ctxfile

Purpose

ctxfile is a local-first MCP server for snapshotting a project's working state into a structured context object and handing it to any MCP agent in a single call. It is aimed at developers who use multiple AI agents at the same time: for example Claude Code in the terminal, Cursor in the editor, a chat tab for thinking. Each agent usually starts from a "cold start," because the working state (the plan, key files, git status, decisions made an hour ago) exists only in the user's head or in scrolling history. ctxfile lets a session be saved in one agent and continued in another, without leaving the local machine.

Main capabilities

• Snapshot the project working state into a context object and hand it to an MCP agent in one go.
• Support saving sessions and continuing sessions (migration across agents).
• Zero network calls on the default path, using only files and git.
• Suspected secret content (cloud keys, tokens, private keys, JWTs, password= assignments) is redacted before entering the snapshot; .env*, key files, and credential files are not read at all.
• The core is read-only with respect to the project, and does not write to the repository, git state, or anything else.
• No telemetry by default; the anonymous weekly install ping is opt-in.
• Network connectors (Notion, local Ollama summaries, Sync) are enabled only when explicitly configured.
• Skills can be installed with a single command, so that any agent knows when to checkpoint the context during normal work, and announces every save (never silent, can be paused at any time, always reviewable).
• Rendered from the same specification, adapted to the format each harness reads: Claude Code, OpenCode, OpenClaw, and Hermes use Agent SKILL.md (the four skill systems share one portable file), Cursor uses a rule, and hosted GEMINI.md / AGENTS.md blocks.
• Context can follow the user into a chat tab: connect Grok, ChatGPT, Claude web, or Perplexity as a custom MCP connector to the encrypted Sync vault, or use ctxfile export to export an envelope and paste it into any prompt box (Gemini, etc.).

How to use

30-second quick start:

• Cursor: in the project's .cursor/mcp.json, or the global ~/.cursor/mcp.json configuration.
• Claude Desktop (no terminal required): download ctxfile-macos-arm64.mcpb and drag it into Settings → Extensions. This bundle includes compiled native modules, so for now it only supports macOS (Apple Silicon); on Windows or an Intel Mac, instead add the above stdio JSON to claude_desktop_config.json.
• All other clients: ctxfile is a standard stdio server, so npx -y ctxfile is the complete command. For copy-paste setup for OpenCode, Gemini CLI, OpenClaw, Hermes, Aider, etc., see the respective client tabs (ctxfile.dev/docs/clients).

Then enter "load my context" in the agent (or call get_context). Requires Node ≥ 20 (≥ 22 on Windows).

Make saving automatic: a single command installs a skill that teaches any agent when to checkpoint context during normal work and announces each save.

When to use it

• Development workflows that switch between multiple AI agents and need to continue the same project work state.
• Privacy-sensitive scenarios where you want context and project state to remain on your local machine.
• Scenarios where you need to bring context from a CLI/editor agent into a web chat bot.

Limitations

• The Claude Desktop .mcpb bundle currently supports only macOS (Apple Silicon); on Windows or Intel Mac, use the stdio JSON configuration instead.
• The core is read-only for projects; if you need capabilities such as session connectors, encrypted cross-session memory, multi-provider consultation, AI-refined prompt Playbooks, and local voice capture, you need the paid Pro add-on package (a separate closed-source package).
• Pro licensing uses offline verification with Ed25519 signature keys and does not send any information back.
• The materials do not provide specific pricing, subscription fees, or support for other platforms, so these are not provided for now.

Open source and feedback

The contents of this repository are all Apache-2.0, can be used independently, and remain valid permanently. The paid Pro add-on package is a separate closed-source package used to fund the open-source work. The "ctxfile" name and logo are trademarks, and the license covers the code rather than the name. Issues, PRs, and harness reports are welcome; for problems and feature requests, see issues, for questions and sharing, see discussions, and for security reports, follow SECURITY.md (do not open a public issue for vulnerabilities).