# thread-keeper

A local MCP server that gives separate agent CLIs one memory store, lets parallel sessions signal each other, and grows a skill library as they work.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 13
- Author: po4erk91
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/po4erk91/thread-keeper
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/mcp/thread-keeper

## What it does

Connected clients — Claude, Claude Desktop, Claude, Antigravity CLI, Copilot, MCP-aware VS Code extensions — read and write the same SQLite database. Threads, notes, quotes and a user model outlive a restart or a switch between tools. At session start the server injects a compressed brief of about 6 KB filled with structural tags and opaque IDs. It is built for an agent to parse, not for you to read.

Parallelism comes from the `spawn` primitive: children each get a self_cid and the same memory. The `broadcast`, `whisper`, `inbox`, `wait`, `ask` and `respond` calls let sessions talk across different CLIs. Class-level skills are written to `SKILL.md` and mirrored into every known skills root — `~/.claude/skills/`, `~/.codex/skills/`, `~/.gemini/config/skills/`, extra dirs listed in `THREADKEEPER_EXTRA_SKILLS_DIRS`. For hosts with no native skill loader there is `lessons.md` as a fallback.

Python 3.11+ is required, and the server runs through `uvx`. Install `'threadkeeper[semantic]'` with pipx, then run `thread-keeper-setup`, which registers the MCP entry in each detected CLI config, copies hooks into `~/.threadkeeper/hooks/` and writes a managed instructions block into `CLAUDE.md`, `AGENTS.md` or `copilot-instructions.md`. A daily self-update runs by default; a dirty or diverged git checkout is skipped instead of being overwritten, so local commits survive.

The brief at session start is dense on purpose and will look like noise if you open it yourself.

## Requirements
- Needs: Python and uv (commands run via uvx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add thread-keeper -- uvx threadkeeper
```
uvx runs the command named after the package; if the README names another one, use uvx --from threadkeeper <command>

### Codex

**Platform CLI**
```bash
codex mcp add thread-keeper -- uvx threadkeeper
```
uvx runs the command named after the package; if the README names another one, use uvx --from threadkeeper <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "thread-keeper": {
            "command": "uvx",
            "args": [
                "threadkeeper"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from threadkeeper <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "thread-keeper": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "threadkeeper"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from threadkeeper <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add thread-keeper uvx threadkeeper
```
uvx runs the command named after the package; if the README names another one, use uvx --from threadkeeper <command>

## When to use it
- carry context from a Claude session into Claude without retyping it
- stop two parallel agents from duplicating the same task
- keep notes and quotes after a thread is closed
- collect skills from several CLIs into one directory
- load a project brief at the start of a fresh session

## Example prompts
- Open a thread for the auth work and note everything you find in it
- Spawn two child agents: one fixes the tests, the other updates the docs
- Check `inbox` for messages from the other session

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md