{"id":50426412,"url":"https://github.com/farmcan/kage","last_synced_at":"2026-05-31T11:00:57.840Z","repository":{"id":345511225,"uuid":"1186182361","full_name":"farmcan/kage","owner":"farmcan","description":"Local-first desktop and CLI session manager for Claude Code, Codex, and QoderCLI.","archived":false,"fork":false,"pushed_at":"2026-05-28T14:17:37.000Z","size":396,"stargazers_count":5,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-28T15:16:35.068Z","etag":null,"topics":["ai-coding","claude-code","codex","desktop-app","macos","qodercli","session-management"],"latest_commit_sha":null,"homepage":"https://farmcan.github.io/kage/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/farmcan.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-19T11:01:47.000Z","updated_at":"2026-05-28T14:18:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/farmcan/kage","commit_stats":null,"previous_names":["farmcan/agent-session-bridge","farmcan/kage"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/farmcan/kage","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/farmcan%2Fkage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/farmcan%2Fkage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/farmcan%2Fkage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/farmcan%2Fkage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/farmcan","download_url":"https://codeload.github.com/farmcan/kage/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/farmcan%2Fkage/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33728391,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-coding","claude-code","codex","desktop-app","macos","qodercli","session-management"],"created_at":"2026-05-31T11:00:56.936Z","updated_at":"2026-05-31T11:00:57.834Z","avatar_url":"https://github.com/farmcan.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# KAGE\n\n[![CI](https://github.com/farmcan/kage/actions/workflows/ci.yml/badge.svg)](https://github.com/farmcan/kage/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![macOS](https://img.shields.io/badge/macOS-desktop_app-black.svg)](app/)\n\nKAGE is a local-first desktop and CLI session manager for AI coding agents.\n\nIt finds, searches, forks, opens replay stories, and moves coding sessions across `Claude Code`, `Codex`, and `QoderCLI` without asking you to copy-paste transcript context by hand.\n\n\u003e Your AI coding agents already have memory. KAGE makes it searchable, portable, and local.\n\nKAGE 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 macOS app is a thin native desktop shell over the same JSON CLI contract, so transcript parsing and route logic stay in one place.\n\nThe CLI command is `kage`.\nThe 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.\n\nAction language in KAGE is intentionally narrow:\n\n- `Continue` resumes the original session in its native agent.\n- `Fork` creates a new same-agent session from the selected context, so you can branch the work without mutating the original session.\n- `Bridge` converts the session into another agent's native resume format.\n- `Replay story` creates a local, read-only HTML review of what happened in the transcript. It is not a fork.\n\nHomepage: \u003chttps://farmcan.github.io/kage/\u003e\n\nProduct strategy: [KAGE Product Strategy](docs/product-strategy-2026-05-28.md)\n\nArchitecture: [KAGE Architecture Review](docs/architecture-review-2026-05-28.md)\n\nGrowth plan: [KAGE Growth Plan](docs/growth-plan-2026-05-28.md)\n\nGitHub presence: [GitHub Presence Guide](docs/github-presence-guide.md)\n\nRelease checklist: [Release And Launch Checklist](docs/release-launch-checklist.md)\n\nExperimental native macOS desktop app source lives in [app](app/). It includes a main session workspace plus a compact menu bar surface for quick status and actions.\n\n## Screenshots\n\n![KAGE desktop preview](docs/assets/screenshots/kage-desktop-preview.svg)\n\n![KAGE menu bar preview](docs/assets/screenshots/kage-menubar-preview.svg)\n\n## Try It In 60 Seconds\n\nDownload the macOS desktop app:\n\n```text\nhttps://github.com/farmcan/kage/releases/download/v0.1.2/KAGE-0.1.2.dmg\n```\n\nThe desktop app is currently unsigned. On macOS, right-click `KAGE.app`, choose `Open`, and confirm the first launch if Gatekeeper blocks a normal double-click.\n\nInstall the CLI:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/farmcan/kage/main/install.sh | bash\n```\n\nCheck what KAGE can see:\n\n```bash\nkage doctor\nkage sessions\nkage search \"auth\"\n```\n\nBridge a useful session:\n\n```bash\nkage c2x\n```\n\nBuild and open the macOS desktop app from a local checkout:\n\n```bash\nswift build --package-path app\n(cd app \u0026\u0026 ./bundle.sh)\nopen app/.build/release/KAGE.app\n```\n\n## Why It Exists\n\nKAGE is built around three practical workflows.\n\n1. Fork a conversation and keep the useful context.\nYou can branch an existing session, trim it, append one new user message, and continue without rebuilding context from scratch.\n\n2. Bridge between agents.\nYou can move a session between tools like `Claude -\u003e Codex` or `Codex -\u003e Claude` and keep working with a native session file instead of a pasted transcript.\n\n3. Browse local agent memory.\nThe desktop app gives you a project-scoped session list, search, recent messages, and per-session actions without leaving macOS.\n\n## Why People Star It\n\n- You use more than one AI coding agent and want context to move with you.\n- You have old local sessions that are useful but hard to find.\n- You want transcript search without uploading everything to another service.\n- You want resume, bridge, replay, and cleanup flows that are scriptable from a CLI.\n- You want a desktop workspace for local agent memory instead of raw JSONL files.\n\n## Core Examples\n\nBridge a Claude session into Codex:\n\n```bash\nkage c2x\n```\n\nBridge a Codex session into Claude:\n\n```bash\nkage x2c\n```\n\nFork the current Codex session into a new Codex session:\n\n```bash\nkage x2x\n```\n\nFork the current Claude session into a new Claude session:\n\n```bash\nkage c2c\n```\n\nFor same-agent forks, KAGE also prints first-party guidance when the agent already has native support. For example, `c2c` points to `claude --resume \u003csource-session-id\u003e --fork-session`, and `x2x` points to `codex fork \u003csource-session-id\u003e`.\n\nFork or trim before exporting:\n\n```bash\nkage claude qodercli --split-recent 1 --out ./tmp/split.jsonl\nkage claude qodercli --fork \"另外开一个分支，去做 session split\" --out ./tmp/fork.jsonl\n```\n\n## What It Supports\n\n| Source | Target | Default Export | Resume Hint |\n|---|---|---|---|\n| `codex` | `claude` | `claude-session` | `claude --resume ...` |\n| `claude` | `codex` | `codex-session` | `codex resume ...` |\n| `claude` | `claude` | `claude-session` fork | `claude --resume ...` |\n| `codex` | `codex` | `codex-session` fork | `codex resume ...` |\n| `qodercli` | `codex` | `codex-session` | `codex resume ...` |\n| `qodercli` | `claude` | `claude-session` | `claude --resume ...` |\n| `qodercli` | `qodercli` | `qoder-session` fork | `qodercli --cwd ... --resume ...` |\n| `codex` | `qodercli` | `qoder-session` | `qodercli --cwd ... --resume ...` |\n| `claude` | `qodercli` | `qoder-session` | `qodercli --cwd ... --resume ...` |\n\n## Install\n\n### macOS Desktop App\n\nDownload the v0.1.2 DMG from GitHub Releases:\n\n```text\nhttps://github.com/farmcan/kage/releases/download/v0.1.2/KAGE-0.1.2.dmg\n```\n\nThe DMG is unsigned for now. If macOS blocks the first launch, right-click `KAGE.app`, choose `Open`, then confirm.\n\n### CLI\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/farmcan/kage/main/install.sh | bash\n```\n\nThen use:\n\n```bash\nkage c2x\nkage update\n```\n\nTo 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.\n\n### Local Development\n\n```bash\nnpm install\nnpm link\n```\n\nBuild the experimental desktop app:\n\n```bash\nswift build --package-path app\nswift run --package-path app kage-contract-smoke\n(cd app \u0026\u0026 ./bundle.sh)\nopen app/.build/release/KAGE.app\n```\n\nThe app opens a desktop session workspace and also keeps a menu bar item for quick checks.\n\n## Quick Start\n\n```bash\nkage c2x\nkage doctor\nkage sessions --json\nkage search \"resume\"\nkage actions\nkage c2c\nkage c2v\nkage x2c\nkage x2x\nkage x2v\nkage c\nkage q\nkage x\nkage q2q\nkage q2x\nkage q2c\nkage q2v\nkage x2q\nkage c2q\n```\n\n## Practical Test\n\nThe most convincing way to validate KAGE is to resume a real session in one agent, export it, then resume it in another.\n\nFor example, start from a Claude session:\n\n```text\nResume this session with:\nclaude --resume b3b958d7-4ac8-41c4-8660-7b7f654737c6\n```\n\nThen run:\n\n```bash\nkage c2x\n```\n\nIf multiple Claude sessions match the current directory, KAGE will ask you to choose:\n\n```text\nMultiple Claude sessions match the current directory:\n1. a=100,b=200,a+b=?\n   2026-03-22T14:49:54.695Z  b3b958d7-4ac8-41c4-8660-7b7f654737c6\n   /Users/you/.claude/projects/-Users-you-wrksp-agentkit/b3b958d7-4ac8-41c4-8660-7b7f654737c6.jsonl\n2. a=1,b=2,a+b=?\n   2026-03-22T14:49:13.552Z  a3ac68c7-76f4-44ef-a619-f04f19b49c83\n   /Users/you/.claude/projects/-Users-you-wrksp-agentkit/a3ac68c7-76f4-44ef-a619-f04f19b49c83.jsonl\n3. 查看并了解当前代码\n   2026-03-20T13:26:27.783Z  33d6decd-7776-4fba-b1d6-50b904c07010\n   /Users/you/.claude/projects/-Users-you-wrksp-agentkit/33d6decd-7776-4fba-b1d6-50b904c07010.jsonl\nSelect a session [1-3]: 1\n/Users/you/.codex/sessions/2026/03/22/rollout-b3b958d7-4ac8-41c4-8660-7b7f654737c6.jsonl\nRun:\ncodex resume b3b958d7-4ac8-41c4-8660-7b7f654737c6\n```\n\nFinally, resume it in Codex:\n\n```bash\ncodex resume b3b958d7-4ac8-41c4-8660-7b7f654737c6\n```\n\nIf the export worked, Codex opens in the same project directory and continues from the imported context.\n\n## Route Aliases\n\n| Alias | Meaning | Default Export |\n|---|---|---|\n| `x2x` | `codex -\u003e codex` | `codex-session` |\n| `x2c` | `codex -\u003e claude` | `claude-session` |\n| `x2q` | `codex -\u003e qodercli` | `qoder-session` |\n| `x2v` | `codex -\u003e visualize` | `session-story-html` |\n| `c2c` | `claude -\u003e claude` | `claude-session` |\n| `c2x` | `claude -\u003e codex` | `codex-session` |\n| `c2q` | `claude -\u003e qodercli` | `qoder-session` |\n| `c2v` | `claude -\u003e visualize` | `session-story-html` |\n| `q2q` | `qodercli -\u003e qodercli` | `qoder-session` |\n| `q2x` | `qodercli -\u003e codex` | `codex-session` |\n| `q2c` | `qodercli -\u003e claude` | `claude-session` |\n| `q2v` | `qodercli -\u003e visualize` | `session-story-html` |\n\nAgent shorthands:\n\n- `x`: `codex`\n- `c`: `claude`\n- `q`: `qodercli`\n\nYou can also run `kage x`, `kage c`, or `kage q` to list matching sessions for the current directory without exporting.\n\nUse explicit source and target instead of aliases:\n\n```bash\nkage codex claude\nkage qodercli codex\nkage claude qodercli\n```\n\nIf you mistype a route alias such as `q2q`, KAGE reports the unknown alias and prints the supported alias list.\n\n## Options\n\n```text\n--agent \u003cagent\u003e\n--target \u003cagent\u003e\n--session \u003cpath\u003e\n--session-id \u003cid\u003e\n--out \u003cpath\u003e\n--output-dir \u003cdir\u003e\n--export codex-session|claude-session|qoder-session|session-story-html\n--split-recent \u003cn\u003e\n--fork \u003cprompt\u003e\n--fork-file \u003cpath\u003e\n--preview\n--run\n--older-than \u003cduration\u003e\n--since \u003cdate|duration\u003e\n--until \u003cdate|duration\u003e\n--project \u003cpath\u003e\n--include-subdirs\n--stdout\n--json\n--version\n--help\n```\n\nUseful patterns:\n\nCheck the local agent setup:\n\n```bash\nkage doctor\nkage doctor --json\n```\n\nList current-project sessions across agents:\n\n```bash\nkage sessions\nkage sessions --agent claude --json\nkage sessions --include-subdirs\n```\n\nGenerate menu-bar friendly actions and run one:\n\n```bash\nkage actions --json\nkage run-action resume:claude:\u003csession-id\u003e\n```\n\nFind a past session by content, agent, date, or project:\n\n```bash\nkage search \"auth\"\nkage search \"resume\" --agent codex --since 7d\nkage search --project ~/wrksp/kage --json\nkage search --project ~/wrksp/kage --include-subdirs --json\n```\n\nUpgrade an existing install:\n\n```bash\nkage update\n```\n\nSpecify a session directly:\n\n```bash\nkage --agent claude --target codex --session ~/.claude/projects/.../session.jsonl\n```\n\nResolve by session id:\n\n```bash\nkage --agent codex --target claude --session-id \u003csession-id\u003e\n```\n\nWrite to a specific location:\n\n```bash\nkage x2q --out ./tmp/qoder-session.jsonl --json\n```\n\nWrite using default filenames into a directory:\n\n```bash\nkage c2x --output-dir ./tmp/exports --json\n```\n\nShow the export body instead of writing files:\n\n```bash\nkage q2c --stdout\n```\n\nPreview a transformed export without writing files:\n\n```bash\nkage x2q --preview\n```\n\nWrite the export and launch the generated resume command:\n\n```bash\nkage c2x --run\n```\n\nClean duplicate installed exports. The default is a dry run; deletion requires `--confirm`.\n\n```bash\nkage clean\nkage clean --older-than 7d\nkage clean --confirm\n```\n\nGenerate shell completions:\n\n```bash\nkage completions zsh\n```\n\nGenerate a local HTML story replay for a session:\n\n```bash\nkage c2v --session ~/.claude/projects/.../session.jsonl --out ./tmp/session-story.html\nopen ./tmp/session-story.html\n```\n\nThe same shortcut exists for the other agents:\n\n```bash\nkage x2v\nkage q2v\n```\n\nThe story export is a standalone HTML file designed for local review. It turns the session into a pixel-style stage play:\n\n- `Human Input` routes the agent into the human briefing room.\n- `LLM Thinking` and `Agent Commentary` send the agent into the reasoning core.\n- Each tool becomes its own room instead of sharing one generic workshop.\n- Playback controls support replay plus `0.5x / 1x / 1.5x / 2x / 3x`.\n\nImplementation choices:\n\n- `Anime.js` drives room-to-room motion and playback sequencing.\n- `PixiJS` is still loaded for the visual layer, but the current map scene is DOM-first for easier room layout control.\n- The HTML is self-contained, so there is no build step after export.\n\n## Session Resolution\n\nThe CLI does not blindly use the global latest session.\n\nIt finds sessions for the current working directory. If nothing matches, export commands fail and ask you to provide `--session` or `--session-id`.\n\nIf multiple matching sessions exist for the current directory:\n\n- interactive terminals get a numbered chooser\n- chooser entries are shown as spaced cards with path, session id, and recent user-message context\n- 交互式选择器会用带留白的卡片样式展示候选项，并附带路径、session id 和最近几条用户消息\n- chooser titles prefer the first real user prompt instead of bootstrap metadata like Codex environment context\n- chooser titles and paths stay untruncated so similar sessions remain distinguishable\n- chooser entries include the most recent real user messages so you can tell similar sessions apart\n- non-interactive runs fail clearly and ask for `--session-id`\n- malformed JSONL rows are ignored during session discovery so one corrupted transcript does not block the whole scan\n\nMatching rules:\n\n- `codex`: `session_meta.payload.cwd`\n- `claude`: `cwd` from transcript rows\n- `qodercli`: `working_dir`\n\n## Export Behavior\n\n`codex-session` installs directly into:\n\n```text\n~/.codex/sessions/YYYY/MM/DD/...\n```\n\nDefault Codex export filenames are stable for the session id, such as `rollout-\u003csession-id\u003e.jsonl`, so repeating the same bridge command overwrites the previous installed export instead of creating duplicates. Fork exports still get a fresh session id.\n\nWhen the export is installed there, the CLI prints:\n\n```text\nRun:\ncodex resume \u003csession-id\u003e\n```\n\n`claude-session` installs directly into:\n\n```text\n~/.claude/projects/\u003cproject-key\u003e/...\n```\n\nWhen the export is installed there, the CLI prints:\n\n```text\nRun:\nclaude --resume \u003csession-id\u003e\n```\n\n`qoder-session` installs directly into:\n\n```text\n~/.qoder/projects/\u003cproject-key\u003e/...\n```\n\nWhen the export is installed there, the CLI prints:\n\n```text\nRun:\nqodercli --cwd \u003cworking-dir\u003e --resume \u003csession-id\u003e\n```\n\nQoderCLI resume support requires a recent QoderCLI release. It is verified with `qodercli 1.0.0`.\n\nIf `qodercli` is not installed, install the latest QoderCLI with one of the official methods:\n\n```bash\ncurl -fsSL https://qoder.com/install | bash\nbrew install qoderai/qoder/qodercli --cask\nnpm install -g @qoder-ai/qodercli\n```\n\nTo upgrade an existing install:\n\n```bash\nqodercli update\ncurl -fsSL https://qoder.com/install | bash -s -- --force\n```\n\nIf you use `--out` or `--output-dir`, missing parent directories are created automatically.\n\n## Forking And Trimming\n\nThe export pipeline can trim or branch a conversation before writing it:\n\n- `--split-recent N`: keep only the most recent `N` real user turns and everything after them\n- `--fork \"...\"`: append one new user message before export\n- `--fork-file path.txt`: read that message from a file\n\n## Current Scope\n\n- exports visible transcript history only\n- does not preserve hidden reasoning, tool runtime state, or UI state\n- `qoder-session` is implemented as a best-effort native export format, with resume support verified on `qodercli 1.0.0`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffarmcan%2Fkage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffarmcan%2Fkage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffarmcan%2Fkage/lists"}