ctx-manager

A provider-agnostic context engineering CLI + MCP server for multi-language agentic development.

ctx-manager sits between your Docs/ folder (PRDs, architecture docs, phase plans, API specs) and AI coding agents (Claude Code, Cursor, Windsurf), cutting token spend two ways:

• Deterministic, header-based document slicing — pull exactly the section you need from a blueprint file, not the whole thing. Structural (regex over Markdown headers), not RAG/embeddings.
• An append-only, git-validated Memory_Ledger.md — accurate session state so agents don't re-derive or hallucinate what's already been built. Every entry is checked against real git status output before being marked verified.

Works identically across Rust, Go, TypeScript, Python, or any other stack -- ctx-manager never touches your application source code, only Docs/.

Install

uvx --from ctx-manager ctx --help

No virtualenv setup, no global install required.

Usage

Slice a blueprint file by header:

ctx build --slice "PRD.md > 5. Feature List"

Prints the matched section's content to stdout — pipe it into CLAUDE.md or wherever your agent reads context from.

Auto-slice the next phase, based on ledger history:

ctx build --auto-phase

Reads Memory_Ledger.md for the latest completed phase, and slices the next phase's section out of Phase_file.md automatically — no manual --slice target needed. Falls back to Phase 0 with a warning if the ledger has no completed-phase entries yet.

Append a verified entry to the session ledger:

ctx append-ledger --summary "Implemented the login endpoint" --category completed

Checks git status against your project before writing, and prefixes the entry [Verified: N files changed], [Reasoning/State Only], or [Unverified: not a git repo] depending on what it finds -- so an agent's self-reported "done" claim is checked against what actually happened on disk.

Run as an MCP stdio server (for Cursor, Windsurf, Claude Desktop):

ctx mcp

Exposes query_slice, append_ledger_entry, and get_current_phase as MCP tools, calling the exact same code path as the CLI commands above.

Configuration

ctx-manager searches upward from your current directory for .context/config.toml. If none is found, it uses sane defaults (Docs/ folder, Memory_Ledger.md, etc.) and warns once.

[project]
docs_dir = "Docs/"
ledger_file = "Memory_Ledger.md"
phase_file = "Phase_file.md"

[blueprint_files]
files = ["PRD.md", "Architecture.md", "API_Spec.md"]

[git]
scope = "docs_dir"  # or "repo_root"

Override the search entirely with --project-root.

Claude Code integration

Example SessionStart/SessionEnd hooks (auto-refresh CLAUDE.md before a session via --auto-phase, auto-log to the ledger after) are in examples/claude_code_hooks/.

Design principles

1. Docs/ in, Docs/ out — never touches application source, in any language.
2. Cheap before heavy — stdlib re before embeddings, subprocess git before a git library, local stdio before any network service.
3. Append-only ledger — no code path overwrites Memory_Ledger.md wholesale. Ever.
4. Fail loud, not silent — a missing header or missing file returns an explicit error, never empty content an agent could hallucinate on.

See Docs/Architecture.md and Docs/PRD.md for the full design writeup (this project dogfoods itself -- its own Docs/ folder is sliced and tracked by ctx-manager during its own development).

Limitations

ctx-manager cannot prevent an agent from bypassing it. Nothing here stops an agent with raw filesystem access from reading Docs/PRD.md directly instead of going through ctx build. This is a structural limit, not a missing feature -- a subprocess-based CLI has no hook into another process's file-read tool calls.

If you need actual enforcement (not just convention), that has to come from the agent runtime itself:

• Claude Code: use permissions.deny rules in .claude/settings.json to block the Read tool from touching Docs/*.md directly, forcing reliance on the CLAUDE.md that ctx build --auto-phase generates. See Claude Code's own permissions docs -- this is not something ctx-manager configures for you.
• MCP clients (Cursor, Windsurf, etc.): whatever filesystem-access controls that client exposes, if any -- outside ctx-manager's control.

Without one of those, ctx-manager is a convention the agent is expected to follow, backed by verified session history (the ledger) -- not a sandbox.

Development

git clone <this-repo>
cd ctx-manager
uv sync
uv run pytest

License

MIT — see LICENSE.