Metadata-Version: 2.4
Name: ctx-manager
Version: 0.1.0
Summary: Context engineering CLI + MCP server for AI coding agents: deterministic Markdown slicing and an append-only, git-validated session ledger.
Author: saturnarians
Author-email: saturnarians <jerrymiahisibor@gmail.com>
License-Expression: MIT
Requires-Dist: mcp>=2.0.0,<3.0.0
Requires-Dist: typer>=0.27.1
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# 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

```bash
uvx ctx-manager --help
```

No virtualenv setup, no global install required.

## Usage

**Slice a blueprint file by header:**

```bash
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:**

```bash
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):

```bash
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.

```toml
[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/`](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`](Docs/Architecture.md) and
[`Docs/PRD.md`](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

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

## License

MIT — see [LICENSE](LICENSE).
