Corbell CLI
A CLI that builds a service graph from the code of several repositories and writes a design doc from a PRD that respects your team's decisions
- 628 ★ on the repository
- Last commit
- Apache-2.0
Extended access
Why this level
- Corbell reads the code of every repository in `workspace.yaml` and sends fragments of it to the chosen LLM provider
- Export to Linear, Jira and Notion creates tasks and pages in external services with tokens from environment variables or `workspace.yaml`
- The `corbell ui serve` command opens a local site on port 7433, and `corbell mcp serve` gives an MCP client access to the graph and code search
Install
- Works in
Manual install
pip install "corbell[anthropic]"Python 3.11 or newer is required. For GPT-4o use the openai extra instead of anthropic, and add notion, linear or jira for exports.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Corbell reads the code of every repository in `workspace.yaml` and sends fragments of it to the chosen LLM provider
- Export to Linear, Jira and Notion creates tasks and pages in external services with tokens from environment variables or `workspace.yaml`
- The `corbell ui serve` command opens a local site on port 7433, and `corbell mcp serve` gives an MCP client access to the graph and code search
This is third-party code. Review the repository files before installing.
What it does
A feature touches five to ten repositories, while the decisions on Kafka or SQS, authentication schemes and who owns rate limiting sit in Confluence and chats. Corbell assembles that picture from the code itself. The `corbell graph build --methods` command builds a graph of services, dependencies and calls in a local SQLite database: typed method signatures, execution flows, file pairs that often change together, data stores and queues. Python, JavaScript, TypeScript, Go, Java, C#, Rust, Ruby and PHP are supported. From a PRD document, `corbell spec new --feature "Payment Retry" --prd-file prd.md` writes a design doc. It first finds the relevant services by meaning: the code chunk index is built with the all-MiniLM-L6-v2 model, and you do not need to pass `--service`. It then mixes in the graph topology, real code snippets and the patterns your team extracted from past RFCs and ADRs with `corbell docs scan` and `corbell docs learn`. After every model call Corbell prints token usage and an estimated cost. Without a key, template mode creates a document skeleton with context from the graph. The document can then be checked against the graph and constraints with `corbell spec review`, approved, split into parallel task tracks with `corbell spec decompose` and exported to Linear, Jira or Notion. A local interface, `corbell ui serve`, shows the graph on port 7433, and `corbell mcp serve` gives Cursor and Claude Desktop the graph, code search and the service list.
Who it is for. For staff engineers and backend architects whose features run across many repositories and who need design docs consistent with decisions already made.
Good fit when
- A new PRD touches several services and you need a design doc draft with the right method and service names
- The team wants new documents to build on old RFCs and ADRs instead of inventing patterns again
- You need to document an existing codebase without a PRD: the `corbell spec new --existing` mode does that
- Architecture constraints such as "Azure only" or "p99 under 200 ms" must be checked in every new document
- An approved document has to be split into tasks and exported to Linear or Jira with method and service context
Not a fit when
- The project is a single small repository: the service graph and multi-repo search add nothing there
- You want code context for the agent right in the editor without design docs: a code indexer with MCP fits better
- Code cannot go to external models and there is no local model: only the no-LLM template mode remains
- The task is setting up agent rules and memory, and no design docs are needed
Example request
Build the graph over my repositories and write a design doc for the "Payment retry with exponential backoff" feature from docs/payment-retry-prd.mdLimitations
Python 3.11 or newer is required. Dependencies are heavy: sentence-transformers for the index, and the embedding model is downloaded separately. Install the extra for your LLM provider: `pip install "corbell[anthropic]"` or `corbell[openai]`. anthropic, openai, ollama, aws, azure and gcp are supported, and keys are set through environment variables such as ANTHROPIC_API_KEY.
Export to Linear needs CORBELL_LINEAR_API_KEY, and export to Jira takes the address, email and token from `workspace.yaml`. Whether the Anthropic and OpenAI providers are reachable from Russia was not checked for this card; local Ollama needs no key.
How to disable. Remove the package with `pip uninstall corbell`. In Cursor and Claude Desktop, delete the corbell block from the MCP configuration. The `corbell-data` working folder with the graph and the `workspace.yaml` config stays in your project and can be deleted by hand.
FAQ
How do I install Corbell?
Run `pip install corbell` and add an extra for model access: `pip install "corbell[anthropic]"` for Claude or `"corbell[openai]"` for GPT-4o. Exports have the notion, linear and jira extras. Python 3.11 or newer is required. After installing, run `corbell init` and a `workspace.yaml` appears in the project.
How do I connect Corbell to Cursor or Claude Desktop?
The `corbell mcp serve` command starts an MCP server over stdio. In `~/.cursor/mcp.json` or `claude_desktop_config.json` add a corbell block with command corbell and the arguments mcp serve. If the editor changes the working directory, set the CORBELL_WORKSPACE variable to the project path. Browser clients have an SSE mode: `--transport sse --port 8000`.
Which MCP tools does Corbell provide?
Four: graph_query looks up service dependencies, methods and call paths, get_architecture_context finds the services relevant to a feature description, code_search searches the code index by meaning, and list_services lists the graph's services.
Can Corbell run without an API key?
Yes, in two ways. The `--no-llm` flag and template mode create a document skeleton with context from the graph. And the ollama provider works with a local model such as llama3 or mistral and needs no key.
How does Corbell pick services for a document?
It forms three or four search queries from the PRD, encodes them with the all-MiniLM-L6-v2 model and looks for similar code chunks in the index. Services are ranked by how many of their chunks land near the top, and services tagged infrastructure, such as AWS CDK repositories, are always added. You can preview the choice without generating anything with `corbell spec context "..."`.
Discussion
No questions or reviews yet.
Related
CLI toolsA Claude Code plugin that takes a feature from PRD to merge: sub-agents work in waves on separate branches, each PR gets a review
A CLI that builds a dependency graph from code with no AI model and serves it to agents over MCP: what an edit touches, whether layers hold
Eleven skills take an agent from an idea to verified code through a PRD and RFCs kept as files in the repository
codesight maps a project in one run: routes, DB models, dependencies, env vars. It gives the map to an agent as files or through an MCP server
A skill that draws every pull request as an architecture and data-flow diagram right in the PR description, to speed up review
The /graphify skill builds a knowledge graph of a project's code, docs and PDFs so the agent queries the graph instead of grepping
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Corbell (this entry) | no | 628 | ||
| GitNexus | no | not required | 48,123 | indexes a repository into a knowledge graph and answers the agent over MCP, with no document writing |
| CCPM | no | 8,423 | a skill for development through PRDs, epics and tasks synced with GitHub, without a code graph |
README in short
The README opens with the problem: architecture decisions get lost in Confluence pages and chats, and a new engineer starts from scratch. It then shows the flow from graph and document scanning to the design doc, review, decomposition and export. After that come installation, a two-minute quick start and a detailed guide: workspace configuration, graph building, document generation, constraints, review and export, the graph interface, the command reference, MCP, automatic service selection and LLM providers.