Your AI Coding Agent Has Amnesia. I Built Handoff So It Stops Starting From Zero.

Your AI agent can write thousands of lines of code, refactor entire systems, and reason through complicated architectural decisions. But close the session, open another one, and suddenly you're explaining the same project all over again.

There's something fundamentally broken about that workflow.

I've been spending a considerable amount of time working with AI coding agents. Claude Code, Codex, Gemini CLI, Antigravity. Different models, different capabilities, different strengths.

But they all expose a remarkably similar problem.

The code survives. The context doesn't.

That's why I built Handoff, an open-source, agent-agnostic skill designed to preserve the operational context of an AI coding session and carry it into the next one.

One Markdown file. Three workflows. No complicated infrastructure.

The problem between sessions

Imagine you're working on a backend service.

You've spent the last few hours with your AI agent implementing a feature. You've discussed architectural decisions, rejected certain approaches, established constraints, and identified edge cases.

You've also discovered that:

• A particular API contract absolutely cannot change.
• One migration must wait for approval.
• The integration tests require an environment you don't currently have.
• A specific module contains an unfinished implementation.
• The next logical step is fixing an idempotency issue before proceeding.

Your agent understands all of this.

At least, within the current session.

Then you close your terminal.

The next morning, you open a new session and type:

Continue where we left off.

Except your new agent doesn't actually know where you left off.

It can inspect the repository. It can read the code. It can examine Git history.

But here's the problem:

Git tells you what changed. It doesn't reliably tell you why a decision was made, what remains unresolved, or what the user explicitly told the agent not to touch.

Your new agent might reconstruct some of that context.

Or it might confidently make a different decision.

And now you're spending the first part of your session correcting something you already resolved yesterday.

Congratulations. You've invented an onboarding process for an engineer who gets amnesia every time you close the terminal.

That's not the kind of automation I signed up for.

More Context Isn't Always the Answer

The obvious response is to give agents more context.

Bigger context windows. Longer conversation histories. More persistent memory. More documentation.

Those capabilities certainly help.

But they don't necessarily solve the underlying problem.

Context availability and context relevance are two different engineering concerns.

A conversation containing thousands of messages might preserve everything that happened.

But what does the next agent actually need?

Probably not the entire conversation.

It needs to know:

1. What are we trying to accomplish?
2. What has already been completed?
3. Which decisions and constraints must remain intact?
4. What was actually verified?
5. What's the next concrete action?

I didn't want to build another elaborate memory system with vector databases, embeddings, retrieval pipelines, and background synchronization.

Not because those technologies are inherently bad.

Because none of them are necessary to solve this particular problem.

Sometimes, the most effective architecture is the one that refuses to introduce unnecessary moving parts.

Introducing Handoff

Handoff is an open-source Agent Skill that transfers working context between AI coding sessions through a single file: HANDOFF.md.

At the end of a session, your agent captures the information the next session needs.

At the beginning of the next session, your agent reads that information and resumes from the first unfinished step.

The file lives at the root of your repository.

No proprietary state format.

No database.

No dedicated memory server.

No dependency on a particular model provider.

Just structured Markdown that a human or an AI agent can understand.

The repository is available here:

github.com/YourAKShaw/handoff

And the philosophy behind it is simple:

Hold only what the next session needs, point to everything else, and never carry secrets.

How Handoff Actually Works

I designed Handoff around three explicit workflows.

1. Bootstrap: Establish Continuity

When you introduce Handoff to a repository, the bootstrap workflow creates its initial HANDOFF.md.

It also establishes a rule in the repository's agent instructions, such as AGENTS.md, CLAUDE.md, or GEMINI.md.

The rule tells subsequent agents to read the handoff before exploring the rest of the repository.

A state file nobody reads is just another abandoned piece of documentation.

Handoff needs to become part of the agent's operating procedure, not something it occasionally discovers.

2. Save: Preserve What Matters

When you're ready to end a session, you can ask the agent to save a handoff.

For example:

/handoff

Or simply:

Update the handoff.

The agent examines the current repository state, recent commits, completed work, unfinished tasks, verification results, and relevant decisions.

Then it rewrites HANDOFF.md.

It doesn't append another session transcript.

It doesn't accumulate an endless historical record.

It replaces outdated information with the current state.

Finished tasks disappear from the active briefing. New constraints replace obsolete ones. Unanswered questions remain visible.

The handoff stays short, ideally under approximately 80 lines.

If repository conventions and user permissions allow it, the agent can also commit the file alongside the handoff-related changes, making the state available through version control.

3. Resume: Continue Instead of Rediscovering

When a fresh session begins, the agent reads HANDOFF.md.

But it doesn't blindly trust that the file represents reality.

It checks the working branch, Git status, and recent commits against the recorded state.

If something changed between sessions, the mismatch should be surfaced before proceeding.

