One rig for all your repos — an AI-ready, multi-repo dev workspace template.

English · 简体中文 · Español · हिन्दी · Português · 日本語 · Français · 한국어 · සිංහල

---

What is devrig?

devrig is a meta-repo: one folder that contains every repo of your project plus the AI tooling used to develop across them. This repo versions only the tooling — your project repos are cloned side-by-side by setup.sh and stay untracked. Everything is configured from a single devrig.toml file.

	What you get
🧠	AI workflow skills — /start-task, /plan-task, /verify-change, /raise-pr, /code-review, /write-doc, /capture-learning, /check-knowledge-consistency, /create-ticket (agent-agnostic in .agents/skills/, symlinked for Claude Code, opencode configured too)
🔍	semble — semantic code search agents use via MCP instead of grep-and-read
🕸️	graphify — a knowledge graph per repo that agents query instead of grepping, kept fresh by git hooks
⚡	rtk — token-optimizing command proxy for Claude Code
🎫	Issue tracker MCP — Linear, Jira, or bring your own; picked interactively by setup.sh
🛡️	Protected-branch git hooks — no accidental commits/pushes to your default branch, in any repo
📚	knowledge/ — a markdown knowledge base skeleton (architecture, ADRs, design docs, runbooks) the AI tooling indexes and writes into
🖥️	Generated VS Code multi-root workspace — every repo in one window

Quick start

The fastest way — one command, no cloning:

npx create-devrig my-project

create-devrig fetches this template (no git history), initializes a fresh git repo in my-project/, and launches the interactive setup wizard immediately — same wizard described below, just without the separate clone step.

Prefer GitHub's UI, or want the repo created under your org from the start?

1. Click Use this template to create your-org/your-project-workspace.

2. Clone it and run:

   ./setup.sh

   The first run notices devrig.toml still has the shipped example values and walks you through configuring it interactively: project name, a one-line description, GitHub org, the repos to clone (paste several at once, space- or comma-separated), your issue tracker (Linear, Jira, or other — pick one from a menu), ticket prefix, default branch, and feature toggles. It then writes devrig.toml for you, removes devrig's own template files, and generates a README.md for your project in their place. Prefer to hand-edit instead? Fill in devrig.toml yourself before running the script and it'll skip the prompts.

3. Run claude from this folder and start working.

Either way, inside Claude Code: run /mcp and authenticate the tracker server that was configured (linear or atlassian; one-time OAuth — semble needs no auth), and restart Claude Code once so the rtk hook takes effect. If graphify is enabled, build each repo's graph once with graphify update . from that repo's root — the git hooks keep it fresh from then on.

🤖 Kickstart with your AI agent

Already have your repos?

Just created a workspace from this template? Paste this into your AI coding agent (Claude Code, Cursor, opencode, …) and let it finish the setup with you:

