RPG-ZeroRepo: a Repository Planning Graph as a control layer for coding agents

The problem RPG-ZeroRepo targets: context that outlives one chat turn

Long coding tasks break in a specific way. A requirement gets stated, the agent makes local edits, and twenty steps later the original architecture decision is gone from the working context. File search returns the file that mentions a name, not the file that depends on it. The README frames this as coding agents that "lose repository-level context across long tasks", with requirements drifting and edits missing hidden dependencies.

RPG-ZeroRepo's answer is to stop treating the plan as chat history. It represents a repository as a Repository Planning Graph, a structure connecting requirements, features, architecture and files, and then uses that graph as the thing the agent reads and writes during a task. The README states the design intent plainly: good planning for coding agents should be grounded, executable, verifiable and reusable, and the plan should be a graph rather than a transient chat artifact.

The audience is narrow and identifiable. This is for engineers running Claude Code or GitHub Copilot on multi-file work, and for researchers who want to reproduce or extend the underlying papers. It is not a linter, a code generator you point at a spec and walk away from, or a replacement for your build system.

Two pipelines and one control layer: how the pieces fit

The repository holds three distinct things, and conflating them is the main source of confusion.

ZeroRepo is the forward pipeline, described as requirements to RPG to repository. You start from a natural-language requirement, the pipeline builds a planning graph, and code is generated from it. The pipeline documentation is in docs/zerorepo-pipeline.md, which the README says covers Phase 1/2/3, checkpoint files and configuration. The presence of checkpoints matters: a multi-phase generation run is resumable rather than a single monolithic call.

RPG-Encoder is the reverse pipeline, repository to RPG. It takes an existing codebase and produces the graph. The code lives in zerorepo/rpg_encoder/, and the README points to a module-level README there. This is the half that makes the tool usable on code you already have rather than only on greenfield projects.

CoderMind sits on top and is the part most readers will actually install. It exposes the RPG workspace through three interfaces, per the README: CLI setup via `cmind init`, slash commands inside the coding agent (`/cmind.feature_spec`, `/cmind.code_gen`, `/cmind.encode`, `/cmind.rpg_edit`), and MCP graph tools the agent can call during coding (`search_rpg`, `explore_rpg`, `get_node_detail`). The MCP layer is the mechanism that turns the graph from a file on disk into something the agent queries mid-task.

RepoCraft is the fourth piece, a benchmark in repocraft/ with its own README. It exists to measure the pipeline, not to be used in production.

Installing cmind-cli and running a first graph-aware edit

CoderMind installs as a tool from a subdirectory of the repository. The README gives this exact command, which pulls the package from the git URL rather than PyPI:

uv tool install cmind-cli \
  --from "git+https://github.com/microsoft/RPG-ZeroRepo.git#subdirectory=CoderMind"
cmind check

The `cmind check` call is a readiness probe. Run it before anything else and treat a failure as an environment problem rather than a project problem, since the Python requirement is 3.11+ and the dependency list is long.

For an existing repository, you initialise a workspace and encode the codebase into a graph:

cd your-existing-repo
cmind init . --encode

After that, the workflow moves inside the coding agent. The README shows the edit command as a slash command rather than a shell command:

# In Claude Code or GitHub Copilot:
# /cmind.rpg_edit  "Add rate limiting to all API endpoints"

The expected behaviour is that the agent locates the affected RPG nodes, plans the change against cross-file dependencies, and updates both the code and the graph. What you should see is a diff that touches more than the one file whose name matches "rate limiting".

For a new project the sequence is different. You create the workspace, then drive the plan through the feature commands in order:

cmind init my-project
cd my-project
# In Claude Code or GitHub Copilot:
# /cmind.feature_spec  Build a CLI tool for managing Docker containers
# /cmind.feature_build → /cmind.feature_refactor → ... → /cmind.code_gen

The arrow chain in the README is literal: the feature stages run in sequence and each one refines the graph before generation starts. The README does not document rollback for a stage that produces a bad plan, so keep the workspace under version control if you intend to iterate.

What the dependency list tells you about the real cost

requirements.txt is the least glamorous file in the repository and the most informative. The ZeroRepo side pulls torch>=2.9.1, sentence-transformers>=5.2.0, transformers>=4.57.3, faiss-cpu>=1.7.0 and scikit-learn. That is a vector-search and embedding stack, which fits the claim that graph nodes are searchable and reusable across tasks. It also means a multi-gigabyte install and a machine that is comfortable running local embedding models.

