KAGE

Find, fork, replay, and move AI coding sessions across Claude Code, Codex, and QoderCLI.

KAGE treats coding-agent sessions as local project assets. It reads sessions for the current working directory, normalizes them into one internal model, and can export, preview, replay, or resume them in another agent's native format.

The CLI command is kage.
The name comes from the "shadow clone" idea: a useful coding agent should be able to fork its current working context into parallel branches instead of forcing every task through one linear loop.

Homepage: https://farmcan.github.io/kage/

Product plan: macOS menu bar app

Why It Exists

KAGE is built around two practical workflows.

1. Fork a conversation and keep the useful context.
   You can branch an existing session, trim it, append one new user message, and continue without rebuilding context from scratch.

2. Bridge between agents.
   You can move a session between tools like Claude -> Codex or Codex -> Claude and keep working with a native session file instead of a pasted transcript.

Core Examples

Bridge a Claude session into Codex:

kage c2x

Bridge a Codex session into Claude:

kage x2c

Fork the current Codex session into a new Codex session:

kage x2x

Fork the current Claude session into a new Claude session:

kage c2c

For same-agent forks, KAGE also prints first-party guidance when the agent already has native support. For example, c2c points to claude --resume <source-session-id> --fork-session, and x2x points to codex fork <source-session-id>.

Fork or trim before exporting:

kage claude qodercli --split-recent 1 --out ./tmp/split.jsonl
kage claude qodercli --fork "另外开一个分支，去做 session split" --out ./tmp/fork.jsonl

What It Supports

Install

curl -fsSL https://raw.githubusercontent.com/farmcan/kage/main/install.sh | bash

Then use:

kage c2x
kage update

To upgrade a previous install from this script, run the same install command again. The installer removes the old agent-session-bridge global package if it is present, then reinstalls KAGE from the latest main tarball.

For local development:

npm install
npm link

Quick Start

kage c2x
kage c2c
kage c2v
kage x2c
kage x2x
kage x2v
kage c
kage q
kage x
kage q2q
kage q2x
kage q2c
kage q2v
kage x2q
kage c2q

Practical Test

The most convincing way to validate KAGE is to resume a real session in one agent, export it, then resume it in another.

For example, start from a Claude session:

Resume this session with:
claude --resume b3b958d7-4ac8-41c4-8660-7b7f654737c6

Then run:

kage c2x

If multiple Claude sessions match the current directory, KAGE will ask you to choose:

Multiple Claude sessions match the current directory:
1. a=100,b=200,a+b=?
   2026-03-22T14:49:54.695Z  b3b958d7-4ac8-41c4-8660-7b7f654737c6
   /Users/you/.claude/projects/-Users-you-wrksp-agentkit/b3b958d7-4ac8-41c4-8660-7b7f654737c6.jsonl
2. a=1,b=2,a+b=?
   2026-03-22T14:49:13.552Z  a3ac68c7-76f4-44ef-a619-f04f19b49c83
   /Users/you/.claude/projects/-Users-you-wrksp-agentkit/a3ac68c7-76f4-44ef-a619-f04f19b49c83.jsonl
3. 查看并了解当前代码
   2026-03-20T13:26:27.783Z  33d6decd-7776-4fba-b1d6-50b904c07010
   /Users/you/.claude/projects/-Users-you-wrksp-agentkit/33d6decd-7776-4fba-b1d6-50b904c07010.jsonl
Select a session [1-3]: 1
/Users/you/.codex/sessions/2026/03/22/rollout-b3b958d7-4ac8-41c4-8660-7b7f654737c6.jsonl
Run:
codex resume b3b958d7-4ac8-41c4-8660-7b7f654737c6

Finally, resume it in Codex:

codex resume b3b958d7-4ac8-41c4-8660-7b7f654737c6

If the export worked, Codex opens in the same project directory and continues from the imported context.

Route Aliases

Agent shorthands:

• x: codex
• c: claude
• q: qodercli

You can also run kage x, kage c, or kage q to list matching sessions for the current directory without exporting.

Use explicit source and target instead of aliases:

kage codex claude
kage qodercli codex
kage claude qodercli

If you mistype a route alias such as q2q, KAGE reports the unknown alias and prints the supported alias list.

Options

