ctxfile

Quickstart

ctxfile is a local-first MCP server that snapshots your project's working state (plan, key files, git state, optionally more) into one structured context object any MCP client can load. Install to first snapshot takes about a minute.

Install

npm install -g ctxfile

This gives you the ctxfile binary. It runs as an MCP server over stdio. Your client starts it, talks to it, and stops it. Nothing listens on the network.

ctxfile --root <dir>

--root defaults to the current working directory. Configuration is optional: see Configuration.

Register with Claude Code

claude mcp add ctxfile -- ctxfile --root .

Register with Cursor

Add to .cursor/mcp.json (per-project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "ctxfile": {
      "command": "ctxfile",
      "args": ["--root", "."]
    }
  }
}

What your agent sees

SurfaceWhat it does
get_contextTool the model calls to pull the snapshot. Optional scope: full | plan | files | git.
ingest_contextAny agent pushes its own session digest in: the universal session capture for unsupported harnesses. See Agent-assisted sessions.
context://currentResource returning the full ContextObject as JSON.
context://plan · context://gitScoped resources: just the plan, just the git state.
load-contextPrompt that injects the snapshot into the conversation.
remember · recall · forget · consult · transcribe_voicePro tools, registered per licensed feature. See MCP surface.

In practice: open your agent, say “load context” or let it call get_context, and it starts working with your plan, key files, and git state already in hand. No re-explaining. The full reference is on MCP surface.

Cloud agents

ctxfile export

Agents that don't run on your machine (hosted coding agents, CI bots) read a committed .ctxfile/context.json instead of talking MCP. The default profile is repo-safe. See Cloud agents & export.

Local dashboard

ctxfile ui

Opens a dashboard bound to 127.0.0.1. It is never exposed to your network. The access token is carried in the URL fragment, which never leaves the browser in HTTP requests.

Next steps