{"id":51714822,"url":"https://github.com/cote-star/agent-context","last_synced_at":"2026-07-17T01:35:28.538Z","repository":{"id":355680932,"uuid":"1216060878","full_name":"cote-star/agent-context","owner":"cote-star","description":"Navigation contract for AI coding agents in large repos. Templates, validation scripts, and a Python CLI for authoring three-layer context packs. Companion to the agent-recall research.","archived":false,"fork":false,"pushed_at":"2026-06-24T17:28:20.000Z","size":18848,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-17T01:35:16.601Z","etag":null,"topics":["agent-context","agent-navigation","ai-agents","bounded-search","claude","claude-code","cli","codex","context-engineering","context-pack","cursor","developer-tools","gemini-cli","llm-tools","local-first","multi-agent","navigation","python","repo-navigation","session-handoff"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cote-star.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-20T14:24:15.000Z","updated_at":"2026-06-24T17:29:02.000Z","dependencies_parsed_at":null,"dependency_job_id":"5e193734-d5ff-43ac-b414-0ed89d7d36f6","html_url":"https://github.com/cote-star/agent-context","commit_stats":null,"previous_names":["cote-star/agent-context"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/cote-star/agent-context","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cote-star%2Fagent-context","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cote-star%2Fagent-context/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cote-star%2Fagent-context/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cote-star%2Fagent-context/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cote-star","download_url":"https://codeload.github.com/cote-star/agent-context/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cote-star%2Fagent-context/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35563613,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-16T02:00:06.687Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-context","agent-navigation","ai-agents","bounded-search","claude","claude-code","cli","codex","context-engineering","context-pack","cursor","developer-tools","gemini-cli","llm-tools","local-first","multi-agent","navigation","python","repo-navigation","session-handoff"],"created_at":"2026-07-17T01:35:28.107Z","updated_at":"2026-07-17T01:35:28.532Z","avatar_url":"https://github.com/cote-star.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# agent-context\n\n![License](https://img.shields.io/badge/license-MIT-blue.svg)\n![Version](https://img.shields.io/badge/version-0.4.2-green.svg)\n![Python](https://img.shields.io/badge/python-3.8%2B-blue.svg)\n\n**Portable system context for agents, checked into the repo.**\n\nAgents 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.\n\nThe **skill authors** the pack. The **CLI verifies** it, checks freshness, and makes it safe to commit.\n\n![agent-context impact at a glance](https://raw.githubusercontent.com/cote-star/agent-context/main/docs/visuals/hero-stat-ribbon.svg)\n\n## Quickstart\n\nTwo commands set up both the CLI and the bundled skill:\n\n```bash\nuv tool install agent-context-cli       # or: pipx install agent-context-cli\nagent-context install-skill --agent claude\n```\n\n(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.)\n\nIn the repo you want to improve, ask:\n\n\u003e **Use the agent-context skill to build context for this repo.**\n\nThen make the generated diff reviewable:\n\n```bash\nagent-context verify .\nagent-context freshness . --base-ref origin/main\n```\n\nOpen a PR with `.agent-context/`, the managed routing blocks, and any CI/hook follow-up the skill recommends.\n\n\u003cdetails\u003e\n\u003csummary\u003eAdvanced/manual/scripted setup (from a clone)\u003c/summary\u003e\n\nUse the CLI from a clone when no agent is in the loop, or when bootstrapping repos in scripts:\n\n```bash\ngit clone https://github.com/cote-star/agent-context.git ~/agent-context\ncd /path/to/your-repo\n~/agent-context/bin/agent-context init --tier 3 --install-hook .\n```\n\n`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.\n\u003c/details\u003e\n\n## Why This Exists\n\n| Capability | What it gives you |\n|---|---|\n| **Agent-authored context** | One prompt produces a reviewable `.agent-context/` PR instead of a private model memory. |\n| **Cross-agent routing** | Cursor, Claude, Codex, Gemini, OpenCode, and human reviewers consume the same checked-in pack. |\n| **Machine checks** | `verify`, `freshness`, `doctor`, and `install-hook` make the artifact auditable locally and in CI. |\n| **Evidence-backed workflow** | Q2 2026 rerun: 288 graded tasks across 48 cells, plus a historical reviewer-confirmed run set. |\n| **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. |\n| **Zero infrastructure** | Markdown and JSON committed to your repo. No server, vector store, crawler, or API key. |\n\n## What Gets Created\n\nThe skill and CLI scaffold a tiered pack under `.agent-context/current/`:\n\n```text\n.agent-context/current/\n├── 00_START_HERE.md\n├── 10_SYSTEM_OVERVIEW.md\n├── 20_CODE_MAP.md\n├── 30_BEHAVIORAL_INVARIANTS.md\n├── 40_OPERATIONS_AND_RELEASE.md\n├── routes.json\n├── completeness_contract.json\n├── reporting_rules.json\n├── search_scope.json\n├── manifest.json\n└── acceptance_tests.md\n\n.agent-context/tools/\n├── verify_agent_context.py\n├── check_freshness.sh\n└── pre-push-hook.sh\n```\n\nIt also writes short managed routing blocks to `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, and `.cursorrules` so agents read the pack before opening source files.\n\n| Layer | Files | Job |\n|---|---|---|\n| **Content** | `00_*` through `40_*` markdown | Human-readable map, risks, invariants, operations |\n| **Authority** | `routes.json`, `completeness_contract.json`, `reporting_rules.json` | Completeness rules for trust-and-follow agents |\n| **Navigation** | `search_scope.json` | Scoped search and verification shortcuts for search-and-verify agents |\n| **Quality** | `manifest.json`, `acceptance_tests.md`, helper tools | Validation, freshness, and PR review support |\n\n## How It Works\n\nThe product experience is skill-first:\n\n1. **Ask the agent** to use the `agent-context` skill.\n2. **The skill inventories the repo**, chooses the right tier, scaffolds files when needed, fills templates, and writes grep-backed acceptance tests.\n3. **The CLI verifies** structure, JSON schema, real glob matches, template cleanup, and freshness.\n4. **You review the diff** like code and merge it through PR.\n\nThe CLI remains intentionally boring:\n\n```bash\nagent-context init --tier 3 --install-hook .   # scaffold\nagent-context verify .                         # validate pack integrity\nagent-context freshness . --base-ref origin/main\nagent-context doctor                           # local setup audit\n```\n\n`init` is a bootstrap command. `verify` and `freshness` are what make agent-written context safe to commit.\n\n## Results\n\n### Q2 2026 multi-agent rerun\n\nCurrent 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.\n\n| Agent / Model | Bare yes-rate | Structured yes-rate | Δ |\n|---|---:|---:|---:|\n| **Claude Opus 4.7** | 80% (4.80/6) | **100% (6.00/6)** | +20pp |\n| **Cursor `claude-opus-4-7-medium`** | 89% (5.33/6) | **97% (5.83/6)** | +8pp |\n| **Cursor `composer-2-fast`** | 61% (3.67/6) | **81% (4.83/6)** | +20pp |\n| **Codex CLI 0.130.0** | 72% (4.33/6) | **78% (4.67/6)** | +6pp |\n\nHeadline stories:\n\n- **Claude Opus + structured: 6/6 across all 6 repos.**\n- **Cursor `composer-2-fast`: largest correctness lift** at +20 percentage points.\n- **Cursor Opus medium: 219s → 78s median duration** under structured context.\n- **Production-risk flags drop to zero** for Codex and Cursor Opus medium with structured context.\n\nGrading 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](https://github.com/cote-star/agent-context/blob/main/docs/evidence/metrics.md#methodology-and-disclosure).\n\n→ [Full Q2 results](https://github.com/cote-star/agent-context/blob/main/docs/evidence/results.md#q2-2026-multi-agent-rerun-current-evidence) · [headline metrics](https://github.com/cote-star/agent-context/blob/main/docs/evidence/metrics.md) · [evidence dashboard](https://cote-star.github.io/agent-recall/docs/)\n\n### Historical reference\n\nThe 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.\n\n| Metric | Bare | With agent-context | Change |\n|---|---:|---:|---:|\n| Correct answers | 50% | 88% | **+76%** |\n| Files opened by Claude | 6.3 | 1.9 | **~70% fewer** |\n| Tokens used by Claude | 38.6K | 13.1K | **~66% fewer** |\n| Dead ends | 2-3 per repo | 0 | **eliminated** |\n| Production-risk answers | 7 total | 0 | **eliminated** |\n\n![agent-context proof summary — per-agent + historical](https://raw.githubusercontent.com/cote-star/agent-context/main/docs/visuals/proof-results.svg)\n\n## Agent Architectures\n\nThe same `.agent-context/` pack serves two opposite loops:\n\n```text\nTrust-and-follow: Claude, Gemini, OpenCode with Anthropic backend\n  routing block → required files → completeness contract → answer\n\nSearch-and-verify: Cursor, Codex, OpenCode with local model\n  search scope → scoped grep → verification shortcut → answer\n```\n\nClaude-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.\n\n![Explorable recall as a three-track system](https://raw.githubusercontent.com/cote-star/agent-context/main/docs/evidence/figures/three-tracks-importance-minimal.svg)\n\n## Tested Repositories\n\nThe Q2 rerun used the same general-purpose template across six code repos with zero template modifications.\n\n| Repo type | Stack | Notes |\n|---|---|---|\n| CLI/library | Rust + Node.js | `agent-chorus` |\n| ML pipeline | Python | training/inference workflow |\n| React frontend | TypeScript | React Query + Zustand |\n| Backend service | Python | FastAPI service |\n| Polyglot monorepo | mixed | multi-language workspace |\n| macOS daemon | Swift | process broker / daemon |\n\nThe 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.\n\n**Non-code corpora are not yet validated.** The design is intentionally broader than repos, but public evidence currently covers code repositories only.\n\n## Tiers\n\nStart small. Promote only when the repo needs more structure.\n\n| Tier | Files | Best for | Direct CLI scaffold |\n|---|---:|---|---|\n| **1** minimal | 2 | Quick adoption, smaller repos | `init --tier 1 .` |\n| **2** standard | 6 | Most teams starting out | `init --tier 2 .` |\n| **3** full | 11 | Complex repos, production workflows | `init --tier 3 --install-hook .` |\n\n## Examples\n\n| Example | Size | Why look at it |\n|---|---:|---|\n| [`examples/hello-service/`](https://github.com/cote-star/agent-context/tree/main/examples/hello-service/) | 6 files | Read the whole pack in five minutes |\n| [`examples/agent-chorus-reference/`](https://github.com/cote-star/agent-context/tree/main/examples/agent-chorus-reference/) | 155 files | Real dual Rust/Node CLI pack |\n\n## Comparison\n\n| | agent-context | Long-term memory | Multi-agent orchestration | agent-chorus |\n|---|---|---|---|---|\n| **Primitive** | Checked-in system context | Stored memory | Worker coordination | Cross-agent session visibility |\n| **Best for** | Cold-start agent work and PR-scoped guidance | Persona/history recall | Delegated task execution | Reading and comparing agent sessions |\n| **Runtime dependency** | none | service/vector store optional | framework runtime | chorus CLI |\n| **Lives in repo** | yes | no | no | no |\n\nFor multi-agent session visibility and messaging, pair with [agent-chorus](https://github.com/cote-star/agent-chorus).\n\n## Documentation\n\n| Need | Document |\n|---|---|\n| First install | [Getting started](https://github.com/cote-star/agent-context/blob/main/docs/getting-started.md) |\n| Architecture deep-dive | [Architecture guide](https://github.com/cote-star/agent-context/blob/main/docs/architecture.md) |\n| Evidence | [Experiment results](https://github.com/cote-star/agent-context/blob/main/docs/evidence/results.md) · [metrics summary](https://github.com/cote-star/agent-context/blob/main/docs/evidence/metrics.md) |\n| Agent-driven creation | [SKILL.md](https://github.com/cote-star/agent-context/blob/main/SKILL.md) |\n| CI setup | [CI adaptation](https://github.com/cote-star/agent-context/blob/main/docs/ci-adaptation.md) |\n| Design rationale | [16 design principles](https://github.com/cote-star/agent-context/blob/main/docs/design-principles.md) |\n| Roadmap | [Roadmap](https://github.com/cote-star/agent-context/blob/main/docs/roadmap.md) |\n\n## Project Scope\n\nThe public `agent-context` CLI, templates, verifier, examples, and evidence docs live here. `chorus` session-reading commands live in [agent-chorus](https://github.com/cote-star/agent-chorus).\n\nFound a bug or a missing system pattern? [Open an issue](https://github.com/cote-star/agent-context/issues).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcote-star%2Fagent-context","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcote-star%2Fagent-context","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcote-star%2Fagent-context/lists"}