Getting started · Give a repo a brain

Give a repo a brain

A repo with a brain remembers what the last session learned. Two free ways to put one in: paste a prompt into whatever coding agent you already use, or run one command. Both stamp the same structure, both leave plain markdown you can read and delete, and neither needs an account.

Two doors, one kernel

The prompt

Paste it into a fresh session in Claude Code, Cursor, Codex, or anything that reads AGENTS.md, inside the repo you want to bootstrap. The agent reads your repo first and writes an operating manual describing what is actually there.

Use this when you want the manual to reflect your stack, your commands and your conventions, and you are happy to spend a model call on it.

The command

npx repoops init --kernel

Deterministic, no model in the loop, no key. It stamps the folder skeleton, a seed brain, the drift gates and the kernel blocks in CLAUDE.md, then stops.

Use this when you want the structure now and will fill in the repo-specific parts yourself, or when you are scripting it across several repos.

They are not alternatives to argue about. The prompt asks an agent to produce the same kernel the command stamps, plus the prose only a reader of your repo can write. Run the command first and paste the prompt afterwards if you want both.

Get the prompt

Print it from the CLI, so the copy you paste is pinned to the kernel version you have:

npx repoops init --prompt

Or read it in the repo at docs/distribution/repo-brain-bootstrap-prompt.md. It carries a version header naming the kernel it targets, which is how a copy that has been sitting in someone's notes for six months can be told apart from a current one.

From inside the app

If you already have RepoOps installed, Settings, then Birth a repo does the whole thing in one step: it creates the folder if it does not exist, runs git init, stamps the kernel, and registers the result as a tracked repo so the loop starts on it immediately.

It never overwrites what is already there.The stamp skips any file that exists. Pointing it at a folder that already has files and no git repo is refused outright, because stamping a brain on top of untracked work is the one case where a birth could cost you something.
It tells you which step it reached.Directory, git, kernel, tracked: each reports on its own. A repo that was stamped and then failed to register looks identical on disk to one that was never touched, so the steps are the only way to tell.

What a birth actually puts in your repo

  • A CLAUDE.md with the kernel blocks: how to work in this repo, read by every future session.
  • A .claude/brain/ seeded with the files a brain records into: decisions, errors, a file map, a glossary.
  • The drift gates, so the brain cannot quietly fall out of step with the code.
  • An AGENTS.md, for agents that read that instead.

All of it is plain markdown and small scripts. Nothing phones home, nothing needs a key, and deleting the folder removes it completely.

Read more

Last updated