Give any repository a brain that every AI agent can read. Drop this folder into any repo. AI reads the instructions, analyzes your codebase, and builds a linked knowledge base with
AGENTS.mdas its single source of truth.
Formerly install-obsidian.
This is not a traditional installer. It is a set of Markdown instructions that AI agents (Claude Code, Codex, Copilot, Cursor, etc.) read to:
- Analyze your repo structure
- Design a documentation tree tailored to your codebase
- Create interconnected Markdown docs behind one hub,
AGENTS.md - Optimize link structure to remove duplicate/valueless links for cleaner graph + lower token use
The result: your repo gains a living knowledge base that both humans and AI can navigate.
AGENTS.mdis the single source of truth. It is the instruction file agents share — Codex, Cursor, GitHub Copilot, and many others read it directly.CLAUDE.mdis one line:@AGENTS.md. Claude Code expands the import at session start and loads the same hub. The import works on every platform; a symlink turns into a one-line text file on a default Windows checkout, and a sentence saying "read AGENTS.md" loads nothing by itself.- Stable rules live inline in
AGENTS.md. Rules kept in an agent-specific folder reach only that agent. - Links are standard relative Markdown links. They resolve for agents, on GitHub, in editors, and in Obsidian.
This project uses a hybrid approach:
- Core (repo-brain installer, non-negotiable): phase-based installer flow, stable rules, migration safety, and practical completion gates
- Inspired layer (llm-wiki style): smaller knowledge units, high-signal cross-links, living docs, and rationale-first writing
The inspired layer is an enhancement, not a replacement for the installer core.
Pick one of the three methods below. They are alternatives, not steps — each one installs the same thing, so you never run more than one.
Install repo-brain in this repo: read
https://raw.githubusercontent.com/borncode-app/repo-brain/main/AGENT-INSTALL.md
and follow it end to end. Ask me before you change anything.
If your agent supports skills and you have Node.js 22.20+, install the skill once. After that, "set up repo-brain in this repo" is enough — no URL to paste.
npx skills add borncode-app/repo-brain --skill repo-brain-installThen, in any repo:
Set up repo-brain in this repo.
The skill also works with -g for all projects, -a claude-code to skip the agent picker, and
npx skills update to keep it current.
git clone --depth 1 https://github.com/borncode-app/repo-brain.git /tmp/repo-brainRead /tmp/repo-brain/INSTALL.md and follow it end to end.
Whichever you pick, the agent analyzes your codebase, proposes a doc tree, and builds it after you approve. It
confirms two things as it goes: which repo it is installing into, and whether you want strict (default, full
structure) or adaptive (only the categories your repo justifies).
There is no package, no build step, and nothing added to your package.json. The outputs are listed under
What You Get.
| Situation | Use |
|---|---|
| Any agent, one time | Method 1 — the paste-in prompt |
| You will use repo-brain on several repos | Method 2 — install the skill once |
| Network is blocked, or you want the files locally | Method 3 — clone |
AGENT-INSTALL.md lists which agents fetch cleanly and which need Method 3.
If your CLAUDE.md is the hub and your docs use [[wiki-links]], run this instead:
Upgrade this repo to repo-brain v2: read
https://raw.githubusercontent.com/borncode-app/repo-brain/main/UPGRADE.md
and follow it end to end.
The skill handles this too: if you installed it, say "upgrade this repo to repo-brain v2".
The repo page is the whole installer: INSTALL.md is the flow, PHASES/01-analyze.md through PHASES/05-cleanup.md are the steps, TEMPLATES/hub-agents-md.md and its neighbors are the structures. Each phase documents its own output and its own gate.
This installer supports two output modes.
AGENTS.mdas the project hub — the single source of truth every agent reads first, with the stable rules inlineCLAUDE.mdholding one line,@AGENTS.md, so Claude Code loads the same hubdocs/_index.mdas the documentation navigation hub./.claude/rules/coding-behavior-rules.md— coding-behavior guidelines, linked fromAGENTS.md./.claude/skills/updating-docs/SKILL.md— generic doc-update skill (forces read-first, write-second discipline for future agents)decisions.mdfor persistent design decisions across sessions
Creates a full standardized documentation skeleton:
your-repo/
├── AGENTS.md # Project hub (every agent reads this first)
├── CLAUDE.md # One line: @AGENTS.md
├── docs/
│ ├── _index.md # Documentation navigation hub
│ ├── project/ # Project-level knowledge
│ ├── architecture/ # Structure and subsystem docs
│ ├── features/ # Feature workflow docs
│ ├── integrations/ # External dependency docs (if applicable)
│ ├── build/ # Build/packaging docs (if applicable)
│ ├── testing/ # Testing knowledge
│ └── reference/ # Stable reference docs
Creates only categories justified by repo analysis (example):
your-repo/
├── AGENTS.md
├── CLAUDE.md
├── docs/
│ ├── _index.md
│ ├── project/
│ ├── architecture/
│ └── features/
In both modes, files must contain real content. No empty placeholders.
- Flex, not static — AI analyzes YOUR repo, creates docs that match YOUR structure
- Hub-and-spoke — AGENTS.md is the front door, docs/ are the rooms
- Graph-friendly — standard relative links between docs work for agents, on GitHub, and in Obsidian graph view
- Minimal — Only creates docs where real knowledge exists, no empty placeholders
- Context-first — explain why decisions and workflows exist, not only where files are
| File | Purpose |
|---|---|
| AGENT-INSTALL.md | Remote install entry point: how an agent reaches the installer from a URL |
| skills/repo-brain-install/SKILL.md | The same install as an installable agent skill (npx skills add) |
| INSTALL.md | Step-by-step instructions for AI agents |
| UPGRADE.md | Upgrade flow for repos installed with v1 (install-obsidian) |
| PRINCIPLES.md | Design principles and decision framework |
| CONTRIBUTING.md | Contributor guidelines |
| CHANGELOG.md | Version tracking |
AGENTS.md |
Operational hub used by AI agents working on this repo |
CLAUDE.md |
One-line import of AGENTS.md for Claude Code |
decisions.md |
Persistent design decision log |
.claude/rules/ |
Coding-behavior rules shipped to target repos |
shipped/ |
Skills shipped to target repos (updating-docs) |
TEMPLATES/ |
Document structure templates, including migration mapping |
PHASES/ |
Sequential execution phases (Analyze → Design → Implement → Optimize Links → Cleanup) |
The knowledge base is plain Markdown with standard relative links, so it works wherever Markdown does.
- Start a new agent session — it loads
AGENTS.md(Claude Code throughCLAUDE.md) - When you add new features, AI will follow the Doc Workflow in AGENTS.md to create new docs automatically
Optional — browse the docs as a graph in Obsidian:
- Open your repo folder as a vault
- In Settings > Files & Links, turn off "Use [[Wikilinks]]" and set "New link format" to "Relative path to file", so links you create in Obsidian follow the same convention
- Open graph view to see how the docs connect (Obsidian does not index dot-folders, so links into
.claude/show as unresolved there)
- An AI agent capable of reading files and exploring a codebase
- Either network access for that agent (so it can fetch the instructions) or
git(for the shallow-clone fallback) - The target repo must have identifiable structure (any language, any framework)
- Obsidian (optional, for graph view)
MIT License