ctx-manager

プロバイダ非依存のコンテキストエンジニアリングCLI + MCPサーバー。多言語エージェント開発向け。

ctx-manager は、Docs/ フォルダ（PRD、アーキテクチャドキュメント、フェーズ計画、API仕様）とAIコーディングエージェント（Claude Code、Cursor、Windsurf）の間に位置し、トークン消費を2つの方法で削減します：

• 決定的なヘッダーベースのドキュメントスライシング — ブループリントファイルから必要なセクションだけを正確に取得し、全体を取得しません。構造的（Markdownヘッダーに対する正規表現）であり、RAG/埋め込みではありません。

• 追記専用のgit検証済みMemory_Ledger.md — 正確なセッション状態を保持し、エージェントが既に構築された内容を再導出したり幻覚を起こしたりするのを防ぎます。すべてのエントリは、検証済みとマークされる前に実際のgit status出力と照合されます。

Rust、Go、TypeScript、Python、その他どのスタックでも同じように動作します — ctx-manager はアプリケーションのソースコードには一切触れず、Docs/ のみを扱います。

インストール

uvx --from ctx-manager ctx --help

virtualenvのセットアップも、グローバルインストールも不要です。

Related MCP server: Claude Session MCP

使用方法

ヘッダーでブループリントファイルをスライス：

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

一致したセクションの内容をstdoutに出力します — CLAUDE.md やエージェントがコンテキストを読み取る場所にパイプします。

台帳履歴に基づいて次のフェーズを自動スライス：

ctx build --auto-phase

Memory_Ledger.md から最新の完了フェーズを読み取り、Phase_file.md から次のフェーズのセクションを自動的にスライスします — 手動の--sliceターゲットは不要です。台帳に完了フェーズのエントリがない場合は、警告とともにフェーズ0にフォールバックします。

検証済みエントリをセッション台帳に追記：

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

書き込み前にプロジェクトのgit statusをチェックし、検出結果に応じてエントリに[Verified: N files changed]、[Reasoning/State Only]、または[Unverified: not a git repo]のプレフィックスを付けます — エージェントが自己申告した「完了」が、ディスク上で実際に起こったことと照合されます。

MCP stdioサーバーとして実行（Cursor、Windsurf、Claude Desktop用）：

ctx mcp

query_slice、append_ledger_entry、get_current_phase をMCPツールとして公開し、上記のCLIコマンドとまったく同じコードパスを呼び出します。

設定

ctx-manager は現在のディレクトリから上方向に .context/config.toml を検索します。見つからない場合は、適切なデフォルト（Docs/ フォルダ、Memory_Ledger.md など）を使用し、一度だけ警告します。

[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"

--project-root で検索を完全に上書きします。

Claude Code統合

SessionStart/SessionEnd フックの例（セッション前に--auto-phaseでCLAUDE.mdを自動更新、セッション後に台帳へ自動ログ）は examples/claude_code_hooks/ にあります。

設計原則

1. Docs/ イン、Docs/ アウト — どの言語でもアプリケーションソースには一切触れません。

2. 重い処理より軽い処理 — 埋め込みの前に標準ライブラリのre、gitライブラリの前にsubprocess git、ネットワークサービスの前にローカルstdio。

3. 追記専用台帳 — Memory_Ledger.md を全体上書きするコードパスはありません。絶対に。

4. 静かに失敗せず、明確に失敗 — ヘッダーやファイルが見つからない場合は明示的なエラーを返し、エージェントが幻覚を起こす可能性のある空のコンテンツは返しません。

完全な設計文書は Docs/Architecture.md と Docs/PRD.md を参照してください（このプロジェクトは自己ドッグフーディングしています — 自身のDocs/フォルダは、開発中にctx-manager自身によってスライス・追跡されています）。

制限事項

ctx-manager はエージェントがそれを迂回するのを防ぐことはできません。 ここにあるものは、生のファイルシステムアクセスを持つエージェントがctx buildを経由せずにDocs/PRD.mdを直接読むのを止めるものではありません。これは構造上の限界であり、欠落した機能ではありません — サブプロセスベースのCLIは、別のプロセスのファイル読み取りツール呼び出しにフックする手段がありません。

実際の強制（単なる慣習ではなく）が必要な場合、それはエージェントランタイム自体から来る必要があります：

• Claude Code: .claude/settings.json の permissions.deny ルールを使用して、ReadツールがDocs/*.mdに直接触れるのをブロックし、ctx build --auto-phase が生成するCLAUDE.mdへの依存を強制します。Claude Code自身のパーミッションドキュメントを参照してください — これはctx-managerが設定してくれるものではありません。

• MCPクライアント（Cursor、Windsurfなど）: そのクライアントが公開しているファイルシステムアクセス制御があれば、それを使用します — ctx-managerの制御外です。

これらのいずれかがない場合、ctx-manager はエージェントが従うことが期待される慣習であり、検証済みのセッション履歴（台帳）によって裏付けられています — サンドボックスではありません。

開発

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

ライセンス

MIT — LICENSE を参照。