You start a feature in Claude Code. It stalls on a gnarly type error, so you hand the same repo to Codex, which is better at that kind of grind. Codex fixes it, but now it has no idea what the feature was for, which files you’d already agreed not to touch, or what “done” means here. You re-explain the whole thing from memory. Ten minutes later you switch back, and Claude Code has forgotten too. The code moved forward. The context didn’t.
This is the tax on running more than one coding agent. Each tool keeps its own memory in its own format and its own session, so the moment work crosses from one agent to another, everything except the diff falls on the floor. Keeping context when switching between coding agents means making that context live somewhere outside any single agent, in a form the next one can read without you narrating it.
This article walks through how to do that, using Sharkly as the workflow: the layer that sits above your coding agents and keeps context, progress, blockers, results, and human review visible from request to release. You already have coding agents. The problem here is the seam between them, and it gets wider with every agent you add.
Why context doesn’t travel between agents
Context for a coding task lives in three places, and only one of them is portable.
The first is the instruction file: CLAUDE.md, AGENTS.md, GEMINI.md. Standing rules, conventions, the commands to run tests. The second is session state: the scrollback of what you and the agent just said, what it tried, what it ruled out. The third is the artifact itself, the diff on disk or the branch.
Only the third travels for free. A different agent can read the code, but it can’t read a conversation it wasn’t part of, and it won’t read an instruction file addressed to a different tool. That’s the boundary worth stating plainly: switching agents preserves the code and drops the reasoning. The commit survives. The “why” was in a scrollback buffer one agent saw and the next one never will.
So keeping context across a switch is really two jobs: make the standing rules readable by every agent, and make the live task state exist as something other than one tool’s memory. The next sections take them in order. (If your pain is losing context between runs of the same agent, that’s a related but separate problem, covered in maintaining context across AI sessions.)
Make the standing rules one file every agent reads
Start with the cheap win. Claude Code reads CLAUDE.md, Codex reads AGENTS.md, Gemini CLI reads GEMINI.md. Same job, three filenames. If you maintain them separately, they drift, and the agent you switched to is now following stale rules while you assume it isn’t.
Write the rules once and point the other filenames at it. On macOS or Linux:
# AGENTS.md is the source of truth; the others are aliases
ln -s AGENTS.md CLAUDE.md
ln -s AGENTS.md GEMINI.md
git add AGENTS.md CLAUDE.md GEMINI.md
Now every agent that opens the repo reads the same conventions, and there’s one file to update when they change. Keep it short and factual: the test command, the directories that are off-limits, the review rule, how commits should look. This is the shared contract each agent inherits the instant it starts, no matter which one you switched to.
The failure mode to watch for: putting task-specific detail in these files. The instruction file is for rules that are true across every task in the repo. “We use Vitest, not Jest” belongs here. “Finish the checkout retry logic and don’t touch the auth middleware” does not; it’s true for one task this week and wrong the next. Mixing the two means every agent reads instructions that were meant for a job that’s already shipped.
Carry the working context, not just the rules
The rules file gets a new agent to the starting line. It says nothing about the task in flight: what’s been decided, what’s half-done, what’s still uncertain. That knowledge is exactly what evaporates when you switch, because it only ever lived in the previous agent’s session.
The manual fix is a handoff note. Before you switch agents, have the current one write down where it is: the goal, the files it changed, what it verified, and the one thing it wasn’t sure about. Paste that into the next agent as the first message. It works, and for a single switch it’s enough. The pattern is worth internalizing on its own; the shape of a good one is covered in agent handoff templates.
The failure mode is that the note lives nowhere durable. It’s a paragraph in a terminal you’ll close, or a message you retype each time. Switch back and forth twice and you’re maintaining the handoff note by hand, in your head, across three tools. The context exists, but you’ve become the database it’s stored in. That holds for one task. It does not hold when you’re running several, which is where the DIY approach runs out.
Where the DIY setup stops scaling
Symlinked rules plus a pasted handoff note carries you a long way with one repo and two agents. Add a third agent, a second repo, or a task that spans a day, and the arithmetic turns on you. Every switch is a manual export and re-import. Every task has its own thread of “what’s done” that lives only where the last agent left it. Nothing tells you a backend Agent finished the endpoint the frontend Agent is waiting on, because “telling” was a message in a terminal nobody’s watching.
At that point the fix isn’t a better note. It’s moving the working context off the agents entirely and onto a shared Task that every agent and person reads from and writes back to. A Task in Sharkly holds the goal, the acceptance criteria, the diff, the blockers, and the discussion in one record. Execution, blockers, results, and follow-up return to that Task timeline, so switching agents stops being an export at all. You reassign the Task; the next agent reads the same record the last one wrote to.
This is also where the human-agent split gets clean. Agents research, execute, test, and report to the Task. People set direction, grant authority, and accept the result. Automation stops where team judgment is required, and the record the next worker reads is the same one a reviewer reads. That only works because the context isn’t trapped in a session anymore.
Here’s the honest decision pair. If you run one agent in one terminal on one repo, you don’t need any of this; the context never leaves, so there’s nothing to preserve. Reach for a shared Task the moment context has to survive a switch, whether that switch is agent-to-agent, agent-to-human, or just you tomorrow morning. If you want to keep using several coding agents rather than committing to one ecosystem, that portability is the point: your workflow survives whichever agent you pick next, because the context was never stored inside any of them. That’s also the setup that lets you run Claude Code and Codex together on one codebase without either one going blind at the handoff, and it pairs naturally with worktrees, one checkout per task, so parallel agents don’t collide.
The checklist you can run today
Work through this in order. The first three cost nothing; the fourth is what you graduate to when the first three stop keeping up.
- Unify the rules file. Symlink
CLAUDE.md,AGENTS.md, andGEMINI.mdto one source. Keep it to repo-wide conventions only, no task detail. - Write a handoff note before every switch. Goal, files changed, what was verified, open question. The current agent can draft it; you paste it into the next.
- Decide the switch on the task, not the habit. Match the agent to the work in front of you, using a routing guide rather than defaulting to whichever terminal is open.
- Move context off the agents when notes stop scaling. Once you’re juggling more than a couple of agents or repos, put the goal, state, and review on a shared Task so switching is a reassignment, not a re-explanation.
If you’re already running several agents and re-narrating the same context every time you switch, that’s the problem Sharkly is built around: one place where each agent’s tasks, progress, and results stay visible, so the context outlives the switch.
