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 ctx-manager --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.

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, 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).

Development

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

License

MIT — see LICENSE.