Agent contexts - A tool for AI coding agents context management

Francesco Marchesini — Wed, 17 Jun 2026 09:08:32 +0000

In the AI era, something funny is happening: side projects that have been collecting dust in ~/code/wishful-thinking/ are 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.

Why? 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."
So while the discourse is busy replacing you with LLMs, you're quietly using LLMs to replace the procrastination that used to replace you.

This 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
agent-contexts I wrote because I was sick of having 40 AGENTS.md tabs open across 40 different repos.

What Even Is "Context" and Why Should You Care?

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.

Different agents have different conventions for where to look:

Claude Code looks for CLAUDE.md (and also AGENTS.md, because Anthropic isn't petty).
Gemini CLI looks for GEMINI.md.
GitHub Copilot, OpenAI Codex, Cursor, and friends use AGENTS.md.
A bunch of tools also support .cursorrules and 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.

Context Is a Diet, Not a Buffet

The thing i learned the hard way: bigger context does not equal better context.

When you feed your agent a 4,000-line AGENTS.md covering every
architectural decision from 2019 to today, two things happen:

The model gets slower and more expensive.
The model gets worse. Conflicting instructions, ancient context that's no longer relevant, edge cases from a code path that got deleted last year — all of it pollutes the "what to do right now" buffer.

The same project rarely wants the same context for every task:

Building a new feature? You want the architecture overview, the existing patterns, the conventions.
Refactoring existing code? You want the constraints, the dependencies, the "this is load-bearing, don't touch" notes.
Hunting a bug? You want the diagnostics playbook, the logging conventions, the test scaffolding.
Onboarding a new dev (human or AI)? You want the orientation guide: how to run things, where to look first, what's safe to change.

Same repo. Four different AGENTS.md files. (Plus nested ones for
subfolders, because your src/payments/ deserves its own context, thank you very much.)

The "obvious" solution at the beginning was one big monolithic AGENTS.md at 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 files 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.

Enter: Vercel's Skills

The Vercel team had a similar itch a while back, and they scratched it with agent 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>, the tool fetches the right files, drops them in the right places, and tracks what's installed in a lockfile. Deterministic, versioned, no fuss.

But 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 use case, where you want to distribute context, not behavior.

So I built something in the same vein, but scoped to context files.

`agent-contexts`: npm, but for `AGENTS.md`

agent-contexts is a CLI. The way to think about it:

Curate agent context once in a central git repo. Install it into every
consumer project. Versioned, deterministic, reproducible.

How it works

You write a contexts.yml at the root of your contexts repo:

version: "1"
name: engineering-contexts

mappings:
  ".":
    context_source: ./agents/root/AGENTS.md
    description: Repo-wide conventions
  src/products:
    context_source: ./agents/products/AGENTS.md
    description: Products module
  src/common/database:
    context_source: ./agents/database/AGENTS.md
    description: Sequelize + MySQL integration

Each mapping points a folder in the consumer project at a profile file in the contexts repo. agent-contexts add then:

Materializes the contexts repo into a git-ignored cache: .contexts/cache/<slug>/.
Drops relative symlinks at every target path. (Yes, relative - so the project still works after you move it.)
Writes a contexts.lock pinning each source to a commit SHA and each file to a SHA-256 hash.

agent-contexts install is the npm ci of context. It only reads
contexts.lock, never the manifest, so CI doesn't have to fetch the manifest or guess about upstream availability. Same lock, same files, every time.

agent-contexts status recomputes truth from disk and exits non-zero if anything is broken, missing, or hand-edited. Easy CI gate.

Tags: different context, same folder

Sometimes you need a different context for the same folder, depending on what you're doing.

Say 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.

You author those as a tag:

mappings:
  ".":
    context_source: ./agents/root/AGENTS.md
  src/products:
    context_source: ./agents/products/AGENTS.md

tags:
  onboarding:
    mappings:
      ".":
        context_source: ./agents/root/onboarding/AGENTS.md
      src/products:
        context_source: ./agents/products/onboarding/AGENTS.md
  refactor:
    mappings:
      src/products:
        context_source: ./agents/products/refactor/AGENTS.md

Switch with a flag:

npx agent-contexts add your-org/your-contexts --tag onboarding
# or
npx agent-contexts update --tag refactor

Effective set is root ∪ tag (tag wins on conflicts), so you only write the differences. The lock records which tag each entry is on, so install reproduces it and update keeps you there.

A tiny end-to-end example

NestJS microservice. You want a Star-Wars-toned AGENTS.md for
src/products — because why not.

# contexts repo
mkdir -p agents/star-wars

cat > agents/products/AGENTS.md <<'EOF'
# Products Module

Follow the Repository pattern for data access.
Split Read and Write services (CQS-lite).
Use `class-validator` DTOs for every input.
EOF

cat > agents/star-wars/products.md <<'EOF'
# Products Module — The Armory of the Bounty Hunters

The domain heart, this is. Where artifacts of the holonet catalog,
manage you do.

- The Repository pattern, follow — data access through one gate
- Read and Write services, split — CQS-lite, the path of clarity
- DTOs with `class-validator`, use — `@nestjs/swagger` for the holomap
EOF

cat > contexts.yml <<'EOF'
version: "1"
mappings:
  src/products:
    context_source: ./agents/products/AGENTS.md
    description: Products module
tags:
  star-wars:
    mappings:
      src/products:
        context_source: ./agents/star-wars/products.md
        description: Products module — Yoda edition
EOF

In the consumer project:

npx agent-contexts add ../your-contexts --tag star-wars --force -y
# src/products/AGENTS.md is now a relative symlink into the cached file
# contexts.lock records tag=star-wars + the SHA of the file

npx agent-contexts status
# ✓ src/products/AGENTS.md  ok

# Later, switch back to the default tone
npx agent-contexts update                       # keeps the recorded tag
npx agent-contexts add ../your-contexts -y     # back to root mappings

That's the whole loop. Symlink in, versioned, switchable, reproducible.

A real (and less jokey) combo: code review in CI

Tags 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 files 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.

So you ship a ci-code-review tag alongside the default one:

mappings:
  ".":
    context_source: ./agents/root/AGENTS.md
  src/products:
    context_source: ./agents/products/AGENTS.md

tags:
  ci-code-review:
    mappings:
      ".":
        context_source: ./agents/root/ci-review.md
        description: Code-review checklist + tone for CI agents
      src/products:
        context_source: ./agents/products/ci-review.md
        description: Review-time conventions for the products module

Then the CI job does the swap before invoking the agent:

# restore the lock so the cache is hot
npx agent-contexts install

# swap every entry to the CR-specific tone
npx agent-contexts update --tag ci-code-review

# boot the reviewer — it picks up AGENTS.md / CLAUDE.md / GEMINI.md
# that all point at the ci-code-review content
npx your-cr-agent

Same project, same lock, completely different AGENTS.md content 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.

Commands cheat sheet

Command	What it does
`agent-contexts add <source>`	Fetch, select mappings, link, write lock.
`agent-contexts install`	Headless restore from `contexts.lock`. The `npm ci`.
`agent-contexts update`	Pull upstream, diff, re-pin.
`agent-contexts status`	Per-entry truth from disk. Exit 5 on problems.
`agent-contexts list`	Pretty table straight from the lock.
`agent-contexts reset`	Undo: remove links, restore `.bak` backups, delete lock + cache.

All commands take --json, -y, --dry-run, and --verbose. None of them need a TTY, so they slot into CI without fuss.

The full docs and source live at
github.com/gadz82/contexts.

Pros, cons, and an honest disclaimer

Pros

Deterministic. Same contexts.lock, same files, anywhere — laptop, CI, your colleague's machine.
Versioned. Pin to a SHA. Roll back by changing one line in the lock.
Composable. Tags mean you ship one context repo per project, not N forks of it.
Familiar. Anyone who's used npm, cargo, or pip already gets it.
Portable. Symlinks are relative — the project keeps working after you move or re-clone it.
Cross-tool. AGENTS.md, CLAUDE.md, GEMINI.md, whatever your agent of the week wants.
Scriptable. --json everywhere, deterministic exit codes, no TTY needed, for example you can wire it into a CI job that swaps to a ci-cr tag before booting the reviewer agent, then walk away.

Cons (fair's fair)

Local-path sources store an absolute path in the lock. Commit that lock and ship it to another machine and install won't find anything to fetch from. The reason is in the docs (TL;DR: only a git URL is the same string everywhere). Use git for shared/CI; locals are for solo experiments.
Windows without Developer Mode falls back to file copies. It still works, but updates need a re-run.
The schema is opinionated — POSIX paths, no .. escapes, lowercase hex hashes, that sort of thing. Read the spec once and you'll stop fighting it.
This is v0.x. I'm not promising the lockfile format won't change in a breaking way. Pin your agent-contexts version.

Wrapping up

If you've ever felt the pain of maintaining AGENTS.md files across a fleet of repos — or worse, watching them drift out of sync — give agent-contexts a try. The README is short, the install is one command, and the worst case is that you rm a .contexts/ folder and a contexts.lock.

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 and the binary should be contexts, I know, I know)? There's an issue tracker for that too.

And a proper thank-you to the Vercel Skills folks. The shape of
this whole thing is theirs; the AGENTS-shaped twist is mine.

That's all. Go ship something.

DEV Community: Francesco Marchesini