agent-context

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.

Quickstart

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/main

Open a PR with .agent-context/, the managed routing blocks, and any CI/hook follow-up the skill recommends.

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 .

Why This Exists

What Gets Created

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

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.

How It Works

The product experience is skill-first:

1. Ask the agent to use the agent-context skill.
2. The skill inventories the repo, scaffolds the full pack when needed, fills templates, and writes grep-backed acceptance tests.
3. The CLI verifies structure, JSON schema, real glob matches, template cleanup, and freshness.
4. 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 routing --layout canonical .     # 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 audit

init is a bootstrap command. verify and freshness are what make agent-written context safe to commit.

Results

Q2 2026 multi-agent rerun

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.

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

Historical reference

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.

Agent Architectures

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.

Tested Repositories

The Q2 rerun used the same general-purpose template across six code repos with zero template modifications.

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.

Pack shape (tiers)

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.

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.

Examples

Comparison

For multi-agent session visibility and messaging, pair with agent-chorus.

Documentation

Project Scope

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.