--agent <agent>
--target <agent>
--session <path>
--session-id <id>
--out <path>
--output-dir <dir>
--export codex-session|claude-session|qoder-session|session-story-html
--split-recent <n>
--fork <prompt>
--fork-file <path>
--preview
--run
--older-than <duration>
--stdout
--json
--version
--help

Useful patterns:

Upgrade an existing install:

kage update

Specify a session directly:

kage --agent claude --target codex --session ~/.claude/projects/.../session.jsonl

Resolve by session id:

kage --agent codex --target claude --session-id <session-id>

Write to a specific location:

kage x2q --out ./tmp/qoder-session.jsonl --json

Write using default filenames into a directory:

kage c2x --output-dir ./tmp/exports --json

Show the export body instead of writing files:

kage q2c --stdout

Preview a transformed export without writing files:

kage x2q --preview

Write the export and launch the generated resume command:

kage c2x --run

Clean duplicate installed exports. The default is a dry run; deletion requires --confirm.

kage clean
kage clean --older-than 7d
kage clean --confirm

Generate shell completions:

kage completions zsh

Generate a local HTML story replay for a session:

kage c2v --session ~/.claude/projects/.../session.jsonl --out ./tmp/session-story.html
open ./tmp/session-story.html

The same shortcut exists for the other agents:

kage x2v
kage q2v

The story export is a standalone HTML file designed for local review. It turns the session into a pixel-style stage play:

• Human Input routes the agent into the human briefing room.
• LLM Thinking and Agent Commentary send the agent into the reasoning core.
• Each tool becomes its own room instead of sharing one generic workshop.
• Playback controls support replay plus 0.5x / 1x / 1.5x / 2x / 3x.

Implementation choices:

• Anime.js drives room-to-room motion and playback sequencing.
• PixiJS is still loaded for the visual layer, but the current map scene is DOM-first for easier room layout control.
• The HTML is self-contained, so there is no build step after export.

Session Resolution

The CLI does not blindly use the global latest session.

It finds sessions for the current working directory. If nothing matches, export commands fail and ask you to provide --session or --session-id.

If multiple matching sessions exist for the current directory:

• interactive terminals get a numbered chooser
• chooser entries are shown as spaced cards with path, session id, and recent user-message context
• 交互式选择器会用带留白的卡片样式展示候选项，并附带路径、session id 和最近几条用户消息
• chooser titles prefer the first real user prompt instead of bootstrap metadata like Codex environment context
• chooser titles and paths stay untruncated so similar sessions remain distinguishable
• chooser entries include the most recent real user messages so you can tell similar sessions apart
• non-interactive runs fail clearly and ask for --session-id
• malformed JSONL rows are ignored during session discovery so one corrupted transcript does not block the whole scan

Matching rules:

• codex: session_meta.payload.cwd
• claude: cwd from transcript rows
• qodercli: working_dir

Export Behavior

codex-session installs directly into:

~/.codex/sessions/YYYY/MM/DD/...

Default Codex export filenames are stable for the session id, such as rollout-<session-id>.jsonl, so repeating the same bridge command overwrites the previous installed export instead of creating duplicates. Fork exports still get a fresh session id.

When the export is installed there, the CLI prints:

Run:
codex resume <session-id>

claude-session installs directly into:

~/.claude/projects/<project-key>/...

When the export is installed there, the CLI prints:

Run:
claude --resume <session-id>

qoder-session installs directly into:

~/.qoder/projects/<project-key>/...

When the export is installed there, the CLI prints:

Run:
qodercli --cwd <working-dir> --resume <session-id>

QoderCLI resume support requires a recent QoderCLI release. It is verified with qodercli 1.0.0.

If qodercli is not installed, install the latest QoderCLI with one of the official methods:

curl -fsSL https://qoder.com/install | bash
brew install qoderai/qoder/qodercli --cask
npm install -g @qoder-ai/qodercli

To upgrade an existing install:

qodercli update
curl -fsSL https://qoder.com/install | bash -s -- --force

If you use --out or --output-dir, missing parent directories are created automatically.

Forking And Trimming

The export pipeline can trim or branch a conversation before writing it:

• --split-recent N: keep only the most recent N real user turns and everything after them
• --fork "...": append one new user message before export
• --fork-file path.txt: read that message from a file

Current Scope

• exports visible transcript history only
• does not preserve hidden reasoning, tool runtime state, or UI state
• qoder-session is implemented as a best-effort native export format, with resume support verified on qodercli 1.0.0