Portable system context for agents, checked into the repo.
Agents start cold. They re-read the same tree, rediscover the same ownership boundaries, and miss the same hidden invariants. agent-context turns that repeated exploration into a small, reviewable context pack that lives beside the code.
The skill authors the pack. The CLI verifies it, checks freshness, and makes it safe to commit.
Two commands set up both the CLI and the bundled skill:
uv tool install agent-context-cli # or: pipx install agent-context-cli
agent-context install-skill --agent claude(For Codex, register skills/agent-context/agents/openai.yaml with your Codex skill registry. For Cursor, open the target repo; Cursor reads .cursorrules after the pack exists.)
In the repo you want to improve, ask:
Use the agent-context skill to build context for this repo.
Then make the generated diff reviewable:
agent-context verify .
agent-context freshness . --base-ref origin/mainOpen a PR with .agent-context/, the managed routing blocks, and any CI/hook follow-up the skill recommends.
Advanced/manual/scripted setup (from a clone)
Use the CLI from a clone when no agent is in the loop, or when bootstrapping repos in scripts:
git clone https://github.com/cote-star/agent-context.git ~/agent-context
cd /path/to/your-repo
~/agent-context/bin/agent-context init --tier 3 --install-hook .init scaffolds the files and routing blocks. It does not replace the authoring workflow; the pack still needs repo-specific content before verify will pass.
| Capability | What it gives you |
|---|---|
| Agent-authored context | One prompt produces a reviewable .agent-context/ PR instead of a private model memory. |
| Cross-agent routing | Cursor, Claude, Codex, Gemini, OpenCode, and human reviewers consume the same checked-in pack. |
| Machine checks | verify, freshness, doctor, and install-hook make the artifact auditable locally and in CI. |
| Evidence-backed workflow | Q2 2026 rerun: 288 graded tasks across 48 cells, plus a historical reviewer-confirmed run set. |
| Portable pattern | Code repos are the validated venue today; the same context pattern applies to any system with state, rules, risk, and work to do. |
| Zero infrastructure | Markdown and JSON committed to your repo. No server, vector store, crawler, or API key. |
The skill and CLI scaffold a tiered pack under .agent-context/current/:
.agent-context/current/
├── 00_START_HERE.md
├── 10_SYSTEM_OVERVIEW.md
├── 20_CODE_MAP.md
├── 30_BEHAVIORAL_INVARIANTS.md
├── 40_OPERATIONS_AND_RELEASE.md
├── routes.json
├── completeness_contract.json
├── reporting_rules.json
├── search_scope.json
├── manifest.json
└── acceptance_tests.md
.agent-context/tools/
├── verify_agent_context.py
├── check_freshness.sh
└── pre-push-hook.sh
It also writes short managed routing blocks to CLAUDE.md, AGENTS.md, GEMINI.md, and .cursorrules so agents read the pack before opening source files.
| Layer | Files | Job |
|---|---|---|
| Content | 00_* through 40_* markdown |
Human-readable map, risks, invariants, operations |
| Authority | routes.json, completeness_contract.json, reporting_rules.json |
Completeness rules for trust-and-follow agents |
| Navigation | search_scope.json |
Scoped search and verification shortcuts for search-and-verify agents |
| Quality | manifest.json, acceptance_tests.md, helper tools |
Validation, freshness, and PR review support |
The product experience is skill-first:
- Ask the agent to use the
agent-contextskill. - The skill inventories the repo, chooses the right tier, scaffolds files when needed, fills templates, and writes grep-backed acceptance tests.
- The CLI verifies structure, JSON schema, real glob matches, template cleanup, and freshness.
- You review the diff like code and merge it through PR.
The CLI remains intentionally boring:
agent-context init --tier 3 --install-hook . # scaffold
agent-context verify . # validate pack integrity
agent-context freshness . --base-ref origin/main
agent-context doctor # local setup auditinit is a bootstrap command. verify and freshness are what make agent-written context safe to commit.
Current evidence: 288 graded tasks across 48 cells: 6 repos × 4 model variants × bare/structured × 6 tasks. Every structured_fresh clone passed agent-context verify and strict freshness checks before the agent started.
| Agent / Model | Bare yes-rate | Structured yes-rate | Δ |
|---|---|---|---|
| Claude Opus 4.7 | 80% (4.80/6) | 100% (6.00/6) | +20pp |
Cursor claude-opus-4-7-medium |
89% (5.33/6) | 97% (5.83/6) | +8pp |
Cursor composer-2-fast |
61% (3.67/6) | 81% (4.83/6) | +20pp |
| Codex CLI 0.130.0 | 72% (4.33/6) | 78% (4.67/6) | +6pp |
Headline stories:
- Claude Opus + structured: 6/6 across all 6 repos.
- Cursor
composer-2-fast: largest correctness lift at +20 percentage points. - Cursor Opus medium: 219s → 78s median duration under structured context.
- Production-risk flags drop to zero for Codex and Cursor Opus medium with structured context.
Grading is LLM-provisional via independent Claude Code subagents, one fresh-context grader per cell. Treat the Q2 numbers as directional until reviewer spot-audit is complete. Anomalies are disclosed rather than hidden; see metrics methodology.
→ Full Q2 results · headline metrics · evidence dashboard
The March/April 2026 run set used 78+ reviewer-confirmed grades across three repos. It is preserved as a historical reference and is not directly comparable to the Q2 LLM-provisional rerun.
| Metric | Bare | With agent-context | Change |
|---|---|---|---|
| Correct answers | 50% | 88% | +76% |
| Files opened by Claude | 6.3 | 1.9 | ~70% fewer |
| Tokens used by Claude | 38.6K | 13.1K | ~66% fewer |
| Dead ends | 2-3 per repo | 0 | eliminated |
| Production-risk answers | 7 total | 0 | eliminated |
The same .agent-context/ pack serves two opposite loops:
Trust-and-follow: Claude, Gemini, OpenCode with Anthropic backend
routing block → required files → completeness contract → answer
Search-and-verify: Cursor, Codex, OpenCode with local model
search scope → scoped grep → verification shortcut → answer
Claude-like agents can stop when the completeness contract is satisfied. Cursor/Codex-like agents still verify against source, but the pack tells them where to search and what evidence matters.
The Q2 rerun used the same general-purpose template across six code repos with zero template modifications.
| Repo type | Stack | Notes |
|---|---|---|
| CLI/library | Rust + Node.js | agent-chorus |
| ML pipeline | Python | training/inference workflow |
| React frontend | TypeScript | React Query + Zustand |
| Backend service | Python | FastAPI service |
| Polyglot monorepo | mixed | multi-language workspace |
| macOS daemon | Swift | process broker / daemon |
The seventh candidate, org-second-brain, was skipped because its experiment setup caused an interactive Claude session loop. It remains a follow-up, not part of the headline slate.
Non-code corpora are not yet validated. The design is intentionally broader than repos, but public evidence currently covers code repositories only.
Start small. Promote only when the repo needs more structure.
| Tier | Files | Best for | Direct CLI scaffold |
|---|---|---|---|
| 1 minimal | 2 | Quick adoption, smaller repos | init --tier 1 . |
| 2 standard | 6 | Most teams starting out | init --tier 2 . |
| 3 full | 11 | Complex repos, production workflows | init --tier 3 --install-hook . |
| Example | Size | Why look at it |
|---|---|---|
examples/hello-service/ |
6 files | Read the whole pack in five minutes |
examples/agent-chorus-reference/ |
155 files | Real dual Rust/Node CLI pack |
| agent-context | Long-term memory | Multi-agent orchestration | agent-chorus | |
|---|---|---|---|---|
| Primitive | Checked-in system context | Stored memory | Worker coordination | Cross-agent session visibility |
| Best for | Cold-start agent work and PR-scoped guidance | Persona/history recall | Delegated task execution | Reading and comparing agent sessions |
| Runtime dependency | none | service/vector store optional | framework runtime | chorus CLI |
| Lives in repo | yes | no | no | no |
For multi-agent session visibility and messaging, pair with agent-chorus.
| Need | Document |
|---|---|
| First install | Getting started |
| Architecture deep-dive | Architecture guide |
| Evidence | Experiment results · metrics summary |
| Agent-driven creation | SKILL.md |
| CI setup | CI adaptation |
| Design rationale | 16 design principles |
| Roadmap | Roadmap |
The public agent-context CLI, templates, verifier, examples, and evidence docs live here. chorus session-reading commands live in agent-chorus.
Found a bug or a missing system pattern? Open an issue.