I just created a workspace from the devrig template
(https://github.com/lakpriya1s/devrig). Help me set it up:

1. Read README.md and AGENTS.md to understand the workspace.
2. Run ./setup.sh with me, relaying its interactive prompts (project name,
   description, GitHub org, repos, issue tracker, ticket prefix, default
   branch, feature toggles) so I can answer them — then help me fix anything
   it flags. It personalizes the workspace: devrig's own template files are
   removed and a README for my project is generated.
3. Work through the generated README's "Customize this workspace" checklist
   with me — fill AGENTS.md's Systems table and the per-repo skill references.
4. Commit the personalization on a task branch and open a PR.

Starting a brand-new project?

No repos yet, just an idea? Swap in your project description where marked and paste this instead — the agent takes you from idea to a running workspace, new repos included:

I want to start a brand-new project using the devrig template
(https://github.com/lakpriya1s/devrig). Here's what I'm building:

[describe your project — what it does, who it's for, and any stack or
platform preferences you already have]

Help me go from this description to a working workspace:

1. Run `npx create-devrig <name>` to scaffold the workspace (pick a short
   project name from my description if I haven't given one).
2. Propose a repo breakdown and stack for each piece based on what I'm
   building — confirm with me before creating anything.
3. Create each repo on GitHub under my org (ask which) and scaffold it
   with its framework's starter command, committing the initial code.
4. Fill in devrig.toml (project name, description, org, the repos we just
   created, issue tracker, ticket prefix, default branch — make sure it
   matches what the new repos actually use) and run ./setup.sh.
5. Fill in AGENTS.md's Systems table and the generated README's "What's
   inside" table since you already know each stack.

What setup.sh does

setup.sh is idempotent — re-run it anytime to update every repo and tool. It:

0. First run only: if devrig.toml still has the shipped example values, prompts for all of the values below interactively and writes devrig.toml.
1. Personalizes the workspace: removes devrig's own template files (docs/, assets/, CITATION.cff, CONTRIBUTING.md, LICENSE) and generates a README.md for your project from devrig.toml. Skipped inside the devrig repo itself, and a README you've edited is never overwritten.
2. Checks prerequisites (git, gh authenticated; installs uv if semble or graphify is enabled).
3. Clones every repo in repos side-by-side (or fast-forwards clean default-branch checkouts), and excludes them from this repo's git status via .git/info/exclude.
4. Installs the protected-branch git hooks into this repo and every cloned repo.
5. Converges .mcp.json / opencode.json to your devrig.toml toggles — adding the linear or atlassian (Jira) server per issue_tracker, or neither if you picked "other" — while preserving any MCP servers you added by hand, and generates .claude/settings.local.json.
6. Installs semble and warms a search index per repo.
7. Installs rtk and registers its Claude Code hook.
8. Installs graphify: its skill into .agents/skills/ (symlinked for Claude Code), the PreToolUse guards that point agents at the graph before they grep, and the git hooks that rebuild a repo's graph after commits, checkouts and merges.
9. Generates <project>.code-workspace for VS Code (skipped if you already have one, so it's safe to customize and commit).

Customization checklist

setup.sh handles the mechanical personalization itself (writes devrig.toml, removes devrig's template files, generates your project README). What's left is the knowledge only you have — the generated README's "Customize this workspace" section carries this same checklist into your workspace:

• AGENTS.md — fill the Systems table (one row per repo: what it is, stack, what it depends on), the Commands table, and the Testing section. This is the source of truth every skill reads. Keep the generated README's "What's inside" table in sync.
• POLICY.md — adjust the Definition of Done and ADR triggers to match your team's actual bar (e.g. add a security-review requirement).
• .ai/systems.yaml, .ai/commands.yaml, .ai/ownership.yaml — replace the example entries with your real systems/commands/owners (mirrors AGENTS.md's tables; node scripts/validate-ai-config.mjs checks the shape).
• .ai/policies.yaml, .ai/risk-levels.yaml — adjust protected paths, forbidden/approval-required actions, and risk examples for your project.
• .agents/skills/code-review/references/ and .agents/skills/write-doc/references/ — one reference file per repo (copy _example-repo.md). The skills work without them but get much sharper with them.
• If issue_tracker is linear: verify .agents/skills/create-ticket/SKILL.md's "Conventions" table against your Linear workspace (teams, projects, labels). If it's jira or other: adapt /start-task, /raise-pr, and /create-ticket's mcp__linear__* calls to your tracker's MCP tool names (each skill flags this at the top).
• Delete or adjust anything a toggle disabled (e.g. remove the semble notes from CLAUDE.md if you don't use it).

To change config values later — switch tracker, add a repo — edit devrig.toml directly and re-run ./setup.sh.

Layout

Path	What it is
devrig.toml	Your project config — the one file every tool reads
setup.sh	Idempotent bootstrap/update script
AGENTS.md	Agent-agnostic source of truth (systems, commands, branch rules, retrieval policy)
POLICY.md	Definition of Done, ADR requirement, risk/data/role policy, verification/confidence reporting
.ai/	Machine-readable mirror of the above (systems.yaml, commands.yaml, ownership.yaml, policies.yaml, risk-levels.yaml), their JSON Schemas in .ai/schemas/, and per-task context bundles in .ai/context/ (written by /start-task)
.github/workflows/	CI: validates .ai/*.yaml against its schemas, and validates knowledge/ (frontmatter, links, ADR ids, index freshness, protected-path ADR requirement)
CLAUDE.md	Claude Code specifics; imports AGENTS.md
.agents/skills/	Canonical workflow skills (agent-agnostic)
.claude/	Claude Code settings, agents, skill symlinks
.opencode/	opencode agents and plugin config
.mcp.json / opencode.json	MCP servers (issue tracker, semble)
git-hooks/	Shared hooks for every repo (core.hooksPath): protected-branch pre-commit / pre-push, plus the graphify graph rebuilds
knowledge/	Markdown knowledge base (architecture, decisions, design, runbooks, product, releases, handoffs, generated) — see knowledge/index.md
evals/	Questions with known-good answers, for measuring retrieval accuracy/hallucination rate over time — see evals/README.md
scripts/	Workspace maintenance scripts — build-knowledge-index.mjs, validate-knowledge.mjs, validate-ai-config.mjs, detect-doc-drift.mjs, check-adr-requirement.mjs, generate-architecture-views.mjs
<repo>/ (untracked)	Your project repos, cloned by setup.sh

Adding a skill

See .agents/skills/_template/README.md. Short version: create .agents/skills/<name>/SKILL.md, symlink it into .claude/skills/, and list it in CLAUDE.md.

Knowledge graph

With the graphify toggle on, every repo gets its own <repo>/graphify-out/ — a queryable graph of the code (hubs, communities, cross-file relationships) plus a plain-language GRAPH_REPORT.md and an interactive graph.html. Agents hit it instead of grep-and-read:

cd <repo>
graphify update .                                # build/refresh (AST-only, no API key)
graphify query "how does authentication work"    # scoped subgraph, not a grep dump
graphify path "LoginForm" "SessionStore"         # how two things connect
graphify explain "PaymentService"                # one node and its neighbours

setup.sh installs the CLI, drops the skill in .agents/skills/graphify/, registers the PreToolUse guards that nudge agents to the graph before they search, and installs the rebuild hooks — graphify hook install covers post-commit and post-checkout, and devrig adds git-hooks/post-merge so a git pull refreshes the graph too. Graphs, the installed skill and the generated hooks are all gitignored: they're regenerated from the CLI on every ./setup.sh, so nothing stale gets committed.

Knowledge base

New design docs, architecture notes, ADRs, and runbooks go in knowledge/ as markdown via PR — semble indexes it, so agents find design context the same way they find code. When it outgrows this repo, push it as a separate <project>-knowledge repo, add that to repos in devrig.toml, delete the folder here, and update the pointer in AGENTS.md.

Troubleshooting

• semble or uv not found after setup — open a new shell (PATH was updated) and re-run ./setup.sh.
• Tracker tools missing in Claude — run /mcp and complete the OAuth flow for the linear or atlassian server.
• rtk not kicking in — restart Claude Code; verify with rtk gain that commands are being proxied.
• graphify query says there's no graph — build it once per repo with graphify update . from that repo's root; the hooks only refresh a graph that already exists.
• Graph rebuilds aren't firing on commit — run graphify hook status in the repo and check ~/.cache/graphify-rebuild.log. GRAPHIFY_SKIP_HOOK=1 silences them for one command.
• A repo won't update — setup.sh never touches a repo that has local changes or is on a task branch; it only fast-forwards clean default-branch checkouts.
• setup.sh isn't prompting me, it just fails with "edit devrig.toml first" — it only prompts when attached to an interactive terminal; running it from a script or CI falls back to requiring devrig.toml to already be filled in.
• Picked Jira or "other" — the atlassian MCP server (Jira) is wired up automatically, but /start-task, /raise-pr, and /create-ticket still call Linear's MCP tool names — setup.sh will warn you about this at the end of every run until you adapt those skills.

Contributing

devrig gets better with every team that rigs it up. Bug reports, new generic skills, better docs, and README translations are all very welcome — see CONTRIBUTING.md. If devrig saved your team setup time, a ⭐ helps others find it.

License & citation

Released under the MIT License.

If you use devrig in your work or writing, a citation is appreciated — GitHub's "Cite this repository" button (powered by CITATION.cff) has the details, or:

Senevirathna, L. (2026). devrig: a multi-repo AI dev workspace template. https://github.com/lakpriya1s/devrig

_{Built from a production multi-repo workspace · devrig}