Callimachus

[Callimachus: the catalogue for your AI coding history]

[License: AGPL-3.0] [Platform: macOS, Windows, Linux] [Tauri 2] [Rust] [React 19] [Local-first]

Local index & search for your AI coding-agent threads across 12 tools (Claude Code, Codex, Cursor, Gemini CLI, Qwen Code, Goose, OpenCode, Continue, Cline, Roo Code, Kilo Code, Copilot Chat), plus a provider-agnostic chat, an MCP server, a CLI, and a VS Code / Cursor extension. Your history stays on your machine.

Named for Callimachus, who built the first catalogue of the Library of Alexandria.

Download

Grab the latest signed build from Releases: macOS (.dmg, Apple Silicon), Windows (.msi or -setup.exe), or Linux (.AppImage, .deb or .rpm). The app auto-updates from there on. Prefer to build it yourself? See Develop.

macOS: drag Callimachus into Applications and open it from there before enabling the agent integration. While it runs from the disk image or a quarantined download, Settings won't register it, because that path disappears when the app quits.

Windows uninstall: the -setup.exe uninstaller removes what the app added (the /recall skill, the Claude Code, Codex and Gemini CLI hooks, the MCP entries for Claude Code, Codex, Cursor and Gemini CLI, and cal.exe), but the .msi uninstaller doesn't. Before removing an MSI install, click Remove for Claude Code and under Other agents in Settings → Agents (the Other agents Remove also takes out the Codex and Gemini CLI memory hooks), or run callimachus.exe --uninstall-integration; otherwise the hooks keep pointing at the deleted app and each agent reports a hook error at every session start.

The same release also carries standalone cal-<target> and callimachus-mcp-<target> binaries for CLI/MCP-only use, with their SHA-256 sums in SHA256SUMS. Linux builds and binaries need glibc 2.38 or newer (Ubuntu 24.04+, Debian 13+, Fedora 39+); Ubuntu 22.04, Debian 12 and RHEL 9 are too old for the bundled ONNX Runtime.

Updates: the first launch after an update upgrades the index in the background; the splash keeps animating, and on a large index this can take tens of seconds. An older build can't open an upgraded index: an older app shows "This index is from a newer Callimachus", and an older cal, callimachus-mcp or pinned npx callimachus-mcp@<version> stops with an error. Whichever of them opens the index first does the upgrade, so keep the app, the npx launcher and any standalone binaries on the same release.

What it does

