ctx

Filesystem-native context layer for AI agents.

ctx generates CONTEXT.md manifests for every directory in a project so AI agents can navigate with structured summaries instead of reading every file. One command refreshes the entire tree. Manifests are deterministic, verifiable, and cheap to maintain.

Quick Start

pip install ctx-tool
export ANTHROPIC_API_KEY="sk-..."
ctx refresh .

That's it. Every directory now has a CONTEXT.md with a purpose summary, file descriptions, and subdirectory overviews.

What It Costs

ctx uses lightweight LLM calls (Haiku-class models by default). Real-world benchmarks on personal document trees:

Runs are incremental — unchanged directories are skipped, so subsequent refreshes cost near zero.

For Agents

Tell your agent: install ctx-tool, run ctx refresh ., then read AGENTS.md for the full command contract, JSON output schemas, error codes, and integration patterns.

For MCP clients, copy the config from mcp.json into your client's MCP config (.mcp.json for Claude Code, .cursor/mcp.json for Cursor) or run ctx serve --mcp.

Commands

Key flags: --until-complete (auto-retry large trees), --output json (machine-readable), --force (regenerate all), --watch (live refresh).

Configuration

Works out of the box with ANTHROPIC_API_KEY or OPENAI_API_KEY. For local models:

ctx refresh . --setup   # auto-detects Ollama or LM Studio

Fine-tune with .ctxconfig:

provider: anthropic
model: claude-haiku-4-5-20251001
max_usd_per_run: 1.00

Full config reference in AGENTS.md.

Docs

License

MIT