Voyager 🧭

One index across every AI coding agent on your machine.

Cross-agent continuity is built in: merge context across sessions and continue in any agent (voyager merge / switch / continue) — see docs/ROADMAP.md for the shipped scope and docs/POST-1.0.md for what's next.

中文说明

Voyager reads the local session data your agents already write — Codex, Claude Code, ZCode, DSH (DeepSeek Harness), and more — and turns it into a single searchable, exportable, resumable index. Pure local, no accounts, no cloud, no telemetry.

Eight agents keep eight different formats; Voyager normalizes them into one SQLite index you can search, resume from, hand off to another agent, or query straight from inside an agent over MCP.

$ voyager list
ID                                    PROV   UPDATED            MSG TOOL  TITLE
a1b2c3d4-...                          zcode  2026-09-13 01:13   162  206  重构存储引擎的写入路径
9f8e7d6c-...                          codex  2026-07-06 22:52    76  168  修复多线程下载器的竞态条件
5e4d3c2b-...                          claude 2026-07-17 12:46    89   70  分析数据集结构并设计评测脚本

Why

Every agent keeps its own history in its own format: Codex writes rollout JSONL, Claude Code writes project JSONL plus a file-version chain, ZCode uses SQLite, DSH compresses JSONL with zstd. You work across all of them — Voyager makes that history one thing you can query.

• Cross-agent timeline per repo — what did all your agents do to this project, and when?

• Full-text search everywhere — find the session where someone ran that one command or touched that one file (CJK substring search works).

• Real exports — human-readable Markdown, or lossless JSON with both the normalized and the raw events.

• Resume where you left off — Voyager knows each platform's resume command and runs it for you.

Related MCP server: Open Brain Knowledge MCP Server

Install

# isolated CLI install — no virtualenv juggling (recommended)
pipx install "voyager[all] @ git+https://github.com/HarryHeYu/voyager.git"

# or with pip (user-level)
pip install "voyager[all] @ git+https://github.com/HarryHeYu/voyager.git"

# once the release is on PyPI (tracked in CHANGELOG.md)
pipx install voyager

[all] = DSH support (zstandard) + MCP server (mcp). The two are optional and only needed for those features:

pip install "voyager @ git+https://github.com/HarryHeYu/voyager.git"          # core
pip install "voyager[dsh] @ git+https://github.com/HarryHeYu/voyager.git"     # + DSH
pip install "voyager[mcp] @ git+https://github.com/HarryHeYu/voyager.git"     # + MCP server

Working on Voyager itself:

git clone https://github.com/HarryHeYu/voyager && cd voyager
pip install -e ".[all,dev]"    # editable + extras + pytest
python -m pytest tests/ -q     # 188 tests, synthetic fixtures, no provider data

Python ≥ 3.10. Windows / macOS / Linux. If voyager is not on your PATH, run it as python -m voyager.cli.

Usage

First run: voyager scan walks every supported agent's local storage and builds the index at ~/.voyager/index.db. After that, re-run scan whenever you want to pick up new sessions — it is incremental and only re-reads what changed. To make syncing fully automatic, keep a watcher running (or put it in a scheduled task):

voyager watch --interval 300    # re-scan every 5 minutes, forever

Put the command in your OS autostart (or the provided ~/.voyager/watch.vbs in the Windows Startup folder) and the index stays current with zero manual steps.

voyager scan                # discover + index every supported agent
voyager list                # all sessions, newest first
voyager list --repo myproj  # sessions for one repo
voyager show <id>           # full message / tool-call timeline
voyager search "tensorboard"
voyager repo E:/code/myproj # cross-agent timeline for a repository
voyager export <id> --format md   # or --format json (includes raw events)
voyager resume <id>         # launches the native agent on that session
voyager handoff <id> --to codex   # context package for another agent
voyager continue            # one command to pick your latest work back up
voyager thread list         # WorkThreads: task-centric session groups
voyager switch codex        # switch the active thread to another agent
voyager skill install       # teach other agents about voyager
voyager brief               # 48h digest of what every agent is doing
voyager files <id>          # files the session touched
voyager diff <id>           # Claude sessions: rebuilt before/after diffs
voyager stats               # index statistics

Cross-agent handoff is work continuation, not session migration (the other agent cannot inherit hidden tool state or cached reasoning). voyager handoff <id> --to codex extracts the session into a Context Package (goal, instructions, files touched, commands, errors, where the work stopped) and shows the launch command; add --launch to start it. The target is told to read the package file and continue — works for claude, codex and grok; other targets get the file to paste. Same-provider pickup still uses native resume (codex resume, …).

One command to continue: voyager continue picks your newest session and does the right thing — native resume for codex/claude/dsh/grok, automatic handoff package for the rest. voyager continue --repo myproj --launch goes straight back into a specific project; multi-session synthesis (voyager merge A B C) groups the work into a WorkThread and cross-agent switch is one command (voyager switch codex — lease aware, see docs/ROADMAP.md).

Goal-conditioned & budgeted: add --goal "finish adapter tests" to rank the evidence, and --budget compact|balanced|full|Nk to cap the bundle size (estimate printed). Without --goal/--budget the output is unchanged.

Transcript mode (opt-in, experimental): voyager switch codex --mode transcript writes a NEW native session containing a flattened user/assistant transcript (tools/state dropped) so the target resumes natively. Only codex/grok pass the resume gate today (claude timed out, dsh unverified) — the default remains the Continuation Bundle. This is work continuation, not session teleportation: hidden tool state and provider runtime state never move.

