repo-architect — Claude Code subagent: repo structure, how to install
repo-architect maps how your repositories are laid out and proposes a cleaner shape: a shared project template plus file sync across repos through GitHub MCP.
no license ★ 850 updated 2026-10-26
.claude/agents/repo-architect.mdWhat repo-architect does
The agent inspects repository layout and comes back with a restructuring plan: where packages belong, which files should move into a shared template, what to keep in sync between related repos. It spreads the work across a claude-flow swarm with analyst, architect, optimizer and coordinator roles.
Hooks ride on npx ruv-swarm. One runs a structure pass before the task starts, one checks edits afterwards, one assembles recommendations at the end, and a notification hook fires separately. So ruv-swarm has to resolve through npx on the machine running Claude.
On the tool side it has file work (Bash, Read, Write, Edit, Glob, WebFetch, Task) plus GitHub MCP calls for creating, forking and searching repositories and pushing files. Those calls only land when the github and claude-flow MCP servers are connected, otherwise it can touch local files and nothing more.
What it helps with
- align the layout of several repositories to one template
- place packages sensibly before they pile up in the root
- keep CI configs identical across related repos
- spin up a new repository from a ready-made template
- get a written list of structural problems
Example prompts for the agent
- Walk the structure of this repo and tell me what to move so new packages stop landing in the root.
- Build a project template with
.claude/config.jsonandCLAUDE.md, then push it to a fresh repo usingmcp__github__create_repository. - Compare the layout of
claude-code-flowandruv-swarmand sync the files they share.
How to install repo-architect
Manually: put the files in place
.claude/agents/repo-architect.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/repo-architect.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.cursor/agents/repo-architect.mdCursor also reads .claude/agents/
Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean
Questions about repo-architect
How do I install repo-architect in Claude Code?
Put the agent file at .claude/agents/repo-architect.md. That is the whole install; the subagent is then available in your session.
What does repo-architect do?
It reads repository structure, manages project templates and keeps shared files in sync across related repos. A claude-flow swarm splits the job between roles.
Which MCP servers does it need?
github for repository operations and claude-flow for the swarm calls. The hooks also shell out to npx ruv-swarm, so that package must be reachable.