{"slug": "agent-contexts-a-tool-to-feed-you-coding-agents", "title": "Agent contexts - A tool to feed you coding agents", "summary": "A developer created agent-contexts, a CLI tool for distributing AGENTS.md files across projects, solving the problem of maintaining multiple agent context files for different AI coding tools. The tool allows centralized curation of context files that can be versioned and installed deterministically into consumer projects.", "body_md": "In the AI era, something funny is happening: side projects that have been collecting dust in `~/code/wishful-thinking/`\n\nare getting dusted off. Suddenly that \"someday I'll write this\" repo on GitHub has a real README, a working CI, and three open issues you actually want to close.\n\nWhy? Because the AI doesn't complain. Doesn't get bored. Doesn't ask \"but why do we need this when we have X?\" at 11pm when all you want is to feel better with yourself, when your children are on the bed and you think \"now is the moment i should use to realize some of my personal projects.\"\n\nSo while the discourse is busy replacing you with LLMs, you're quietly using LLMs to replace the procrastination that used to replace you.\n\nThis post is about one of those moments, one of those ideas born in the night, that probably, in pre-AI era, would have been forgotten behind \"it's too late to open my laptop\": a small CLI called\n\n[ agent-contexts](https://github.com/gadz82/contexts) I wrote because I was sick of having 40\n\n`AGENTS.md`\n\ntabs open across 40 different repos.When you sit down with Claude Code, Cursor, Gemini CLI, or any of the other agentic tools, they don't read your mind. They need to be told things. Some of those things you tell them in chat. But the important stuff — the project conventions, the \"don't do this here\" rules, the \"we use tabs not spaces, fight me\" — should live **in the repo itself**, so every agent (and every teammate) picks them up automatically.\n\nDifferent agents have different conventions for where to look:\n\n`CLAUDE.md`\n\n(and also `AGENTS.md`\n\n, because Anthropic isn't petty).`GEMINI.md`\n\n.`AGENTS.md`\n\n.`.cursorrules`\n\nand similar.So if you're running a polyglot agent setup (and who isn't these days)you're maintaining multiple files per project. That's annoying before you've written a line of code.\n\nThe thing i learned the hard way: **bigger context does not equal better context**.\n\nWhen you feed your agent a 4,000-line `AGENTS.md`\n\ncovering every\n\narchitectural decision from 2019 to today, two things happen:\n\nThe same project rarely wants the same context for every task:\n\nSame repo. Four different `AGENTS.md`\n\nfiles. (Plus nested ones for\n\nsubfolders, because your `src/payments/`\n\ndeserves its own context, thank you very much.)\n\nThe \"obvious\" solution at the beginning was one big monolithic `AGENTS.md`\n\nat the root... but soon you understand the unefficency of that approach. The other \"obvious\" solution currently is a hand-maintained tree of nested `AGENTS.md`\n\nfiles in every folder, it wins on quality but loses on maintenance. The day someone updates the root convention, they have to remember to propagate it. And nobody remembers.\n\nThe Vercel team had a similar itch a while back, and they scratched it with [agent skills](https://github.com/vercel/skills). They treated the bundle of \"things an agent needs to do a job\" (instructions, scripts, references) as a package. So they made it installable. You can `npx skills add <source>`\n\n, the tool fetches the right files, drops them in the right places, and tracks what's installed in a lockfile. Deterministic, versioned, no fuss.\n\nBut skills are about *capabilities*: \"here's how to run my CI\", \"here's how to deploy\", \"here's a script to seed the DB\". They don't really cover the `AGENTS.md`\n\nuse case, where you want to distribute context, not behavior.\n\nSo I built something in the same vein, but scoped to context files.\n\n`agent-contexts`\n\n: npm, but for `AGENTS.md`\n\n[ agent-contexts](https://github.com/gadz82/contexts) is a CLI. The way to think about it:\n\nCurate agent context once in a central git repo. Install it into every\n\nconsumer project. Versioned, deterministic, reproducible.\n\nYou write a `contexts.yml`\n\nat the root of your contexts repo:\n\n```\nversion: \"1\"\nname: engineering-contexts\n\nmappings:\n  \".\":\n    context_source: ./agents/root/AGENTS.md\n    description: Repo-wide conventions\n  src/products:\n    context_source: ./agents/products/AGENTS.md\n    description: Products module\n  src/common/database:\n    context_source: ./agents/database/AGENTS.md\n    description: Sequelize + MySQL integration\n```\n\nEach mapping points a folder in the consumer project at a profile file in the contexts repo. `agent-contexts add`\n\nthen:\n\n`.contexts/cache/<slug>/`\n\n.`contexts.lock`\n\npinning each source to a commit SHA and each file to a SHA-256 hash.`agent-contexts install`\n\nis the `npm ci`\n\nof context. It only reads\n\n`contexts.lock`\n\n, never the manifest, so CI doesn't have to fetch the manifest or guess about upstream availability. Same lock, same files, every time.\n\n`agent-contexts status`\n\nrecomputes truth from disk and exits non-zero if anything is broken, missing, or hand-edited. Easy CI gate.\n\nSometimes you need a different context for the same folder, depending on what you're doing.\n\nSay your repo has a default tone — calm, professional, focused on the production codebase. But today you're refactoring and you want a more pedagogical tone with extra \"before you change this, consider…\" notes. Or you're onboarding a junior dev and you want a glossary of project-specific terms front and center.\n\nYou author those as a **tag**:\n\n```\nmappings:\n  \".\":\n    context_source: ./agents/root/AGENTS.md\n  src/products:\n    context_source: ./agents/products/AGENTS.md\n\ntags:\n  onboarding:\n    mappings:\n      \".\":\n        context_source: ./agents/root/onboarding/AGENTS.md\n      src/products:\n        context_source: ./agents/products/onboarding/AGENTS.md\n  refactor:\n    mappings:\n      src/products:\n        context_source: ./agents/products/refactor/AGENTS.md\n```\n\nSwitch with a flag:\n\n```\nnpx agent-contexts add your-org/your-contexts --tag onboarding\n# or\nnpx agent-contexts update --tag refactor\n```\n\nEffective set is `root ∪ tag`\n\n(tag wins on conflicts), so you only write the differences. The lock records which tag each entry is on, so `install`\n\nreproduces it and `update`\n\nkeeps you there.\n\nNestJS microservice. You want a Star-Wars-toned `AGENTS.md`\n\nfor\n\n`src/products`\n\n— because why not.\n\n```\n# contexts repo\nmkdir -p agents/star-wars\n\ncat > agents/products/AGENTS.md <<'EOF'\n# Products Module\n\nFollow the Repository pattern for data access.\nSplit Read and Write services (CQS-lite).\nUse `class-validator` DTOs for every input.\nEOF\n\ncat > agents/star-wars/products.md <<'EOF'\n# Products Module — The Armory of the Bounty Hunters\n\nThe domain heart, this is. Where artifacts of the holonet catalog,\nmanage you do.\n\n- The Repository pattern, follow — data access through one gate\n- Read and Write services, split — CQS-lite, the path of clarity\n- DTOs with `class-validator`, use — `@nestjs/swagger` for the holomap\nEOF\n\ncat > contexts.yml <<'EOF'\nversion: \"1\"\nmappings:\n  src/products:\n    context_source: ./agents/products/AGENTS.md\n    description: Products module\ntags:\n  star-wars:\n    mappings:\n      src/products:\n        context_source: ./agents/star-wars/products.md\n        description: Products module — Yoda edition\nEOF\n```\n\nIn the consumer project:\n\n```\nnpx agent-contexts add ../your-contexts --tag star-wars --force -y\n# src/products/AGENTS.md is now a relative symlink into the cached file\n# contexts.lock records tag=star-wars + the SHA of the file\n\nnpx agent-contexts status\n# ✓ src/products/AGENTS.md  ok\n\n# Later, switch back to the default tone\nnpx agent-contexts update                       # keeps the recorded tag\nnpx agent-contexts add ../your-contexts -y     # back to root mappings\n```\n\nThat's the whole loop. Symlink in, versioned, switchable, reproducible.\n\nTags turn out to be the right tool for one specific scenario that I keep running into: a CI job that boots a code-review agent on every PR. You don't want that agent reading the same `AGENTS.md`\n\nfiles as your dev-time sessions, you want it focused, skeptical, and pointing at your review checklist, not your \"how to add a new endpoint\" doc.\n\nSo you ship a `ci-code-review`\n\ntag alongside the default one:\n\n```\nmappings:\n  \".\":\n    context_source: ./agents/root/AGENTS.md\n  src/products:\n    context_source: ./agents/products/AGENTS.md\n\ntags:\n  ci-code-review:\n    mappings:\n      \".\":\n        context_source: ./agents/root/ci-review.md\n        description: Code-review checklist + tone for CI agents\n      src/products:\n        context_source: ./agents/products/ci-review.md\n        description: Review-time conventions for the products module\n```\n\nThen the CI job does the swap before invoking the agent:\n\n```\n# restore the lock so the cache is hot\nnpx agent-contexts install\n\n# swap every entry to the CR-specific tone\nnpx agent-contexts update --tag ci-code-review\n\n# boot the reviewer — it picks up AGENTS.md / CLAUDE.md / GEMINI.md\n# that all point at the ci-code-review content\nnpx your-cr-agent\n```\n\nSame project, same lock, completely different `AGENTS.md`\n\ncontent at every target. The dev never sees the CI variant; the CI never sees the dev variant. Both live in the same repo, both are versioned, and a PR against either one is just a normal git workflow.\n\n| Command | What it does |\n|---|---|\n`agent-contexts add <source>` |\nFetch, select mappings, link, write lock. |\n`agent-contexts install` |\nHeadless restore from `contexts.lock` . The `npm ci` . |\n`agent-contexts update` |\nPull upstream, diff, re-pin. |\n`agent-contexts status` |\nPer-entry truth from disk. Exit 5 on problems. |\n`agent-contexts list` |\nPretty table straight from the lock. |\n`agent-contexts reset` |\nUndo: remove links, restore `.bak` backups, delete lock + cache. |\n\nAll commands take `--json`\n\n, `-y`\n\n, `--dry-run`\n\n, and `--verbose`\n\n. None of them need a TTY, so they slot into CI without fuss.\n\nThe full docs and source live at\n\n[ github.com/gadz82/contexts](https://github.com/gadz82/contexts).\n\n**Pros**\n\n`contexts.lock`\n\n, same files, anywhere — laptop,\nCI, your colleague's machine.`npm`\n\n, `cargo`\n\n, or `pip`\n\nalready gets\nit.`AGENTS.md`\n\n, `CLAUDE.md`\n\n, `GEMINI.md`\n\n, whatever your\nagent of the week wants.`--json`\n\neverywhere, deterministic exit codes, no TTY\nneeded, for example you can wire it into a CI job that swaps to a `ci-cr`\n\ntag\nbefore booting the reviewer agent, then walk away.**Cons** *(fair's fair)*\n\n`install`\n\nwon't find anything\nto fetch from. The reason is in the docs (TL;DR: only a git URL is the\nsame string everywhere). Use git for shared/CI; locals are for solo\nexperiments.`..`\n\nescapes, lowercase\nhex hashes, that sort of thing. Read the spec once and you'll stop\nfighting it.`agent-contexts`\n\nversion.If you've ever felt the pain of maintaining `AGENTS.md`\n\nfiles across a fleet of repos — or worse, watching them drift out of sync — give [ agent-contexts](https://github.com/gadz82/contexts) a try. The README is short, the install is one command, and the worst case is that you\n\n`rm`\n\na `.contexts/`\n\nfolder and a `contexts.lock`\n\n.Found a bug? Open an issue. Got a feature idea? Open a PR. Want to yell at me about the name (it should be `agent-context`\n\nand the binary should be `contexts`\n\n, I know, I know)? There's an issue tracker for that too.\n\nAnd a proper thank-you to the [ Vercel Skills](https://github.com/vercel/skills) folks. The shape of\n\nThat's all. Go ship something.", "url": "https://wpnews.pro/news/agent-contexts-a-tool-to-feed-you-coding-agents", "canonical_source": "https://dev.to/francesco_marchesini_d9fb/agent-contexts-a-tool-to-feed-you-coding-agents-5flm", "published_at": "2026-06-17 09:08:32+00:00", "updated_at": "2026-06-17 09:21:20.932625+00:00", "lang": "en", "topics": ["developer-tools", "artificial-intelligence", "large-language-models", "ai-agents"], "entities": ["agent-contexts", "Claude Code", "Cursor", "Gemini CLI", "Anthropic", "Vercel", "agent skills"], "alternates": {"html": "https://wpnews.pro/news/agent-contexts-a-tool-to-feed-you-coding-agents", "markdown": "https://wpnews.pro/news/agent-contexts-a-tool-to-feed-you-coding-agents.md", "text": "https://wpnews.pro/news/agent-contexts-a-tool-to-feed-you-coding-agents.txt", "jsonld": "https://wpnews.pro/news/agent-contexts-a-tool-to-feed-you-coding-agents.jsonld"}}