Cloud agents & export

The MCP server assumes the agent runs where the context lives. Agents that run elsewhere (hosted coding agents, CI bots) get the context as a static artifact instead: ctxfile export writes a versioned, self-describing snapshot the repo carries with it. No server, no account, no network.

Quick start

ctxfile export            # writes .ctxfile/context.json + context.md
git add .ctxfile && git commit -m "chore: ship agent context"

Any agent that clones the repo can now read .ctxfile/context.json before asking you to re-explain the project. The formal file format lives at the .ctxfile convention.

Redaction profiles

The leak risk is not your code (the repo already carries that); it is everything else the snapshot knows: session digests, Notion pages, private plans. Profiles control exactly what leaves:

Profile	Contents
repo-safe	Default. Plan, git state, and a key-file manifest (paths, token counts, redaction counts). No file bodies, no Notion, no sessions. Safe to commit.
full	Everything: file bodies, Notion content, session digests, session summary. The CLI warns loudly and suggests gitignoring `.ctxfile/`; committing this shares private working notes with everyone who can clone.
custom	Your allowlist from config, e.g. `"export": { "profile": "custom", "include": ["plan", "gitState"] }`. Sections: `plan`, `gitState`, `keyFiles`, `keyFileContent`, `notionPages`, `sessions`, `sessionSummary`.

Every profile re-runs secret redaction on every exported text field, and no export ever contains your absolute local path (the project appears by directory name only).

Keeping it fresh

Pre-commit hook

ctxfile hooks install

Adds a managed block to .git/hooks/pre-commit that regenerates the repo-safe export and stages it, so the artifact in every commit matches that commit. Best-effort by design: if ctxfile is missing or the export fails, the commit proceeds and a one-line note goes to stderr. ctxfile hooks uninstall removes exactly the managed block and nothing else.

CI

Regenerate on push instead (or as well); the ready-made GitHub Actions recipe is on the convention page.

Drift detection

The envelope stamps git_sha (the commit the snapshot saw) and both generation timestamps. Agents should compare git_sha with the checkout's HEAD and flag stale context instead of trusting it silently.

Piping instead of committing

ctxfile export --stdout | your-agent-cli --context -
ctxfile export --stdout > /tmp/context.json   # hand to anything

--stdout writes the JSON envelope to stdout and nothing to disk, for CI artifacts, upload steps you control, or ad-hoc handoffs.

What export deliberately is not

A static artifact, not a connection: no scoped queries, no memory recall, no live updates. Interactive remote access (an MCP endpoint you can point cloud agents at) is planned as ctxfile serve; its token configuration shape is already reserved in configuration but no listener ships yet. Roadmap-wise, the always-on multi-machine answer is the self-hosted Team hub. See Pricing.