uni-code

# uni-code [](https://github.com/Lum1104/uni-code/actions/workflows/ci.yml) [](https://www.npmjs.com/package/@yuxianglin/uni-code) [](https://lum.is-a.dev/uni-code/) **Switch back and forth between Claude Code, Codex, and beyond — nothing gets left behind.** > Want to skip the reading? Everything below, on one screen: **[lum.is-a.dev/uni-code](https://lum.is-a.dev/uni-code/)** You fix a bug in Claude Code, switch to Codex an hour later, and it has never heard of the fix. Every coding agent keeps its sessions on your machine, in its own undocumented format, invisible to every other agent. uni-code indexes all of it into one local store and serves it back to your agents over MCP — so the agent you're in right now can recall what any agent did. ``` You (in Codex): how did we fix that playwright timeout? pretty sure that was a Claude Code session last week ⚙ codex → uni-code · search_history("playwright timeout") ⚙ codex → uni-code · read_session("f3a9c2d1-8") Codex: Found it — oss/atlas-ui, 2026-05-28, in Claude Code: you pinned the webServer timeout in playwright.config.ts and added one retry for chromium. Want me to apply the same fix here? ``` > **Status: experimental.** The core is proven on real stores (numbers below); the surface will still change. v1 covers Claude Code + Codex; more agents follow. ## Install Everything ships as one npm package — `@yuxianglin/uni-code`, Node ≥ 22.5, **zero runtime dependencies** (it runs on Node's built-in SQLite). **Claude Code, as a plugin** — MCP tools plus a recall skill that teaches Claude when to use them: ``` /plugin marketplace add Lum1104/uni-code /plugin install uni-code@uni-code ``` **Claude Code, as a plain MCP server:** ```sh claude mcp add uni-code -- npx -y @yuxianglin/uni-code mcp ``` **Codex:** ```sh codex mcp add uni-code -- npx -y @yuxianglin/uni-code mcp ``` **Cursor or any other MCP client:** stdio server, command `npx`, args `-y @yuxianglin/uni-code mcp`. Then warm the index once (a big history takes ~30 s the first time; every refresh after that is incremental and automatic): ```sh npx @yuxianglin/uni-code ingest ``` Registration goes through each agent's own CLI — uni-code never edits your agents' config, and never writes into their data directories. ## What your agent can do with it The MCP server exposes five tools; agents reach for them on their own whenever you reference past work: | tool | the question it answers | |---|---| | `search_history` | "How did we fix X?" — ranked full-text search over every message, thought, shell command, and tool output, from every agent | | `list_sessions` | "What was I working on yesterday?" — unified recent-session list across agents | | `read_session` | "Show me that session" — one session's timeline, outcomes-end first | | `get_handoff` | "Get me up to speed" — a one-page briefing: goal, where it ended, files touched, commands run (with failures), errors seen | | `resume_session` | "Continue exactly where I left off" — a true cross-agent resume: the source agent's own compaction summary, reused verbatim, plus everything after it | `resume_session` is the flagship: what a native `--resume` reloads is never the full history — it's the last compaction summary plus the live window after it. uni-code finds that structure in the native files and rebuilds it agent-neutrally, so Codex can resume a Claude Code session the way Claude Code itself would. (One asymmetry, stated honestly: Claude Code writes its compaction summaries in plaintext and they're reused verbatim; Codex encrypts its summaries, so resuming *from* a compacted Codex session falls back to its preserved user prompts.) Every query re-ingests changed native files before answering (instant when warm), so results include the session you closed five minutes ago — in the *other* agent. No daemon, nothing to keep running. ## CLI The same store, for humans. Use `npx @yuxianglin/uni-code <cmd>`, or `npm i -g @yuxianglin/uni-code` for a global `uni`: | command | what it does | |---|---| | `uni search <q>` | ranked full-text search — the same engine the agents use | | `uni handoff [id]` | one-page briefing from a session (default: the latest) — pipe it into the next agent | | `uni resume [id]` | full effective context (compact summary + live window) — a cross-agent resume | | `uni sessions` | unified session list across agents, newest first | | `uni log <id>` | timeline of one session by id prefix | | `uni status` | agents found, files discovered, ingested vs pending, store size | | `uni ingest` | incremental, idempotent pull of the native stores | | `uni mcp` | the MCP server (stdio) — what the registrations above run | Flags: `-n/--limit`, `-p/--project` (`.` = current git root), `-a/--agent`, `--all` to include subagent transcripts. ``` $ uni search "playwright" codex projects/webshop 2026-03-29 0195aa1c-7 tool_call:web_search … site:«playwright».dev passWithNoTests «playwright» config official docs … claude-code oss/atlas-ui 2026-05-28 f3a9c2d1-8 tool_call:Bash … npx «playwright» test --project=chromium before pushing the CI fix … ``` ## Real-world numbers Everything below was measured on a real developer machine (MacBook, Apple M4, Node 24) against the author's actual agent history — not synthetic fixtures. | metric | value | |---|---| | agents ingested | 2 (Claude Code, Codex incl. archived sessions) | | native session files | 760 files, **392 MB** on disk | | sessions / events after ingest | 759 sessions, **81,414 events** | | searchable text | **72.4M chars ≈ 18M tokens** | | raw archive (verbatim source lines) | **350.2M chars ≈ 87.5M tokens** | | full first ingest | **~35 s** (~11 MB/s end-to-end) | | incremental re-ingest | **< 1 s** | | warm full-text search | **5–50 ms** per query — ≈ 50 ms for the entire `uni search` process, English and CJK alike | | store size (SQLite + FTS index) | 582 MB | | unparseable lines quarantined | **0** | Token counts use the rough 4-chars-per-token heuristic for code-heavy English (Chinese runs denser, so the true number is higher). Put differently: this one laptop was already sitting on **~87M tokens** of agent work history that no single tool could see across. ## How it works Hub-and-spoke. Native stores are never written; per-agent adapters map each undocumented format into one canonical model; the MCP server and CLI both read the same store. ``` ~/.claude ~/.codex (~/.gemini, ~/.cursor, … later) native stores — READ-ONLY │ │ └────┬─────┘ one-way ingest adapters (tolerant parsers, fixture-tested) ▼ ~/.uni-code/store.db SQLite + FTS5 — canonical sessions & events │ ├──► MCP server search_history · list_sessions · read_session (uni mcp) ├──► CLI status · ingest · sessions · log · search └──► projections handoff bundles, memory distillation (planned) ``` ### Design principles - **Native stores are read-only.** uni-code never writes into an agent's directory. - **No bidirectional sync.** Translating one agent's session into another's native format is N×N, lossy, and breaks on every release. Write-back is always a *generated artifact* an agent consumes on its own terms. - **Lossy-but-useful core + raw sidecar.** The canonical model keeps the common core; every source line survives verbatim in a `raw` column, so no mapping decision is irreversible. - **Tolerant by construction.** Native formats are undocumented and change silently. Malformed lines are quarantined and counted, unknown record types are kept as opaque events — parsing never hard-fails on content. - **The store is a derived cache — that outlives the agents' own memory.** Delete it and re-ingest rebuilds everything the native stores still hold; and since agents prune their own history over time, the store often remembers sessions the agents have already forgotten. - **Local-only, no telemetry.** Transcripts contain secrets. The store is `0600` and nothing ever leaves the machine — the MCP server is stdio to a local process. - **No daemon.** Incremental ingest on invocation, like `git status`. ### Chinese / CJK search built in Most embedded full-text engines silently fail on Chinese: the default tokenizer can't segment CJK text, so a word buried in a sentence is unfindable, and trigram indexes can't serve two-character words (部署, 优化, 隔离 — most Chinese dev vocabulary). uni-code indexes every CJK run as overlapping character bigrams and transforms queries symmetrically, giving exact-substring matching for any CJK term of ≥2 characters, in mixed Chinese/English queries too. English/code text is untouched, and the index migrates itself when the scheme changes. ``` $ uni search "隔离机制" claude-code work/sandbox-runner 2026-07-06 9d41e0b7-3 meta 讨论«隔离机制»的目的和优化方案 ``` ## Roadmap 1. ~~Canonical store, Claude Code + Codex adapters, unified cross-agent search~~ ✅ 2. ~~MCP server + Claude Code plugin — agents recall each other's sessions themselves~~ ✅ 3. ~~**Handoff & resume** — `uni handoff`/`get_handoff` briefings, plus `uni resume`/`resume_session`: cross-agent resume built from the source agent's own compaction summaries and the live window after them~~ ✅ — an optional `--distill` polish pass that shells out to an installed agent (so uni-code itself needs no API key) is still planned. 4. **More adapters** — Gemini CLI, Cursor, opencode, Copilot CLI. `src/adapters/` is the seam; each adapter ships with a synthetic fixture corpus as contract tests. 5. **Instructions/config projection** — one source of truth → `AGENTS.md`, `CLAUDE.md`, `.cursor/rules`, MCP server lists. ## Development ```sh npm run dev -- status # run from source (tsx) npm test # vitest — adapter, store, and MCP protocol tests over fixtures npm run build # tsc → dist/ npx @modelcontextprotocol/inspector node dist/cli.js mcp # poke the MCP server interactively ``` Fixtures in `tests/fixtures/` are **synthetic** — never commit real transcripts.