Once the state is reconciled, the agent follows the recorded constraints and starts with the first actionable next step.

Instead of exploring the entire repository just to understand what happened yesterday, it opens the files relevant to the unfinished work.

A clear starting point for the next session.

What Goes Inside HANDOFF.md?

Every handoff follows five sections.

Goal Right Now

What are we currently trying to accomplish?

This section records the immediate objective and the constraints that govern the work.

Not the project's entire product roadmap.

Just the relevant goal and the decisions that must survive the session boundary.

Where Things Stand

What's already finished?

Which branch are we working on?

What checks actually ran?

This distinction is especially important for AI-assisted engineering.

An agent saying something should work is not equivalent to having executed the tests.

Handoff explicitly separates verified results from assumptions and untested changes.

Next Steps

What should the next agent do first?

These aren't vague reminders like "continue backend development."

They're actionable instructions pointing to a file, command, or unresolved implementation.

The next session shouldn't need a detective to reconstruct the task.

Open Questions

What's waiting for a decision?

Perhaps the user needs to approve a migration.

Perhaps an external dependency is blocking progress.

Rather than guessing, the agent preserves the unresolved question.

Gotchas

What could trip up the next session?

Environment limitations, commands requiring special flags, problematic dependencies, or repository conventions that aren't immediately obvious.

These are the details that repeatedly consume engineering time when they're forgotten.

A Practical Example

Let's say we're implementing a subscription renewal endpoint.

An illustrative HANDOFF.md might look something like this:

# Session handoff

Read this first in every new session; rewrite it when asked
to save a handoff.

Last updated: 2026-11-04

## Goal right now

Complete the subscription renewal endpoint.

Preserve the existing API response contract.
Do not modify payment migrations without approval.

## Where things stand

- Branch: feat/subscription-renewal (remote origin)
- Done: Request validation implemented.
- Checks: npm run test:unit passed.
- Integration tests: Not run.

## Next steps

1. Open src/billing/renewal.service.ts.
   Implement idempotency handling for duplicate requests.

2. Add regression tests for repeated renewal attempts.

3. Run npm run test:unit and report results.

## Open questions

- Should failed payment retries require manual approval?

## Gotchas

- Integration tests require unavailable test credentials.
- Do not alter the existing payment response schema.

That's it.

A fresh agent can understand the immediate objective, identify unfinished work, avoid known mistakes, and distinguish tested behavior from unverified behavior.

It might still need additional information.

That's fine.

The point isn't to eliminate repository exploration entirely.

It's to eliminate unnecessary rediscovery.

The best handoff isn't the one that remembers everything. It's the one that makes the next correct action obvious.

Why Agent-Agnostic Design Matters

Here's another problem I've noticed in AI development workflows.

People increasingly work across multiple coding agents.

You might prefer Claude Code for one task, Codex for another, and Gemini CLI for something else.

Sometimes that's because of capability differences.

Sometimes it's cost.

Sometimes it's rate limits.

Sometimes you simply want another model to evaluate an implementation.

Whatever the reason, switching agents shouldn't mean rebuilding your project context.

Handoff is intentionally designed around plain Markdown rather than a proprietary conversation format.

The same HANDOFF.md can be read by Claude Code, Codex, Gemini CLI, Antigravity, Grok, or another file-capable agent.

The agent-specific part is the integration: installing the skill where supported and configuring instructions to read the file.

The project state itself remains portable.

This is a distinction I care about.

Your development workflow shouldn't depend on one model remembering what another model already figured out.

The repository should own the continuity.

The agents should consume it.

The Security Problem With Persistent Context

There is an uncomfortable side to giving AI agents persistent context.

You're asking an agent to write information to a file that may eventually be committed, pushed, copied, or exposed.

That creates a security boundary.

If the agent starts recording API keys, authentication tokens, private credentials, or sensitive user data, your convenient handoff mechanism becomes a liability.

So Handoff explicitly instructs agents never to record secrets, one-time codes, passwords, private keys, or unnecessary personal information.

It also avoids copying large amounts of existing repository content into the handoff.

Instead, it points to the relevant files.

A Markdown file is editable.

Someone could modify it between sessions. It could become stale. It could even contain malicious instructions.

That's why the resume workflow checks the recorded state against the repository and treats newer user instructions as authoritative when they conflict with the handoff.

To be clear, these are workflow safeguards, not a security sandbox or a guarantee against prompt injection.

A handoff file should never be treated as an unquestionable source of authority.

Persistent context should improve continuity.

It shouldn't quietly expand an agent's permissions or override the human directing the work.

Engineering the Skill, Not Just the Prompt

I also wanted Handoff to be more than an interesting Markdown template.

The repository contains a structured Agent Skill with separate resources for saving, resuming, and bootstrapping sessions.

The implementation includes:

• A SKILL.md entry point defining when and how the skill operates.
• Dedicated workflow instructions for the three operations.
• A documented handoff format and capture rules.
• Reusable templates and agent instruction snippets.
• A Python package validator and regression tests.

The validator uses Python's standard library and checks the skill manifest, required files, local references, and resource reachability.

It doesn't claim to prove that an AI agent will behave correctly.

That would require a different evaluation setup.

But it does help prevent avoidable packaging and documentation errors.

Validate what you can measure. Be explicit about what you haven't measured.

It's tempting to turn every AI project into a grand claim about reliability.

I'd rather build a small mechanism, document its limits, and make the behavior inspectable.

Getting Started

If you work with coding agents, Handoff is designed to be simple to introduce.

Option 1: Install With the Skills CLI

For supported agents, install the skill globally using:

npx skills add YourAKShaw/handoff --global

Option 2: Clone It for Claude Code

mkdir -p ~/.claude/skills

git clone https://github.com/YourAKShaw/handoff.git \
  ~/.claude/skills/handoff

Once installed, the skill can be invoked through /handoff in Claude Code.

Option 3: Use One Shared Installation

For a multi-agent workflow, clone one shared copy:

git clone https://github.com/YourAKShaw/handoff.git \
  ~/.agents/skills/handoff

Then configure the relevant agent-specific skill directories and global instructions.

The repository includes a detailed agent setup guide for this.

One important detail: installing the skill alone isn't always enough to guarantee automatic session resumption.

Agents also need the appropriate instructions to read HANDOFF.md when opening a repository.

Handoff includes those instructions as a reusable snippet.

At the end of a session:

Update the handoff.

At the beginning of the next:

Continue.

The skill doesn't run a hidden background service or automatically intercept every session shutdown.

Saving is explicitly triggered, and resuming depends on the agent reading the handoff.

I prefer being clear about that instead of pretending the system does more than it actually does.

What Handoff Doesn't Try to Solve

I think it's important to define the boundaries of a tool, especially when building for AI agents.

Handoff is not a replacement for Git.

It doesn't replace specifications, architectural decision records, test suites, or project documentation.

It doesn't preserve an agent's internal reasoning.

It doesn't guarantee that a different model will make exactly the same decisions.

And it cannot reconstruct information that was never captured.

Handoff is designed to solve one narrower problem:

Preserving the smallest useful operational state required to continue work across session boundaries.

You could add semantic search, event logs, automated summaries, contextual retrieval, task graphs, or distributed state synchronization.

Some projects might need those capabilities.

But the existence of a more complicated architecture doesn't automatically make it a better one.

For most single-repository coding workflows, a well-maintained handoff file is a sensible starting point.

If the problem eventually outgrows that model, you can measure the gaps and introduce the appropriate mechanisms.

That's how I prefer to engineer systems.

Start with a concrete failure mode.

Build the smallest defensible solution.

Measure its limitations.

Add complexity when the evidence justifies it.

Not before.

The Bigger Picture: AI Agents Need Operational Discipline

Handoff is part of a broader engineering philosophy I've been exploring through my open-source work.

We're getting remarkably good at making AI agents generate code.

But code generation is only one part of software engineering.

Real engineering also requires continuity, verification, constraint management, architectural judgment, and the ability to resume unfinished work without introducing regressions.

An agent that produces an impressive implementation but forgets critical decisions during the next session is still creating operational friction.

And friction compounds.

Especially when you're working across multiple repositories, multiple models, and multiple active development sessions.

I've been building tools and frameworks around different parts of this problem: better prompting, stronger engineering judgment, structured execution, and more reliable workflows.

Handoff addresses session continuity, an ordinary but costly gap.

It's not the flashiest problem in AI engineering.

But it's exactly the kind of problem that determines whether these tools remain impressive assistants or become dependable parts of an engineering workflow.

The real measure of an AI agent isn't just how much work it can complete in one session. It's how reliably that work carries forward into the next.

Handoff Is Open Source

I've released Handoff under the MIT license.

The repository includes the complete skill, workflows, references, templates, installation instructions, validator, and tests.

If you regularly use AI coding agents and find yourself repeating constraints, reconstructing decisions, or reminding the next session what remains unfinished, this is the problem I built it to address.

You can explore the implementation, try it in your own repositories, inspect the instructions, suggest improvements, or contribute directly.

GitHub: YourAKShaw/handoff

I would be particularly interested in how the handoff format holds up across different agents and longer-running engineering projects.

Because making a system work in one controlled scenario is relatively easy.

Making it consistently useful across real development workflows is where the interesting engineering begins.

Handoff is built to preserve what was decided, what was verified, and what needs to happen next. The next session should continue the work, not restart the conversation.

Built by Ayush Kumar Shaw (@YourAKShaw). Open source, MIT licensed, and available on GitHub.