The pins are aggressive in both directions. `tree-sitter==0.21.3` and `tree-sitter-languages==1.10.2` are exact pins, so any other project in the same environment that wants a newer tree-sitter will conflict. The llama-index family is pinned across roughly twenty packages at the 0.11.x line, including llama-index-core==0.11.22 and llama-index-legacy==0.9.48.post4. Mixing this requirements file into an environment that already has a different llama-index version is not going to resolve cleanly.

There is also a hard dependency on `mcp==1.12.2`, which is the protocol version the graph tools are built against. If your agent's MCP client expects a different protocol revision, that pin is where you will find out.

The practical conclusion is to isolate this. A dedicated virtual environment or container is the intended shape, and the repository ships a dockerfile/ directory for that reason. The README does not document a supported Python-version matrix beyond the 3.11+ badge.

Where the graph approach gets in the way

The graph is only as good as its encoding step, and the encoding step is the failure mode. If `cmind init . --encode` produces a graph that misplaces a subsystem or misses a dependency edge, every downstream edit is planned against a wrong map, and the agent will sound confident while doing it. The README describes the benefit of graph-aware edits but does not describe how to audit an encoded graph for correctness. That is a real gap, and it is the first thing a cautious team should probe.

Second, this is the wrong tool for small work. A single-file bug fix does not need a planning graph, and running the encode step to get one is pure overhead. The README's own framing is repository-level tasks; below that threshold, plain file editing wins.

Third, the external-model dependency is structural, not incidental. The core LLM clients are openai, anthropic and google-genai. Graph construction and code generation go to a hosted provider. If your code cannot leave your network, this pipeline does not fit as shipped, regardless of how good the graph is.

Fourth, there is no homepage and no published CLI reference in the top-level README beyond links into CoderMind/docs/. The documentation lives in the repository, which is normal for research code but means you are reading source when the docs run out.

How this differs from retrieval-only repository context

The obvious comparison is a retrieval-augmented setup: embed the repository, store it in a vector index, and let the agent fetch relevant chunks. The requirements file shows RPG-ZeroRepo uses embeddings and faiss-cpu too, so the difference is not the absence of retrieval.

The difference is what gets retrieved. A retrieval-only setup returns text chunks ranked by similarity to the current query, with no persistent structure between them and no notion of which chunk depends on which. RPG-ZeroRepo builds an explicit graph of requirements, features, architecture and files, then exposes traversal over that graph through `search_rpg`, `explore_rpg` and `get_node_detail`. The agent can ask what a node depends on rather than hoping the dependency appears in a top-k chunk.

The second difference is persistence. A retrieval index is rebuilt or re-embedded as the code changes; the graph is meant to be a durable workspace that survives across tasks and is updated alongside the code during a `/cmind.rpg_edit` run. Whether that durability holds up over months of commits is exactly what the README does not tell you, and what a trial period should measure.

Maintenance, licensing and what to watch on upgrade

The repository is not archived, and the last push was on 2026-08-24. The most recent release listed is cmind-v0.1.10 (CoderMind Templates) from 2026-07-22, following cmind-v0.1.9 on 2026-06-29 and cmind-v0.1.8 on 2026-06-26. The 0.1.x version numbers and the three-week gap between 0.1.9 and 0.1.10 tell you the CLI surface is still moving, and the release name mentions templates specifically, which suggests the template format is among the things changing.

That has a concrete upgrade consequence. Because the install command pulls from a git URL rather than a pinned PyPI version, `uv tool install` with the same command will fetch whatever is on the branch at that moment. If you need reproducibility, pin the git ref yourself rather than relying on the default. The README does not document a supported upgrade path between cmind versions, so treat a workspace created by 0.1.8 as something to re-check after upgrading.

The licence is MIT, stated in the README badge and the LICENSE file at the repository root. MIT is permissive and imposes no copyleft obligation on your own code. Two caveats are worth naming without giving legal advice: the repository bundles research code alongside the CLI, so if you vendor parts of it, keep the licence text with what you copy; and the pipeline calls hosted model providers under your own credentials, so your provider's terms, not the MIT licence, govern what happens to the code you send. The README does not document data handling for those calls.

Editorial conclusion

Adopt it if you already run Claude Code or GitHub Copilot on repository-scale work and want planning state that survives a long session, and if you can absorb a Python 3.11+ stack with torch, faiss-cpu and tree-sitter pinned to 0.21.3. Skip it if you only need single-file edits, or if you cannot send repository structure to an external model provider. Before committing, verify that `cmind check` reports a working workspace in your environment, that the RPG files land in a directory you are willing to commit or gitignore, and that your chosen agent actually exposes the MCP tools listed in CoderMind/docs/commands.md.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. microsoft/RPG-ZeroRepo on GitHub
4. README
5. Releases