• Indexes every conversation from 12 coding agents into one local SQLite store: Claude Code, Codex, Cursor, Gemini CLI, Qwen Code, Goose, OpenCode, Continue, Cline, Roo Code, Kilo Code, and Copilot Chat (the built-in chat panel of VS Code, Cursor, VSCodium and Windsurf). Adding another source is a small, documented contract.
• Searches them with hybrid ranking: keyword (SQLite FTS5 / BM25) fused with on-device semantic similarity (sqlite-vec KNN, no cloud) via Reciprocal Rank Fusion. Filter by source, project, subagents, starred, and tags.
• Finds code-aware: type file:embed/mod.rs in the search bar (or cal files <path>) to find every thread that touched a path; backed by a file-mention index built at index time.
• Distills knowledge: free heuristic TODO extraction (always on, no LLM), plus LLM distillation of decisions, gotchas, and summaries behind one consent click that names the engine and where transcripts go (the Turn on memory card in Projects or Chat's Ask mode preselects a detected Claude Code or Codex CLI, then local Ollama, then a saved key; Settings > AI engine has the same switch), with cross-thread semantic recall of past decisions/gotchas. Optional auto-distillation works through threads active in the last 30 days in the background, up to a daily limit you set next to its toggle (50 threads by default, 0 pauses it; Settings shows what's left today), so memory self-populates without an open-ended bill. Runs on local Ollama (keyless), your logged-in Claude Code or Codex CLI (keyless, billed to whatever that CLI is signed in with), or a cloud API key.
• Imports what agents already write: Claude Code's own auto memory (the topic files under ~/.claude/projects/<project>/memory/) joins each repo's project memory with no LLM: feedback memories become gotchas and project memories decisions, tagged "Claude Code memory", refreshed when a file changes and removed when it goes (Settings > Agents turns it off and removes them). The managed AGENTS.md / CLAUDE.md block and .callimachus/memory.md leave them out, since Claude Code already loads them and those files get committed. When auto-distillation is on, a SessionEnd hook moves the session that just ended to the front of the queue, so its memory lands minutes after it ends.
• Curates the facts: pin, edit, or hide distilled facts so your edits survive re-distilling, record a decision or gotcha yourself with Remember in the Projects tab (saved pinned), plus an LLM "Review conflicts" pass that flags decisions that contradict each other.
• Remembers per project: a Projects tab gives each repo one page: its recent sessions, its decisions, gotchas, and open TODOs aggregated into durable memory (grouped by a canonical project key, so worktrees / symlinks / ~ don't split one repo), its snapshots, and exactly what its agents are given (the SessionStart hook's text and the managed AGENTS.md block, with their sizes), plus an LLM brief and a managed .callimachus/memory.md. That memory is prepended when you "Open in CLI", and you can inject it into any agent automatically: Update AGENTS.md (or cal agents) writes a managed block into the repo's AGENTS.md / CLAUDE.md, and cal hook feeds a size-budgeted version to a Claude Code SessionStart hook, labeled as notes from past sessions rather than instructions. A repo with no memory yet still gets something on day one, with no LLM: a digest of its last few sessions (title, agent, branch, age, the latest summary or prompt, touched files, open TODOs, and the latest snapshot to resume), also appended under the facts when they leave room. The hook runs on startup, /clear and compaction (a shorter, facts-only refresher), stays quiet on a resumed session, and skips a repo where Claude Code already loads the managed block (a CLAUDE.md, CLAUDE.local.md or a file one @-imports, or AGENTS.md when no CLAUDE.md exists), so the memory is injected once. cal hook --explain shows what a new session would get, cal hook --mute turns the digest off for one repo, and Settings > Agents turns it off everywhere. Codex and Gemini CLI get the same memory through their own hooks (Settings > Agents > Other agents > Memory hooks): cal hook --for codex / --for gemini on session start and /clear (Codex also after compaction), wrapped in each agent's hook output format, plus their imported Claude Code memories, marked as such, since neither loads Claude's auto memory. The hook stays quiet in a repo whose AGENTS.md (Codex) or GEMINI.md (Gemini CLI) already holds the managed block. Their SessionEnd hooks queue the ended session for auto-distillation like Claude Code's, and a Codex PreCompact hook snapshots the session. Codex asks you to trust new hooks once (/hooks in Codex). The /recall skill is also copied to ~/.agents/skills/, the shared skills folder other agents read. Cursor gets no hook: its session-start payload has no working directory. Gemini CLI loads every context file it is configured with plus their @ imports, and Codex its fallback filenames too, so the hook stays silent wherever the managed block already lives.
• Asks your history (RAG): the Ask mode in Chat gives a synthesized, cited answer over your own threads, with [thread N] citations that open the sources it used; it is saved with your chats and follow-ups continue as a normal chat. Needs an LLM engine (memory turned on in Settings > AI engine).
• Organizes into collections: star threads and attach free-form tags, then filter the list by starred or by tag.
• Chats with an in-app agent (Anthropic / OpenAI / Gemini / OpenRouter / Ollama, local or Cloud, or your logged-in Claude Code / Codex CLI with no key) that can search your own history and run shell commands with your approval; streaming, cancellable, with live model lists. Chats are saved and become searchable too.
• Carries context across tools: open any thread in any agent CLI ("Open in Claude / Codex / Gemini …", seeded with the packed transcript), resume a Claude Code / Codex thread in its native CLI, copy context, or export a thread to Obsidian (optionally AI-summarized with decisions / gotchas / TODOs).
• Links threads to commits: infers on-device which git commits a thread produced, by overlapping the files a thread discussed with git log's changed files inside the thread's time window (shared-file count = confidence). See it as a thread→commit timeline (cal commits), per-thread in the desktop UI ("Produced commits"), or via the linked_commits MCP tool.
• Snapshots agent sessions: durable, resumable checkpoints of a thread (packed transcript + carry-forward project memory) for handoff across a context-window compaction or across tools; auto-captured by a Claude Code PreCompact hook right before a context compaction, which also keeps Claude Code's compaction summary as the thread's summary. Take, list, and resume them (cal snapshot / cal snapshots / cal resume, or the snapshot_session / list_snapshots / load_snapshot MCP tools), or in the app, where a project's page lists its snapshots to read, delete, or resume in any agent CLI.
• Guards decisions: decisions can carry a rationale ("why"), and an active guard surfaces settled decisions on a topic before an agent re-litigates one (cal check "<proposal>" / the check_decision MCP tool).
• Recalls before you redo: an opt-in Claude Code hook quietly injects "you may have solved this before" into the agent's context on each prompt when it strongly matches prior work (Settings → Agents → Proactive recall, off by default, signal-floored and per-session deduped).
• Mines recurring issues: surfaces the errors you keep hitting across all your tools (normalized signatures, last 180 days) so you fix the pattern, not the instance (on the Project page, or cal issues).
• Shows what it did for you: a Stats card counts, per week, the sessions that started with injected memory or a recent-sessions digest, the prompts where recall surfaced prior work, and the MCP tool calls answered (cal stats prints the same as one line). The counts are appended to ledger.jsonl next to the index (<name>.ledger.jsonl for any other index file, such as the dev build's index.dev.db), and once a day is over the app moves that day's counts into the index itself; neither leaves the machine. The same card shows how many indexed Claude Code sessions are still searchable after Claude Code deleted their transcripts (its cleanupPeriodDays, 30 days by default), with a reversible "Keep transcripts for a year" that sets it to 365 in Claude Code's settings.json after you confirm.
• Shows what it cost: captures per-message token usage and model at index time, then estimates dollar spend by model and your priciest threads (a Stats card, or cal cost; reindex once to backfill).
• Feeds PR audits: cal audit-pr <repo> --changed-files … --shas … returns one JSON bundle (per-commit provenance back to the session that produced it, per-file prior threads + reasoning, repo recurring errors, project memory) so an external local PR-review tool can show the history behind a diff.
• Surfaces to your agents: a bundled MCP server (callimachus-mcp) exposes the index as tools any agent can call mid-session, and it's two-way: agents can write back into Callimachus's own memory (close TODOs, record decisions/gotchas, snapshot a session) without ever touching your files. The /recall skill teaches them when to use it.
• Stays current via a background file watcher, plus a catch-up pass at launch for the sessions your agents wrote while the app was closed; stays private: the index never leaves your machine, API keys live in the OS keychain, conversation content goes only to an AI provider you pick, and usage analytics are opt-in and content-free (see Security & privacy).

Stack

• Shell: Tauri 2 (Rust) + React 19 + TypeScript + Vite 8
• Store/search: bundled SQLite + FTS5 (rusqlite); on-device embeddings via fastembed (bge-small-en-v1.5, 384-dim); KNN in SQL via sqlite-vec (vec0)
• Watcher: notify + debouncer
• Chat: multi-provider via the genai crate (Anthropic / OpenAI / Gemini / OpenRouter / Ollama local + Ollama Cloud), each with a configurable base URL, streaming tokens over a Tauri Channel, cancellable, with agent tool-calls (history search + approved shell)
• Secrets: OS credential store via the cross-platform keyring crate: macOS Keychain, Windows Credential Manager, Linux Secret Service
• Entry points: the app binary also runs as cal (through the ~/.local/bin/cal link or cal.exe) and as the MCP server (--mcp); the standalone cal and callimachus-mcp release binaries are the same code built on their own. All of them reuse the desktop core lib against the same index.db
• Editor: a VS Code / Cursor extension (apps/vscode, published to the Marketplace + Open VSX) that shells out to cal

Monorepo

This is a Turborepo + pnpm workspace.

apps/  desktop/            # the Tauri 2 desktop app + the cal CLI and MCP server (src-tauri)  vscode/             # VS Code / Cursor extension (search history from the editor)  web/                # callimachus.app, the marketing + download site (TanStack Start)packages/  callimachus-mcp/    # the npm launcher behind `npx -y callimachus-mcp`.changeset/           # version + changelog managementscripts/              # version-sync, release tagging

Releases, versioning, and the auto-updater are documented in RELEASING.md.

Develop

pnpm installpnpm desktop:dev      # launches the desktop window (tauri dev) against a separate dev index
# from the repo root, across all apps:pnpm build            # turbo: build every app's frontendpnpm typecheck        # turbo: typecheck every app

First launch: the index is empty, so the Search screen offers Index my history (or use Reindex in Settings → Sources); then Build semantic index enables semantic search. Later launches also index whatever your agents wrote while the app was closed. Reindex runs as a background job with a per-source progress bar, separate from Build semantic index. The two are mutually exclusive (one pauses while the other holds the write lock).

Tests

cd apps/desktop/src-tauricargo test                                   # fast unit testscargo test -- --ignored --nocapture          # real-data + model + keychain smoke tests

The --ignored tests touch live data on this machine: each source has a real_<source>_index smoke test that indexes your real history read-only (~/.claude, ~/.codex, Cursor, ~/.gemini, ~/.qwen, Goose, OpenCode, Continue, Cline/Roo/Kilo), plus the embedding-model download (first run, needs network) and a Keychain round-trip.

Use your history anywhere

Beyond the desktop window, the same local index is reachable from your agents, terminal, and editor, all reading one index.db.

Claude Code plugin: the one-step setup for Claude Code. It bundles the /recall skill (as /callimachus:recall), the MCP server (through npx -y callimachus-mcp@<version>, pinned to the plugin's release) and the SessionStart, PreCompact and SessionEnd memory hooks (plugins/claude-code):

claude plugin marketplace add BetaBots-LLC/callimachus# then, inside Claude Code:/plugin install callimachus@callimachus

The hooks run the cal CLI at ~/.local/bin/cal, so open the desktop app (which builds the index) and click Install the cal CLI in Settings → Agents once (the Claude Code button's label while the plugin is enabled): that installs only cal and removes the app's own skill, MCP entry and hooks, so memory is never injected twice and only one server starts; Settings then says the integration is managed by the plugin. Until cal exists the hooks do nothing. The plugin needs the app at 0.11.4 or later: the marketplace serves it from the latest release tag, with the MCP server pinned to that release, so keep the app on the latest release too. On Windows, use Settings → Agents instead of the plugin: Claude Code runs plugin hooks through Git Bash (or PowerShell, where they fail with a hook error), and the app keeps its own skill, MCP entry and hooks there, so the plugin would load them twice.

MCP server: let any agent search its own past work mid-session. It reads the index the desktop app builds and does not index anything by itself, so install the app and let it index once first. The quickest way to register it is npx (it downloads the prebuilt binary on first run and verifies its SHA-256); it's also listed on the official MCP registry as io.github.BetaBots-LLC/callimachus:

claude mcp add callimachus -- npx -y callimachus-mcp    # or any MCP client

Already running the desktop app? You don't need npm: Settings → Agents → Enable for Claude Code registers the app itself (launched with --mcp) as Claude Code's MCP server, and Settings → Agents → Other agents does the same for Codex, Cursor and Gemini CLI. The app keeps those entries pointed at itself after an update or a move. You can also download the standalone callimachus-mcp-<target> binary from Releases, or build from a checkout with cargo install --locked --path apps/desktop/src-tauri/standalone --bin callimachus-mcp (add --force over a source install from an earlier version).

Tools (22), read and write. Reads (18): search_threads, search_current_project (auto-scoped to the repo it runs in), recent_threads, get_thread, list_tags, list_open_todos, get_thread_knowledge, recall_decisions, recall_gotchas, find_prior_work (the "have I done this before?" guard: prior sessions similar to a task), project_memory (a project's aggregated decisions / gotchas / open TODOs), ask_history (a cited RAG answer over your history), threads_for_file (which sessions touched a path), check_decision (surface settled decisions before re-litigating a proposal), linked_commits (the commits a thread likely produced), recurring_issues (errors you keep hitting across sessions), list_snapshots (a project's session snapshots), and load_snapshot (restore a saved checkpoint). Writes (4, into Callimachus's own memory, never your code): complete_todo (close an open TODO), record_decision (optionally with a rationale), record_gotcha (persist a fact into a project's memory), and snapshot_session (checkpoint a thread for handoff). The bundled /recall skill (resources/recall/SKILL.md) tells agents when to reach for them.

Results are compact JSON sized for an agent's context. The search tools return one entry per thread with its matching snippets, get_thread and load_snapshot take an optional budget (default 24,000 chars, max 96,000), and project_memory returns size-budgeted markdown by default (format: "json" for data, plus limit and kinds). Until the app has indexed something, every read tool answers with setup instructions instead of an empty list. The server never upgrades the index itself: when its version and the index's schema disagree, every tool says to open the app once (the index needs an upgrade) or to update callimachus-mcp or the app (the index is newer). Memory that is not distilled yet still answers: when nothing matches in a scope that isn't fully distilled, recall_decisions, recall_gotchas and check_decision return the distillation coverage and up to three closestSessions by search, project_memory adds the repo's recent sessions while it has no decisions or gotchas, and a search with zero hits says which sources the index holds, when it last indexed, and its blind spots (cloud sessions, Cursor's missing project paths).

The server also offers three MCP prompts, recall (a topic), check_decision (a proposal) and prior_work (a task), which spell out the tool order of the /recall skill; Claude Code lists them as slash commands such as /mcp__callimachus__recall. Project memory is also a resource: callimachus://memory for the repo the server runs in, callimachus://memory/{project} for any other (a path, a project key, or current).

CLI: cal, pipe-friendly. The desktop app installs it with Settings → Agents → Enable for Claude Code: on macOS and Linux it is linked at ~/.local/bin/cal (if ~/.local/bin isn't on your shell's PATH, as on stock macOS, Settings shows the export PATH=... line to add), and on Windows it is placed as cal.exe next to the app. If another program already owns ~/.local/bin/cal, or a per-machine Windows install can't write cal.exe, Callimachus leaves cal out and says so in Settings; the hooks, MCP server and /recall skill work without it. You can also download the standalone cal-<target> binary from Releases, or build from a checkout with cargo install --locked --path apps/desktop/src-tauri/standalone --bin cal (add --force over a source install from an earlier version).

cal search "vector index migration" -y    # -y = hybrid (semantic + keyword)cal recent -n 10cal cat 42 | pbcopy                        # packed transcript → clipboardcal stats                                  # index totals, per-source breakdown, times helped this weekcal export 42 --vault ~/Obsidian           # write a thread as an Obsidian notecal ask "how did we set up releases?"      # cited RAG answer over your historycal files embed/mod.rs                     # threads that touched a file pathcal memory                                 # this repo's distilled memory (decisions/gotchas/TODOs)cal done 17                                # mark an open TODO done (id from `cal todos`)cal remember decision "use sqlite-vec for KNN" --because "no cloud, KNN in SQL"  # record a fact (+ rationale) into the repo's memorycal check "switch to pgvector"             # surface settled decisions before re-litigating onecal commits                                # infer the thread→commit timeline for this repo (--json; or pass a path)cal issues                                 # recurring errors you keep hitting across sessions (last 180 days)cal cost                                   # estimated $ spend by model + your priciest threadscal audit-pr . --changed-files a,b --shas s1,s2  # one JSON bundle for an external PR auditorcal snapshot 42 -l "pre-refactor"          # checkpoint a thread for handoff (transcript + project memory)cal snapshots                              # list saved session snapshots (optionally for a project)cal resume 7 -a claude                     # resume a snapshot in an agent CLIcal agents                                 # write the repo's memory into AGENTS.md (any agent reads it)cal hook                                   # print the repo's memory (use as a Claude Code SessionStart hook)cal hook --explain                         # what a new session in this repo would get, or why nothingcal hook --explain --for codex             # the same for a Codex session (also --for gemini)

star, tag, tags, todos, knowledge, distill, decisions, gotchas, related, and similar (the "have I done this before?" check) also exist. Run cal help for the full list.

VS Code / Cursor: the extension adds a "Callimachus History" sidebar, a status-bar search button, and commands to search / insert / copy threads (it shells out to cal). Install from the VS Code Marketplace or Open VSX (the registry Cursor and VSCodium use), or grab the .vsix from Releases. See apps/vscode/README.md.

Notes / limitations

• Cross-platform (macOS / Windows / Linux), including the "Open in CLI" / "Resume" launchers. They open Terminal on macOS, a new console window on Windows, and on Linux the first terminal they find ($TERMINAL, then x-terminal-emulator, GNOME Terminal, Konsole, xfce4-terminal, kitty, Alacritty, WezTerm, xterm). On a Linux machine with none of these, the buttons are hidden.
• Cline / Roo Code / Kilo Code are editor extensions with no CLI, so they are index-only (searchable, but not relaunchable via "Resume").
• Cursor doesn't store a per-thread workspace, so Cursor threads currently have no project path.
• Claude Code subagent transcripts are indexed but hidden behind a "subagents" toggle by default.
• Moved your Claude Code or Codex data (CLAUDE_CONFIG_DIR / CODEX_HOME)? An app opened from the Dock, Finder or Start menu doesn't see shell variables, so set those folders under Settings → Sources (changing one reindexes that source).
• Large first index is a one-time cost (the Claude corpus here was ~90k messages in ~25s); subsequent passes skip unchanged files.
• The index (index.db), the embedding model (models/) and the app's diagnostics log (callimachus.log) live together in the per-user app data folder dev.shaller.callimachus (~/Library/Application Support on macOS, %LOCALAPPDATA% on Windows, ~/.local/share on Linux). Attach callimachus.log to a bug report.
• More sources (Charm Crush, Factory Droid, and the standalone Copilot CLI) are scoped but not yet integrated; Copilot Chat in VS Code-family editors is already indexed. See the indexer guide.

Contributing

Issues and PRs welcome. CONTRIBUTING.md covers local setup, conventions, and the release flow. Adding support for another agent is a small, documented contract, usually one indexer module + a migration + a few wiring points.

Security & privacy

Callimachus is local-first. Your index, transcripts and memory never leave your machine, except conversation content you explicitly send to an LLM provider you choose (the in-app chat, Knowledge distillation, Ask your history, project briefs and conflict review, and AI-summarized Obsidian exports; local Ollama keeps even that on-device) and the excerpts that agents you connect over MCP or hooks pull into their own sessions. API keys live in the OS keychain, never on disk.

The desktop app can send anonymous, opt-in usage analytics to PostHog (US): event names, app version, OS, CPU architecture and language, and a few properties picked from fixed lists (such as which agent source, AI provider or setting an event concerns, an error category, or a count rounded into a range), tied to a random install ID. It never sends file paths, thread titles, prompts, transcripts, project names or API keys. It is off until you choose Allow, and you can turn it off any time in Settings → General or with CALLIMACHUS_TELEMETRY=0 / DO_NOT_TRACK=1. The CLI and MCP server never send analytics. The only other network traffic is the update check against GitHub Releases and the embedding-model download from Hugging Face (desktop app only, the first time you build the semantic index). The website uses PostHog in cookieless mode (no cookies, no cross-site tracking).

The full breakdown is in SECURITY.md and the privacy policy. To report a vulnerability, see SECURITY.md.

License

Dual-licensed. Free and open source under AGPL-3.0-or-later: use, modify, and share it; if you distribute it or run a modified version as a network service, you must release your source under the AGPL.

For closed-source, proprietary, or for-profit/SaaS use that the AGPL doesn't permit, a commercial license is required. See COMMERCIAL.md (contact [email protected]).

© 2026 Ari Shaller. See NOTICE for attributions. Contributions are accepted under the terms in CONTRIBUTING.md.

Acknowledgements

Built on Tauri, fastembed-rs, sqlite-vec, and genai. Named for Callimachus of Cyrene, who catalogued the Library of Alexandria.

_{Social preview: assets/og.png · brand sources in assets/brand/}