ctx-manager

다중 언어 에이전트 개발을 위한 공급자 중립적(provider-agnostic) 컨텍스트 엔지니어링 CLI + MCP 서버.

ctx-manager는 Docs/ 폴더(PRD, 아키텍처 문서, 단계별 계획, API 스펙)와 AI 코딩 에이전트(Claude Code, Cursor, Windsurf) 사이에 위치하여 두 가지 방식으로 토큰 비용을 절감합니다:

• 결정적(Deterministic), 헤더 기반 문서 슬라이싱 — 블루프린트 파일에서 필요한 섹션만 정확히 가져오고, 전체를 가져오지 않습니다. 구조적(Markdown 헤더에 대한 정규식) 방식이며, RAG/임베딩이 아닙니다.

• 추가 전용(append-only), git 검증 Memory_Ledger.md — 정확한 세션 상태를 기록하여 에이전트가 이미 구축된 내용을 다시 유도하거나 환각(hallucinate)하지 않도록 합니다. 모든 항목은 검증됨(verified)으로 표시되기 전에 실제 git status 출력과 대조됩니다.

Rust, Go, TypeScript, Python 또는 다른 어떤 스택에서도 동일하게 작동합니다 — ctx-manager는 애플리케이션 소스 코드를 건드리지 않고 Docs/만 다룹니다.

설치

uvx --from ctx-manager ctx --help

가상환경 설정도, 전역 설치도 필요 없습니다.

Related MCP server: Claude Session MCP

사용법

헤더로 블루프린트 파일 슬라이싱:

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

일치하는 섹션의 내용을 stdout으로 출력합니다 — CLAUDE.md나 에이전트가 컨텍스트를 읽는 곳으로 파이프하세요.

원장(ledger) 기록을 기반으로 다음 단계 자동 슬라이싱:

ctx build --auto-phase

Memory_Ledger.md에서 가장 최근 완료된 단계를 읽고, Phase_file.md에서 다음 단계의 섹션을 자동으로 슬라이싱합니다 — 수동 --slice 대상이 필요 없습니다. 원장에 완료된 단계 항목이 없으면 경고와 함께 Phase 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 통합

세션 전 CLAUDE.md 자동 새로고침(--auto-phase), 세션 후 원장 자동 기록을 위한 SessionStart/SessionEnd 훅 예시는 examples/claude_code_hooks/에 있습니다.

설계 원칙

1. Docs/ 입력, Docs/ 출력 — 어떤 언어에서도 애플리케이션 소스를 건드리지 않습니다.

2. 무거운 것보다 가벼운 것 — 임베딩보다 표준 라이브러리 re, git 라이브러리보다 subprocess git, 네트워크 서비스보다 로컬 stdio.

3. 추가 전용 원장 — 어떤 코드 경로도 Memory_Ledger.md를 통째로 덮어쓰지 않습니다. 절대로.

4. 조용히 실패하지 않고 크게 실패 — 헤더나 파일이 없으면 명시적 오류를 반환하며, 에이전트가 환각할 수 있는 빈 내용을 반환하지 않습니다.

전체 설계 문서는 Docs/Architecture.md와 Docs/PRD.md를 참조하세요 (이 프로젝트는 스스로를 도그푸딩(dogfooding)합니다 — 자체 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 참조.