thread-keeper

Multi-agent shared brain across Claude Code/Desktop, Codex, Antigravity CLI (agy), Copilot, and VS Code. Cross-session memory, self-improving skill loops, and inter-agent signaling — one local MCP server turns parallel agent instances into a coordinated multi-agent system instead of N isolated chats.

Every connected client (Claude Code, Claude Desktop, Codex CLI + desktop, Antigravity CLI, Copilot, every MCP-aware VS Code extension) shares one SQLite store, one set of threads, one user model, and one learning loop that improves the skill library autonomously over time.

The brief format is dense — structural tags, opaque IDs, ~6 KB per session-start injection. Optimized for agent consumption, not human reading.

Why

Every agent CLI starts cold. Context dies at session boundaries. Skills you taught Claude don't transfer to Codex. Threads you closed in yesterday's Antigravity chat are invisible to today's Copilot. Parallel agent instances running the same task don't know about each other and duplicate work or step on each other's writes.

thread-keeper is the substrate underneath. Three things that together make it more than a memory store:

• Collective memory — threads, notes, verbatim quotes, dialectic claims about you. Survives session, restart, CLI swap. One agent records, every other agent (any CLI) reads. The brief injected at session start gives a new agent everything the previous one knew.
• Multi-agent coordination — spawn primitive launches child agents in parallel, each gets a self_cid + sees the same memory. broadcast / whisper / inbox / wait / ask / respond let concurrent sessions signal each other across CLIs. Parent / children / sibling agents become a coordinated swarm, not isolated chats.
• Self-improving skill library — autonomous background loops (auto-review on thread close, shadow-review daemon, extract harvester, candidate-reviewer, weekly Curator, and a thread-janitor that auto-closes idle threads so abandoned work reaches the harvest path — closing is reversible, a note reopens a closed thread) materialize class-level skills as the agents work. Adapted to multi-CLI: SKILL.md is the primary write target and gets mirrored to every known/configured skills root simultaneously (~/.claude/skills/, ~/.codex/skills/, ~/.gemini/config/skills/ for Antigravity, existing ~/.agents/skills/, extra roots from THREADKEEPER_EXTRA_SKILLS_DIRS, and ~/.threadkeeper/skills/), with lessons.md as a fallback for CLIs without a native skills loader.

Foreground MCP servers also run a daily self-update check by default. Source checkouts fast-forward their tracked git branch and reinstall the editable package; PyPI/pipx/venv installs run pip install --upgrade in the current interpreter environment only after the latest PyPI release files have matching Integrity API provenance from the expected GitHub Trusted Publisher. Dirty or diverged git checkouts are skipped rather than overwritten. Restarts are gated on install/setup success plus a subprocess import smoke check, so a broken or unverified update is recorded but the current server keeps running. Upstream PyPI publishing is intentionally gated: green merge-to-main builds are auto-tagged, but every upload pauses for a human approval on the protected pypi GitHub Environment (a maintainer-signed annotated v* tag remains the manual override path), as described in docs/RELEASING.md.

They also run a twice-weekly installed-skill updater by default. It keeps all configured CLI skill roots in sync, adopts newer local copies installed into a non-primary root, and updates GitHub-backed skills when a tracked upstream source changes.

Quickstart

The shortest path — PyPI + pipx (recommended):

pipx install 'threadkeeper[semantic]' && thread-keeper-setup

thread-keeper-setup detects every CLI you have installed (Claude Code / Claude Desktop / Codex CLI + desktop / Antigravity CLI agy / Copilot / VS Code), registers the MCP server in each one's config, copies hooks to ~/.threadkeeper/hooks/, and writes a managed instructions block into each CLI's per-user instructions file (CLAUDE.md / AGENTS.md / copilot-instructions.md — Claude Desktop and VS Code have no global instructions file, so that step is skipped for them).

Restart your CLI of choice. Hook-capable clients inject a brief on the first message; hookless clients such as Codex and Antigravity CLI either follow the managed instructions block and call brief() / context() before answering, or — on hosts that support MCP resources — pull the brief as the read-only memory://brief resource the host attaches automatically (see MCP primitives).

Alternative installs

If you don't have pipx and don't want to install it:

# uv (Rust-fast Python tool runner) — no clone, single binary on PATH
uv tool install 'threadkeeper[semantic]' && thread-keeper-setup

# Plain pip into a venv
python3 -m venv ~/.threadkeeper-venv
~/.threadkeeper-venv/bin/pip install 'threadkeeper[semantic]'
~/.threadkeeper-venv/bin/thread-keeper-setup

For development (editable install from a git checkout) or to track the bleeding edge:

# One-liner installer — clones to ~/thread-keeper, makes a venv,
# editable-installs, wires every detected CLI. Idempotent — re-run to
# update (it git-pulls + reinstalls).
curl -fsSL https://raw.githubusercontent.com/po4erk91/thread-keeper/main/install.sh | bash -s -- --semantic

# Or fully manual
git clone https://github.com/po4erk91/thread-keeper ~/thread-keeper
cd ~/thread-keeper && python3 -m venv .venv
.venv/bin/pip install -e '.[semantic]'
.venv/bin/thread-keeper-setup

To preview without writing anything:

thread-keeper-setup --dry-run

Multi-CLI integration

Every CLI that produces parseable transcripts feeds the same dialog_messages table with a source tag, so dialog_search() finds matches regardless of where the conversation happened. Claude Desktop, Antigravity CLI, and the VS Code adapter are the exceptions — MCP registration only; their chats don't reach the table for now (Electron IndexedDB on the Claude Desktop side; sqlite/protobuf on the Antigravity side; per-extension stores on the VS Code side).

VS Code's user-level mcp.json is the central host that every MCP-aware VS Code extension consumes — GitHub Copilot Chat, the Anthropic Claude IDE plugin, the OpenAI Codex IDE plugin, Continue, Cline, … — so a single registration there reaches all of them at once.

Adding a new CLI = one file under threadkeeper/adapters/ implementing the CLIAdapter contract. See CONTRIBUTING.md.

MCP primitives (tools, resources, prompts, elicitation)

MCP has three server primitives. thread-keeper uses all three, mapped to the read/act split, plus MCP elicitation for host-native confirmations: