{"id":50559814,"url":"https://github.com/jonaskahn/agent-context","last_synced_at":"2026-06-04T11:01:34.134Z","repository":{"id":353538734,"uuid":"1219913591","full_name":"jonaskahn/agent-context","owner":"jonaskahn","description":"🚀 Evidence-driven context engineering for AI agents coding","archived":false,"fork":false,"pushed_at":"2026-05-14T10:38:30.000Z","size":96,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-14T11:44:12.423Z","etag":null,"topics":["claude-code","claude-code-plugin","claude-code-skills","claude-skills","cursor-rules"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jonaskahn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-24T10:53:52.000Z","updated_at":"2026-05-14T10:17:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jonaskahn/agent-context","commit_stats":null,"previous_names":["jonaskahn/agent-context"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/jonaskahn/agent-context","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonaskahn%2Fagent-context","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonaskahn%2Fagent-context/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonaskahn%2Fagent-context/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonaskahn%2Fagent-context/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jonaskahn","download_url":"https://codeload.github.com/jonaskahn/agent-context/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonaskahn%2Fagent-context/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33901305,"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-06-04T02:00:06.755Z","response_time":64,"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":["claude-code","claude-code-plugin","claude-code-skills","claude-skills","cursor-rules"],"created_at":"2026-06-04T11:01:33.404Z","updated_at":"2026-06-04T11:01:34.128Z","avatar_url":"https://github.com/jonaskahn.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"assets/logo.svg\" width=\"88\" alt=\"agent-context\"\u003e\n\n# agent-context\n\n**Give your AI agent a real map of your codebase — not a polite fiction.**\n\n\u003csub\u003e\nReads \u003ca href=\"https://github.com/Lum1104/understand-anything\"\u003eUnderstand-Anything\u003c/a\u003e knowledge graphs → emits \u003ccode\u003eAGENTS.md\u003c/code\u003e, \u003ccode\u003eCLAUDE.md\u003c/code\u003e, \u003ccode\u003edocs/agents/\u003c/code\u003e.\u003cbr\u003e\nEvery line traces back to a graph node or edge. Nothing is invented.\n\u003c/sub\u003e\n\n\u003c/div\u003e\n\n---\n\nMost AI context files are one of two things: empty scaffolds stuffed with `[to fill]` placeholders, or\nconfident-sounding LLM boilerplate with no connection to actual code. Either way, they actively hurt. A 2025 ETH Zurich\nstudy found auto-generated context files *reduced* task success in **5 of 8 test settings** and added up to **4 extra\nsteps per task**.\n\nThe problem is not the format. It is the evidence.\n\n## ✨ What makes this different\n\n| Typical context tooling                                | agent-context                                                                            |\n|--------------------------------------------------------|------------------------------------------------------------------------------------------|\n| Generates plausible-sounding filler                    | Emits only what the graph supports                                                       |\n| Requires manual editing of dozens of `[to fill]` slots | One `[to fill]` remains — Mock stance in `testing.md` — because that genuinely needs you |\n| Safety rules live as polite markdown suggestions       | Safety rules are wired as deny-list hooks in `.claude/settings.json`                     |\n| One giant file loaded every session                    | Three-tier loading: always-on kernel, path-scoped rules, on-demand depth                 |\n| Re-run to get the same scaffold again                  | Freshness check — warns when the graph is stale vs HEAD                                  |\n\n## 🔄 How it works\n\n```\n ┌─────────────────────┐     ┌──────────────────────────────┐     ┌────────────────────────────┐\n │     Your repo       │     │      Understand-Anything     │     │       agent-context        │\n │                     │     │                              │     │                            │\n │  src/               │     │  /understand                 │     │  /agent-context            │\n │  package.json  ──────────►│  knowledge-graph.json   ──────────►│  AGENTS.md                 │\n │  go.mod             │     │                              │     │  docs/agents/              │\n │  ...                │     │  /understand-domain          │     │  .claude/settings.json     │\n │                     │     │  domain-graph.json      ──────────►│  CLAUDE.md                 │\n └─────────────────────┘     └──────────────────────────────┘     └────────────────────────────┘\n       your code                   real analysis graphs                  context files\n```\n\n**Understand-Anything** does the heavy lifting: it walks your source, identifies architectural layers, maps import\nrelationships, and builds a dependency-ordered guided tour of the codebase. **agent-context** is a translator — it takes\nthose graphs and renders them into the specific files AI agents read. The two tools are loosely coupled; you can\nregenerate either independently.\n\n## 📁 Output at a glance\n\n```\nyour-repo/\n│\n├── AGENTS.md                ◄── 🔑 the kernel  (\u003c100 lines, loaded every session)\n├── CLAUDE.md                ◄── 🔗 one-line shim: @AGENTS.md\n├── CLAUDE.local.md          ◄── 🔒 gitignored personal prefs\n├── CONVENTIONS.md           ◄── 🔄 starter stub | legacy AGENTS.md copy | skipped (user choice on first run)\n│\n├── .claude/\n│   └── settings.json        ◄── 🛡️  deny-list hooks (rm -rf, force-push, .env writes...)\n│\n├── .cursor/rules/\n│   └── agents.mdc           ◄── 🔄 Cursor rules (synced from AGENTS.md)\n│\n├── .github/\n│   └── copilot-instructions.md  ◄── 🔄 GitHub Copilot (synced from AGENTS.md)\n│\n├── .codex/\n│   └── instructions.md      ◄── 🔄 OpenAI Codex (synced from AGENTS.md)\n│\n├── .aider.conf.yml          ◄── 🔄 Aider config (points to CONVENTIONS.md)\n│\n└── docs/agents/             ◄── 📚 on-demand depth (loaded only when referenced)\n    ├── architecture.md           project overview · stack · quick start · layer map · guided tour\n    ├── flow.md                   domain flows · entry points · triggers (single file when ≤8 flows)\n    ├── flows/                    folder mode (\u003e8 flows): index.md + one file per domain\n    │   ├── index.md              domains, flow counts, cross-domain edges\n    │   └── \u003cdomain\u003e.md           per-domain flows with entry points and triggers\n    ├── patterns.md               complexity hotspots · function exemplars · hub imports\n    ├── glossary.md               domain vocabulary from the domain graph (or stub)\n    ├── conventions.md            team coding standards (if CONVENTIONS.md exists)\n    ├── testing.md                runner · file layout · single-test command\n    └── tech-debt.md              known gotchas format (you fill this over time)\n```\n\nWith `--with-ci`, two additional files are generated:\n\n```\n├── .github/workflows/\n│   └── agent-context-freshness.yml  ◄── ⚙️ CI freshness check\n└── hooks/\n    └── check-freshness.sh           ◄── ⚙️ pre-commit hook\n```\n\n## 🚀 Getting started\n\n### Step 1 — Analyse your repo with Understand-Anything\n\nagent-context does not analyse code. Understand-Anything does.\n\n```shell\n/plugin marketplace add Lum1104/.understand-anything\n/plugin install understand-anything\n```\n\nThen, inside the repo you want to generate context for:\n\n```shell\n/understand\n```\n\nThis produces `./.understand-anything/knowledge-graph.json`. For a populated glossary and business flow map, also run:\n\n```shell\n/understand-domain\n```\n\n### Step 2 — Install agent-context\n\n```shell\n/plugin marketplace add jonaskahn/agent-context\n/plugin install agent-context\n```\n\n### Step 3 — Generate\n\n```shell\n/agent-context\n```\n\nAll output files are written in one pass.\n\n## 🔑 AGENTS.md — the always-on kernel\n\nEvery AI agent loads `AGENTS.md` on every turn. It is deliberately kept under 100 lines, because every irrelevant token\nin a shared attention window degrades output quality across all frontier models. When the kernel is tight and accurate,\nagents stop asking \"where does X live?\" and start making correct edits on the first try.\n\nEach section is derived directly from graph data — never invented:\n\n| # | Section                     | Source                                                                   |\n|---|-----------------------------|--------------------------------------------------------------------------|\n| 1 | **Architectural Altitude**  | Tour steps — the dependency-ordered walkthrough of the codebase          |\n| 2 | **Module Map**              | Layers — pre-computed by Understand-Anything, one bullet per layer       |\n| 3 | **Commands**                | `package.json` / `pyproject.toml` / `Cargo.toml` / `go.mod`              |\n| 4 | **Non-Obvious Conventions** | Cross-layer import anomalies, naming deviators, path/layer disagreements |\n| 5 | **Safety**                  | Static rules, enforced by `.claude/settings.json` hooks                  |\n| 6 | **Deeper Context**          | Pointers to `docs/agents/` — loaded on demand, not always                |\n\nIf a section has no graph evidence behind it, it is **omitted entirely**. No padding. No filler.\n\n## 📚 docs/agents/ — on-demand depth\n\nThese files are never loaded automatically. They exist to be referenced — `@docs/agents/architecture.md` in a task\nprompt, or linked from `AGENTS.md §6`. This keeps the always-on token budget low while still making deep context\navailable when a task actually needs it.\n\n- **`architecture.md`** — project name, one-line summary, detected framework and language, quick-start commands, then\n  every layer mapped with files sorted by inbound-import count. Entry points (zero incoming imports) called out\n  separately. Cross-layer dependency counts show where the architecture has coupling.\n\n- **`flow.md` or `flows/`** — strictly derived from `domain-graph.json`. Each business flow is listed with its trigger\n  type and entry-point file. **Single-file mode** (`docs/agents/flow.md`) when the domain graph has ≤8 flows;\n  **folder mode** (`docs/agents/flows/index.md` + one file per domain) when it has more. The plugin auto-migrates\n  between modes on subsequent runs — old artefacts are deleted before the new mode is written. When the domain graph\n  is missing or empty, `flow.md` becomes a one-line stub pointing at `/understand-domain` (no import-graph fallback —\n  that lives in `architecture.md`).\n\n- **`patterns.md`** — files the analyser flagged as `complex` with their function counts. Representative functions per\n  layer with `file:line` references. The ten most-imported \"hub\" files whose changes ripple everywhere.\n\n- **`glossary.md`** — populated from the domain graph's non-heuristic entries. If the domain analysis is purely\n  structural, this file is an honest stub that tells you what to do next rather than emitting noise.\n\n- **`testing.md`** — derives runner, file layout convention, and single-test command from the build manifest and node\n  path patterns. The one remaining `[to fill]` lives here: Mock stance, because no graph can tell you whether your team\n  mocks the database.\n\n- **`tech-debt.md`** — a stub with entry format instructions. Fills over time as real work surfaces real gotchas.\n\n## ⚙️ Command reference\n\n```\n/agent-context [path] [--force] [--dry-run] [--with-ci]\n```\n\n| Flag        | What it does                                                                                                                       |\n|-------------|------------------------------------------------------------------------------------------------------------------------------------|\n| `[path]`    | Target repo directory. Defaults to the current working directory.                                                                  |\n| `--force`   | Overwrite existing output files. `.claude/settings.json` and `.gitignore` always merge regardless of this flag.                    |\n| `--dry-run` | Print every file that would be written to stdout. Touch nothing on disk.                                                           |\n| `--with-ci` | Also generate `.github/workflows/agent-context-freshness.yml` and `hooks/check-freshness.sh` for automated graph staleness checks. |\n\n\u003cdetails\u003e\n\u003csummary\u003eSample output\u003c/summary\u003e\n\n```\nagent-context — summary\n\nGates:\n  ✓ knowledge-graph.json present (v1.0.0, analysed 2026-04-23, commit 0c97930)\n  ✓ domain-graph.json present (quality: mixed)\n\nFiles:\n  ✓ AGENTS.md                      (84 lines)\n  ✓ CLAUDE.md                      (1 line)\n  ✓ CLAUDE.local.md                (3 lines)\n  ✓ .claude/settings.json          (created)\n  ✓ docs/agents/architecture.md     (301 lines)\n  ✓ docs/agents/flow.md             (38 lines)\n  ✓ docs/agents/patterns.md         (156 lines)\n  ✓ docs/agents/glossary.md         (48 lines; 6 entries)\n  ✓ docs/agents/testing.md          (22 lines)\n  ✓ docs/agents/tech-debt.md        (stub, 14 lines)\n  ✓ .gitignore                     (appended CLAUDE.local.md)\n\nCross-vendor:\n  ✓ .cursor/rules/agents.mdc       (synced from AGENTS.md)\n  ✓ .github/copilot-instructions.md (synced from AGENTS.md)\n  ✓ .codex/instructions.md          (synced from AGENTS.md)\n  ✓ CONVENTIONS.md                   (synced from AGENTS.md)\n  ✓ .aider.conf.yml                 (created)\n\nLint (AGENTS.md, 6 checks):\n  ✓ 6/6 passed\n\nNext:\n  1. Review AGENTS.md — confirm commands and conventions look right.\n  2. Hand-curate docs/agents/glossary.md if business terms are missing.\n  3. Fill Mock stance in docs/agents/testing.md.\n```\n\nWhen the knowledge graph is stale relative to HEAD, a banner is inserted directly into `AGENTS.md`:\n\n```\n⚠ knowledge-graph.json was generated against commit 0c97930 but the\n  repo is at abc1234. Generated files may be out of date.\n  Re-run /understand for the best results.\n```\n\n\u003c/details\u003e\n\n## 🔁 Keeping it fresh\n\nThe plugin compares `project.gitCommitHash` in the graph against `git rev-parse HEAD`. If they differ, the stale banner\nappears in `AGENTS.md`. To regenerate after new commits:\n\n```\n/understand\n/agent-context --force\n```\n\n## 🏗️ Design decisions\n\n**🔍 Evidence over scaffolding** — Every line in the output traces back to a graph node, edge, layer, or build manifest\nentry. If the evidence does not exist, the line does not exist. This is what prevents the \"confident but wrong\" output\nthat makes auto-generated context files so damaging.\n\n**🔒 Hooks, not prose** — A sentence in markdown saying \"don't run `rm -rf`\" is a suggestion. A deny-list entry in\n`.claude/settings.json` is enforcement. Destructive operations, secret writes, force-pushes, and migration-path edits\nare blocked at the hook layer, not requested in prose.\n\n**📐 Three-tier loading** — `AGENTS.md` stays under 100 lines and is loaded on every turn. `docs/agents/*.md` files are\non-demand — they exist to be referenced, not auto-loaded. This architecture keeps the always-on token budget low without\nsacrificing depth.\n\n**☝️ One source of truth** — `AGENTS.md` is canonical. `CLAUDE.md` is a one-line shim (`@AGENTS.md`). Cross-vendor\nfiles (`.cursor/rules/agents.mdc`, `.github/copilot-instructions.md`, `.codex/instructions.md`, `CONVENTIONS.md`) are\nall derived from the same rendered AGENTS.md content. One edit, every tool synced.\n\n**✅ Self-linting output** — After writing `AGENTS.md`, the plugin reads it back and runs 6 mechanical checks: line count\n≤100, numbered H2s only, bold taglines, `The test:` sentences, no ALLCAPS safety keywords, single code fence. Failures\nare reported in the summary but never block the run — partial output beats no output.\n\n## 🔄 Cross-vendor support\n\nEvery AI coding tool reads a different file. agent-context writes all of them from the same source:\n\n| Tool           | File                                 | How it's generated                        |\n|----------------|--------------------------------------|-------------------------------------------|\n| Claude Code    | `AGENTS.md` + `CLAUDE.md`            | Primary output — the kernel               |\n| Cursor         | `.cursor/rules/agents.mdc`           | AGENTS.md content with `.mdc` frontmatter |\n| GitHub Copilot | `.github/copilot-instructions.md`    | AGENTS.md verbatim                        |\n| OpenAI Codex   | `.codex/instructions.md`             | AGENTS.md verbatim                        |\n| Aider          | `CONVENTIONS.md` + `.aider.conf.yml` | Starter stub / legacy AGENTS.md copy / skip (user choice) |\n\nAll vendor files follow the same skip/force/dry-run logic as core files. When you run `/agent-context --force`, every\nvendor file is regenerated from the current graph state.\n\n**Existing `CONVENTIONS.md`?** If your repo already has a `CONVENTIONS.md` (or `conventions.md`) with team-authored\ncoding standards, the plugin won't overwrite it. Instead, it reads the content and merges it into `AGENTS.md` as a\ndedicated `§7 Team Conventions` section — which then propagates to every vendor file. Human-authored rules take\npriority over graph-derived defaults.\n\n**No `CONVENTIONS.md` yet?** On the first run the plugin asks how to handle it via an interactive prompt:\n\n| Option                | Behavior                                                                                      |\n|-----------------------|-----------------------------------------------------------------------------------------------|\n| **Starter stub** *(default)* | Write a minimal `CONVENTIONS.md` with empty Safety / Naming / Patterns / Workflow sections so the team can fill them in. The next run picks up the populated file and distills it into `docs/agents/conventions.md`. |\n| **Skip**              | No `CONVENTIONS.md` is created. Other outputs are unaffected.                                 |\n| **Legacy**            | Write `CONVENTIONS.md` as a verbatim copy of `AGENTS.md` (the previous default — useful when you want Aider to consume the same kernel). |\n\nUnder `--dry-run` or in headless invocations the prompt is skipped and the starter-stub option is used.\n\n## 🔧 Compatibility\n\nWorks with any repo that Understand-Anything can analyse. Tested against TypeScript/Nuxt, Python, Go, and Rust projects.\nThe plugin does not read or modify source files — it writes only the files listed in the output tree above.\n\n## 📖 Specification\n\nThe complete implementation spec lives at `agent-context-plugin/skills/agent-context/references/PLAN.md`. It contains\nthe authoritative graph schemas, the 20-rule AGENTS.md style rubric, per-file content contracts, all rendering\ntemplates, the five convention-mining signals, and the cadence-admin reference sample with expected output.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonaskahn%2Fagent-context","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjonaskahn%2Fagent-context","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonaskahn%2Fagent-context/lists"}