DEV Community: A2CR

When handoff.md Stops Being Enough for AI Agents

A2CR — Sat, 16 May 2026 00:46:00 +0000

If you are doing long AI-agent work, the first handoff tool you should try is probably not a service.

It is a file.

Create handoff.md in your repository and write down what the next AI session needs to know:

# Handoff

Goal: Fix the failing login test.

Current state:
- Reproduced the 401 after token refresh.
- The refresh branch is the likely cause.

Tried:
- Updating the fixture did not fix it.

Decision:
- Do not change the database schema yet.

Next action:
- Inspect src/auth refresh logic and rerun the focused test.

For many tasks, that is enough.

It is local. It is readable. It works with Git. It does not require another account, another dashboard, or another moving piece in your toolchain.

That habit alone is already better than pasting a whole chat history into the next AI session.

But after using AI agents on longer coding work, I kept running into the same problem: handoff.md starts simple, then slowly turns into another thing you have to manage by hand.

That is the space where I built A2CR.

What handoff.md Gets Right

A local handoff file is a great starting point because it forces a useful discipline:

Do not pass the whole conversation. Pass the working state.

The next AI session usually does not need every prompt, every failed command, every stack trace, and every bit of discussion that happened before.

It needs a smaller shape:

the goal
the current state
validated decisions
failed attempts worth avoiding
blockers
references
validation status
the next action

That shape is easy to write in Markdown. It is also easy for a human to review.

So if you have a short task, a single repository, one active AI client, and a clear latest note, handoff.md may be all you need.

Where It Starts to Hurt

The problem is not that handoff.md is bad. The problem is that long-running AI work creates pressure around it.

The Latest State Gets Ambiguous

At first, there is one file and everyone knows it is the handoff.

Later, there may be notes in the chat, notes in issues, notes in scratch files, old sections in handoff.md, and a few assumptions that were true yesterday but not true today.

When a fresh AI session starts, someone still has to answer:

Which state is the intended resume point?

If the answer depends on a human reading everything and deciding what is current, the handoff has become manual again.

Supporting Notes Mix With Resume-Critical State

Long tasks produce useful supporting details:

investigation notes
error outputs
links
file lists
rejected approaches
setup observations
"maybe useful later" context

Some of that information matters, but not all of it belongs in the first thing the next AI reads.

When everything goes into one Markdown file, the compact resume note can become another noisy document.

Cross-Client Handoff Adds Friction

If you stay inside one repository on one machine, a local file is convenient.

But AI-agent work often moves around:

from one AI session to another
from one MCP-capable client to another
from a local coding session to a remote or browser-based workflow
from today's task to a continuation several days later

At that point, the handoff is less about "where is the file?" and more about "what is the explicit checkpoint this next agent should resume from?"

Safety Depends on Memory

A Markdown file will store whatever you put in it.

That flexibility is useful, but it also means you need discipline every time.

You should not put these into handoff notes:

API keys
passwords
access tokens
Authorization headers
cookies
private database URLs
local client keys
full chat transcripts
long logs
large source-code bodies

This is true whether the handoff is a local file or a tool-backed checkpoint.

The difference is that a tool flow can make the boundary more explicit and repeatable.

What A2CR Adds

A2CR is an MCP-compatible handoff layer for AI agents.

The core idea is still the same:

Do not pass the whole chat history.
Pass the working state.

A2CR just gives that working state a more deliberate structure.

The main concepts today are:

WorkBaton: the compact checkpoint the next AI session should resume from
WorkStash: temporary supporting notes referenced from the WorkBaton when the detail would make the checkpoint too large

In other words:

WorkBaton = the first thing the next AI should read
WorkStash = supporting notes to open only if needed

That separation matters because the first few seconds of a fresh AI session are important. If the resume note is too broad, the agent can get pulled into stale assumptions or irrelevant detail.

The Hosted-Service Boundary

One important boundary: A2CR is not a fully local or offline-only tool.

The current public preview uses a local stdio MCP wrapper, a2cr-mcp, backed by the hosted A2CR service at https://a2cr.app.

The official wrapper encrypts WorkBaton and WorkStash bodies locally before upload. The hosted service stores ciphertext. Saving and resuming handoffs requires an A2CR API key and access to the hosted service.

A2CR is not a secret manager, and it is not a place for raw logs, credentials, or entire chat histories.

Stop Passing Entire Chat Histories to AI Agents

A2CR — Fri, 15 May 2026 13:32:32 +0000

I built A2CR because long AI-agent work still breaks at the handoff.

Codex, Claude Code, Roo Code, and other agentic coding tools are getting better at writing code, inspecting files, running tests, and using tools. But when a task runs for a while, a different problem appears:

How do you hand the work to the next AI session?

