Most of us don't work in a single repository. While working on the same task, I might move between an infrastructure repo, an API backend, a web frontend, and an ML modelling project, each with its own setup, its own deploy flow, and its own quirks. A coding agent like Claude is good inside any one of them, but it only ever sees the repository it's currently in.

The obvious answer is to point the agent at each repo's README, and often that's enough. But not always. The README might be out of date. It might be a shared repo with many contributors, where your personal setup notes don't belong and you'd rather not open a pull request just to record them. And you often have preferences the README doesn't capture: I run our backend in a Docker dev container while a colleague runs everything with local installs, and I want the agent to assume mine.

So I end up re-explaining the same handful of facts at the start of every session: this repo is dormant, that one deploys on a push to main, this other one I set up differently from the docs. The knowledge lives in my head, and it dies when the session ends.

This post is a quick how-to for how I've solved this problem for myself.

The idea: a local index of your repos

I keep and maintain a small "context" repository, and I run all my agent sessions from it. Inside, I keep an index of the repositories I've cloned locally, one short entry per repo. I open the agent in this context repo, it reads the index, and from there it can work across the other repos by path, already knowing what each one is.

Each entry is a durable pointer, not a copy of the README. It says what the repo is, where it lives, and where the canonical docs are, and then it adds the things that only matter to me: my local setup, my preferences, and anything in the README I know to be stale.

Here is a representative entry:

# api-backend

Last verified: 2026-06-16

## What it is

The REST API behind our main product. Shared repo, many contributors;
see its own README for the canonical setup.

**GitHub:** git@github.com:acme/api-backend.git (private)
**Local:** `~/github_repos/acme/api-backend/`

## My setup notes

- Run it in the Docker dev container, not local installs. The README
  documents both; the container is what I actually use.
- The README's database-seed step is stale, so the command to use is
  `make seed-dev`.

That's the whole thing. Short, factual, and quick to correct when something changes. When I ask the agent to do something that touches a repo, it reads that entry first instead of guessing or leaning on a README I know is wrong.

A folder of small entries also tends to beat one giant document, because the agent loads only what's relevant to the task at hand rather than wading through everything I've ever written.

Option 1: Set it up by hand in a couple of minutes

You don't need anything fancy to try this. Three steps.

1. Make a context repo. Create a small repo you'll run your agent sessions from: a notes repo, your dotfiles, or a fresh empty one. Add a repos/ folder inside it.

2. Add a template.md so every entry has the same shape:

# <repo-name>

Last verified: YYYY-MM-DD

## What it is

<1-2 sentences, plus a pointer to the repo's own README for canonical docs.>

**GitHub:** <remote URL> (public/private; deploy URL or notes)
**Local:** `~/path/to/<repo>/`

## My setup notes

- <how I run it locally, my preferences, gotchas, anything stale in the README>

3. Add one routing rule. In your CLAUDE.md (or whichever instructions file your agent reads), add a line:

When working in or referencing another repository, read its repos/<name>.md first, and prefer my notes there over the repo's README where they differ. Don't invent paths, URLs, or deploy steps; if something's unknown, leave a TODO: marker.

That's it. Add an entry for each repo as you touch it, rather than all at once, and the index fills in naturally.

Option 2: Let the agent set it up for you

If you'd rather not do it by hand, paste this into your agent inside the repo you want to use as your context home:

Set up a local index of the repositories I work across, in this repo.

1. Create a `repos/` folder and a `repos/template.md` with these
   sections: a title, a "Last verified" date, "What it is" (1-2
   sentences plus a pointer to the repo's own README), the GitHub
   remote (visibility and any deploy URL), the local path, and a
   "My setup notes" list for how I run it locally, my preferences,
   and anything stale in the README.

2. Add a rule to CLAUDE.md: when working in or referencing another
   repo, read its `repos/<name>.md` first and prefer my notes there
   over the README where they differ. Never invent paths, URLs, or
   deploy steps - leave a TODO marker instead.

3. Ask me which repositories I've cloned locally, then create one
   filled-in entry per repo from the template. Don't invent details;
   leave TODO markers for anything you can't verify.

The prompt just saves you the typing. The setup is small enough that it's worth reading what it produces, so you know exactly what your agent is now relying on.

Why this works for me, and when you'd want more

For me it earns its keep in three ways. It survives sessions, so the agent doesn't start from zero each time. It scales by relevance, loading only the entry for the repo in play. And it stays honest, because a short, dated, hand-checked entry is easier to keep true than a sprawling document, and because it holds the personal setup a shared README never will.

It's also deliberately small. If you find yourself wanting reusable procedures, somewhere to track ideas, or richer conventions, that's a sign you're ready for more structure than a single folder gives you. But you don't need any of that to get most of the value, and starting small is the point.

This index is one slice of a broader approach I take to working with coding agents day to day. I'll write that up some other time. In the meantime, you can give this a try today.