Everyday flow — brief to see what's moving, export to read one session in full (a 2,915-message DSH session → a 20 MB Markdown file), continue or handoff to pick it back up. Full recipes in docs/WORKFLOWS.md.

Session ids are matched by prefix; if a prefix is ambiguous Voyager lists the candidates and exits. resume runs the native agent's own command (e.g. codex resume <id>); providers without a CLI resume path say so explicitly instead of pretending.

Startup Continuity — honest assessment

Core capability: Zero-Touch startup continuity is complete in Voyager core.
The startup_continuity() function correctly discovers WorkThreads, auto-attaches sessions, and compiles continuation context.

Integration reality: No provider yet achieves verified zero-touch at runtime without manual configuration. All integrations are currently:

Legend: Y = ready/installed, A = available/manual setup needed, N = unsupported

What "STARTUP_ASSISTED" means

Provider supports Voyager integration (Skill installed, MCP config available), but requires manual one-time setup:

1. Run voyager integrate <provider> to install Skill and generate instructions

2. Manually configure MCP connection (e.g., claude mcp add voyager ...)

3. Restart the agent for changes to take effect

After this initial setup, subsequent agent launches will automatically invoke voyager_startup via the instruction file/MCP mechanism.

Core features that DO work right now

• ✅ startup_continuity() function handles discovery, attach, staleness detection

• ✅ Auto-attach works when conditions are safe (exact repo match, single thread)

• ✅ Context compilation reuses existing ranker+budget+continuation pipeline

• ✅ Staleness detection based on source file mtimes and session updated_at

• ✅ Ambiguity protection: returns explicit error if multiple active threads

What still needs verification

Real-provider dogfood tests are needed to confirm actual zero-touch behavior:

# Test sequence: Claude → Codex in same repo
1. Work on something in Claude, let it index naturally
2. Close Claude
3. Start Codex directly (no `voyager switch`)
4. Observe Codex calling `voyager_startup` tool automatically
5. Verify new Codex session appears in original WorkThread
6. Check if Codex can read and continue from prior context

Similar sequences needed for Claude→Codex, Codex→Claude, etc.

Run voyager integrate status to check your local installation state. See docs/DOGFOOD.md for detailed verification procedure.

MCP — native tools inside your agents

Voyager ships an MCP server, so agents can query the unified index with native tools instead of running commands:

pip install -e ".[mcp]"     # or: pip install "voyager[mcp]"
voyager-mcp                 # same as: python -m voyager.mcp_server

{ "mcpServers": { "voyager": { "command": "python", "args": ["-m", "voyager.mcp_server"] } } }

Tools: voyager_brief, voyager_search, voyager_list, voyager_show, voyager_handoff / voyager_merge (write context package/bundle), voyager_thread_list/show/attach/close (WorkThreads), voyager_current (discover continuity), voyager_context, voyager_continue, voyager_switch, voyager_startup (zero-touch startup with auto-discovery). Codex (config.toml), Claude Code (claude mcp add) and Cursor (mcp.json) are the tested hosts. Without the extra the server prints the install line above instead of a bare ModuleNotFoundError — the rest of the CLI never needs mcp.

Supported platforms

Cursor and Antigravity adapters are marked experimental: Cursor reads its key-value store read-only and Antigravity decodes protobuf blobs heuristically (no public schema). Full per-field availability matrix and data-source paths for every tool are in docs/RECON.md.

Tests & CI

Adapters are the part of Voyager that breaks when a vendor ships a storage change, so every platform has a regression test against a synthetic fixture — no real session data, no agent installation needed:

tests/
├── fixtures/          # codex/claude/dsh/grok/kiro JSON+JSONL, zcode/cursor/antigravity SQL seeds
├── conftest.py        # builds tmp trees (incl. zstd + SQLite) and repoints adapters at them
├── test_codex.py  test_claude.py  test_zcode.py  test_dsh.py  test_grok.py
├── test_cursor.py  test_kiro.py  test_antigravity.py  test_adapters.py
└── test_store.py  test_export.py  test_handoff.py  test_cli.py  test_mcp.py

python -m pytest tests/ -q                # 188 tests: adapters, store, continuity, budget, leases, switch, skill, API, MCP
python scripts/run_tests_core_only.py     # same suite with no optional deps (skips extras)

CI (.github/workflows/test.yml) runs the suite on Python 3.10–3.13 (Linux) and 3.10/3.13 (Windows — the adapters deal with %APPDATA%, drive letters and backslashes), plus a core-only job proving the CLI works with zero optional dependencies. The store tests cover the "don't wreck my thousands of sessions" contract: repeated scans never duplicate, changed sources are re-parsed, vanished sources are pruned.

Design

Provider files are read-only. Adapters translate each platform's events into one normalized model (Session / Event) while keeping the raw provider event alongside — nothing is lost, giant blobs are truncated with a pointer back to the source. Everything lands in a local SQLite index with FTS5 (trigram, so CJK substring search works). Scans are idempotent: sources are tracked by (mtime, size) and re-parsed only when they change; sessions whose source files vanish are pruned.

Details in docs/ARCHITECTURE.md, docs/DECISIONS.md, docs/API.md and docs/FAQ.md and everyday recipes in docs/WORKFLOWS.md.

What's next

The Continuity Engine core is complete (see docs/ROADMAP.md for the full close-out). The post-1.0 backlog — VS Code Context Composer UI, auto-clustering research, Claude/DSH transcript gates, scoped scan, fs-event watcher, PyPI/packaging polish — lives in docs/POST-1.0.md.

Phased plan, CLI sketches, and the issue list: docs/ROADMAP.md · 中文.

License

MIT — see LICENSE.