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. Codex and Cursor read the generated AGENTS.md directly; an existing .cursorrules is refreshed to point at it.)
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 --install-hook .init scaffolds the full pack and the 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 the full 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
By default it writes one shared route to AGENTS.md and a literal @AGENTS.md import to CLAUDE.md. An existing .cursorrules, or a GEMINI.md that already carries a managed block, is refreshed to point at AGENTS.md; a new GEMINI.md is created only with --include-gemini. Use --layout per-agent only for the legacy provider-specific layout.
To migrate a filled pack you maintain, run agent-context routing . and review the diff. This changes only managed routing blocks, preserving pack content, handwritten notes and the file's line endings. It rejects ambiguous linked files or malformed markers before writing. Installing or upgrading the package does not migrate any repository.
| 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, scaffolds the full pack 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 --install-hook . # scaffold the full pack (tier 3 is the default)
agent-context routing . # one AGENTS.md, CLAUDE.md imports it (@AGENTS.md)
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 v0.5 canonical layout gives every agent the same task-based entry contract.
The legacy --layout per-agent option preserves the two historical routing 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.
The full pack (tier 3, 11 files) is the only shape new packs should use, and it is the
default for init. A small repo simply fills fewer routes and contracts; the verifier
still enforces that every reference resolves.
The smaller tiers are deprecated for new packs as of v0.5.0 and will be removed from
init in v0.6.0. A tier-1 pack (code map + search scope) gives a current agent little
more than grep, and tier 2 still lacks the routed authority layer that makes a pack
worth loading. routing and verify keep supporting existing tier 1-2 packs.
| Tier | Files | Status | Direct CLI scaffold |
|---|---|---|---|
| 3 full | 11 | Default. Routed authority layer, contracts, reporting rules | init --install-hook . |
| 2 standard | 6 | Deprecated for new packs; existing packs stay supported | init --tier 2 . (warns) |
| 1 minimal | 2 | Deprecated for new packs; existing packs stay supported | init --tier 1 . (warns) |
To move an existing tier 1-2 pack to the full shape, add the missing templates from
templates/ by hand (or ask the skill to "promote this pack"), fill them, then run
agent-context routing . and agent-context verify .. Do not use init --force: it
replaces filled content.
| Example | Size | Why look at it |
|---|---|---|
examples/hello-service/ |
8 files | Read a whole filled pack in five minutes (a legacy tier-2 shape, kept as the compatibility fixture) |
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.