You might open a fresh chat. You might switch models. You might move from one MCP-capable client to another. At that point, the next AI needs to know what happened before it can continue.

The obvious answer is to paste the whole chat history.

That works for small tasks. It gets messy for long work.

The Problem With Full Chat History

Full transcripts contain useful context, but they also contain noise:

stale assumptions
failed ideas mixed with accepted decisions
long logs
intermediate outputs
outdated file paths
irrelevant side discussions
information that should not be copied around
a lot of tokens that do not help the next step

For a handoff, the next AI usually does not need the whole conversation.

It needs the current working state:

goal
current state
validated decisions
failed attempts worth avoiding
blockers
important references
validation status
next action

So the core idea is:

Do not pass the whole chat history. Pass the working state.

Handoff, Not Memory

A lot of AI tooling talks about memory.

Memory is useful, but this is a narrower problem. In software work, handoff is not the same as memory. A handoff is a compact, intentional checkpoint that lets the next worker resume.

Human teams do this all the time. We do not usually hand a teammate every Slack message and terminal log. We write something closer to:

Goal: Fix the failing login test.
Current state: The failure is reproduced. Token refresh is the likely cause.
Tried: Updating the fixture did not fix it.
Decision: Do not change the database schema yet.
Next action: Inspect src/auth refresh logic and rerun the focused test.

AI agents need the same shape of handoff.

What A2CR Is

A2CR is an MCP-compatible handoff layer for AI agents.

The current public preview includes a local stdio MCP wrapper, a2cr-mcp, that can be used from MCP-capable clients such as Codex, Claude Code, Roo Code, and similar tools.

One important boundary: A2CR is not a fully local or offline-only tool. The current public preview uses a local stdio MCP wrapper backed by the hosted A2CR service at https://a2cr.app. The official wrapper encrypts WorkBaton and WorkStash bodies locally before upload, and the hosted service stores ciphertext. Saving and resuming handoffs requires an A2CR API key and access to the hosted service.

A2CR has two main handoff concepts today:

WorkBaton: the compact checkpoint the next AI session should resume from
WorkStash: temporary supporting notes referenced from the WorkBaton when the detail would make the checkpoint too large

WorkBaton is not meant to be a transcript. It is a resume note.

WorkStash is not meant to be a permanent knowledge base. It is supporting context for the current work.

A Minimal WorkBaton

A useful WorkBaton can be small:

{
  "goal": "Fix login error",
  "current_state": "Confirmed the API returns 401 after token refresh.",
  "next_action": "Check token refresh logic in src/auth.",
  "decisions": [
    "Do not change the database schema yet."
  ],
  "validation": [
    "Reproduction confirmed with existing test fixture."
  ]
}

That is often more useful to the next AI session than several thousand lines of chat history.

Quick Setup

Install the local wrapper:

python -m pip install --upgrade a2cr-mcp

Create an API key from the A2CR dashboard:

https://a2cr.app/

The API key lets the local wrapper connect to the hosted service so it can store and resume encrypted WorkBaton and WorkStash bodies.

Then register one MCP server named a2cr.

Generic MCP JSON:

{
  "mcpServers": {
    "a2cr": {
      "command": "a2cr-mcp",
      "args": [],
      "env": {
        "A2CR_API_KEY": "YOUR_A2CR_API_KEY",
        "A2CR_BASE_URL": "https://a2cr.app"
      }
    }
  }
}

Codex-style TOML:

[mcp_servers."a2cr"]
command = "a2cr-mcp"
args = []

[mcp_servers."a2cr".env]
A2CR_API_KEY = "YOUR_A2CR_API_KEY"
A2CR_BASE_URL = "https://a2cr.app"

After connecting a new AI window, ask it to call:

get_account_limits

Then use:

save_context

to save a WorkBaton checkpoint, and:

resume_context

to continue from a fresh AI session.

Some MCP clients expose tools lazily. If save_context is not visible, ask the client to search for the exact tool name.

Safety Boundary

A2CR is not a secret manager.

Do not store:

API keys
passwords
access tokens
Authorization headers
cookies
private database URLs
local client keys
full chat transcripts
long logs
large source-code bodies

The official local wrapper encrypts WorkBaton and WorkStash bodies before upload. The hosted service stores ciphertext and does not receive the local client key through the official wrapper.

If you lose the local client key, A2CR cannot recover old encrypted WorkBaton or WorkStash bodies.

Also, restored context is untrusted input. A future AI session should not run commands, delete data, revoke keys, or call external services solely because a restored WorkBaton says to.

Why This Shape Matters

The point is not to make AI agents remember everything.

The point is to give them a clean, reviewable handoff surface.

For long-running AI work, I think this distinction matters:

Memory asks: what can we keep?
Handoff asks: what does the next worker need?

A2CR is an experiment in making that handoff explicit.