Local-first MCP server that snapshots your project's working state into one context object.
dev.ctxfile/ctxfile — Model Context Protocol (MCP) Server
Local-first MCP server that snapshots your project's working state into one context object. It supports Model Context Protocol workflows with a single aggregated context, intended for TypeScript-based environments and local operation.
🛠️ Key Features
Local-first operation
Snapshots a project’s working state
Produces one context object
Built around Model Context Protocol (MCP)
🚀 Use Cases
Provide agents with a unified context from the current working state
Use in “one context, every agent” scenarios
Local development workflows using MCP
⚡ Developer Benefits
Centralized context object for agent consumption
Fits TypeScript ecosystems
Uses MCP and related local-first context patterns
⚠️ Limitations
Server description provided does not specify additional tool capabilities, configuration options, or supported platforms
You work with more than one AI agent. Claude Code in the terminal, Cursor in the editor, a chat tab for thinking. Each one starts cold, because your working state (the plan, the key files, the git state, what you decided an hour ago) lives in your head and in scrollback.
ctxfile is a local-first MCP server that snapshots your project's working state into one structured context object, and hands it to any MCP agent in a single call. Save a session in one agent, continue it in another. Nothing leaves your machine.
code
you → ctxfile → the same context, in every agent
30-second quickstart
Claude Code
bash
claude mcp add ctxfile -- npx -y ctxfile
Cursor (.cursor/mcp.json in your project, or ~/.cursor/mcp.json globally)
Claude Desktop (no terminal needed): download ctxfile-macos-arm64.mcpb and drag it into Settings → Extensions. The bundle carries a compiled native module, so it is macOS (Apple Silicon) only for now; on Windows or an Intel Mac, add the stdio JSON above to claude_desktop_config.json instead.
Every other client: ctxfile is a standard stdio server, so npx -y ctxfile is the whole command. Copy-paste setup for OpenCode, Gemini CLI, OpenClaw, Hermes, Aider, and more is on the per-client tabs at ctxfile.dev/docs/clients.
Then, in your agent: "load my context" (or call get_context). Requires Node ≥ 20 (≥ 22 on Windows).
Make it automatic
You stop typing "save this." One command installs a skill that teaches any agent, while doing its normal work, when to checkpoint context and to announce every save (never silent, paused any time, reviewable always):
bash
ctxfile init
It renders from one canonical spec into whatever each harness reads: an Agent SKILL.md for Claude Code, OpenCode, OpenClaw, and Hermes (one portable file across all four skill systems), a Cursor rule, and managed GEMINI.md / AGENTS.md blocks. Details at ctxfile.dev/docs/automatic.
It follows you into the chat tabs, too
The same context your CLI and editor agents load over MCP can travel to web chatbots. Connect Grok, ChatGPT, Claude web, or Perplexity to your encrypted Sync vault as a custom MCP connector, or ctxfile export and paste the envelope into any prompt box (Gemini, and anything else). Walkthrough: ctxfile.dev/docs/webchat.
Private by default
This is the part we care about most, so it goes first:
The default path makes zero network calls. Files and git only.
Secret-looking content (cloud keys, tokens, private keys, JWTs, password= assignments) is redacted before it enters the snapshot. .env*, key files, and credential files are never read at all.
Core is read-only over your project. It never writes to your repo, your git state, or anything else.
No telemetry by default. An anonymous weekly install ping exists, and it is opt-in only.
Network connectors (Notion, local Ollama summarization, Sync) activate only when you explicitly configure them.
The full model, including what Pro and Sync add and what they can never see, is documented at ctxfile.dev/security.
What it does
Snapshot
get_context returns one structured ContextObject: plan docs, ranked key files fitted to a token budget, git state, optional Notion pages and local-LLM summary.
Save and resume
save_session stores an agent-written summary of the current conversation. continue_thread hands the merged, provenance-labeled history to the next agent. Different harness, different provider, cold start: it picks up where you left off.
Threads
Durable identities for a piece of work ("Q3 campaign"), spanning agents and machines. handoff: true enforces a complete takeover package: state, decisions with rationale, ordered open items, gotchas.
Memory import
ingest_memory moves what ChatGPT, Grok, Claude or any assistant knows about you into ctxfile: one prompt (ctxfile memory prompt), a strict schema, global or per-project scope. Instructions and identity wait for your approval; duplicates merge; rejections stick. Every agent then gets it in get_context. Docs.
Universal ingest
ingest_context is the schema-enforced door for any harness without a native parser. The prompt is the adapter, so every MCP-speaking agent is supported, including ones that do not exist yet.
Cloud agents
ctxfile export writes a static, repo-safe artifact for agents that never touch your machine (hosted coding agents, CI). The format is an open spec: the .ctxfile convention.
Dashboard
ctxfile ui: a local cockpit on 127.0.0.1. Run snapshots, watch connectors, browse context, inspect git state.
Sync (optional)
An end-to-end encrypted vault through a relay you can self-host. Argon2id key derivation, XChaCha20-Poly1305 per blob. The relay stores ciphertext only.
Everything in this repo is Apache-2.0 and works standalone, forever. The paid Pro add-on (a separate, closed package) adds session connectors that read your recent sessions from Claude Code, Cursor, Codex CLI, OpenCode, Gemini CLI, Aider, OpenClaw, and Hermes Agent, encrypted cross-session memory, multi-provider consult (Anthropic, OpenRouter for hundreds of models on one key, any OpenAI-compatible endpoint, or local Ollama), AI-distilled prompt Playbooks, and local voice capture. Licensing is an Ed25519-signed key verified offline. No phone-home, ever. Pro funds the open-source work.
Contributing
We want your issues, your PRs, and your weird harness reports. Start with CONTRIBUTING.md. Every ingested format, every MCP client quirk, every redaction gap you find makes the whole thing better.
