Corbell builds a graph of your architecture before it writes a spec

The problem is decisions that leave no record

The README states the problem as a job description. You are a staff engineer or architect at a company where features touch five to ten repositories, and every quarter the team re-litigates the same architectural decisions: should we use Kafka or SQS, why do we have three different auth patterns, who owns the rate-limiting layer.

Then it says where those decisions actually live, and this is the sentence that defines the product. They live in Confluence pages nobody reads, Slack messages nobody can find, and the memories of engineers who have since left. When a new engineer joins, or when you return to a service you have not touched in six months, you start from scratch.

That is a knowledge retention problem, not a documentation problem. Writing better documentation does not fix it, because the gap is not that the decisions were unwritten, it is that they were written in a form nobody can retrieve at the moment of need, in a form that does not connect to the code.

Corbell's answer is to build a living knowledge graph of the architecture from the actual code in the repositories and the team's past design documents, so that a generated spec respects the established patterns instead of inventing new ones. The second half of the pitch is about handing work to an AI coding agent: when you push to Linear, each task carries the exact method signatures, call paths and cross-service impacts an agent needs to work autonomously.

Everything runs from your laptop against local repositories, with no servers and no cloud setup.

The pipeline, from graph to exported issues

The architecture section of the README draws the whole flow as a diagram, and it is the clearest description of what the tool does.

Your repos → [graph:build] → Service graph (SQLite)
Your docs  → [docs:scan]   → Design pattern extraction
              ↓
  [spec new --feature "Payment Retry" --prd-file prd.md]
                 →  Generates 3-4 PRD-driven code search queries (LLM or regex)
                 →  Auto-discovers relevant services via embedding similarity
                 →  Injects graph topology + real code snippets
                 →  Applies your team's established design patterns
                 →  Calls Claude / GPT-4o to write the full design doc
                 →  Displays token usage and estimated cost
                 →  specs/payment-retry.md ✓
              ↓
  [spec review]    → Checks claims against graph → .review.md
  [spec decompose] → Parallel task tracks YAML
  [export linear]  → Linear issues with full method/service context
  [export jira]    → Jira issues via REST API v3 (reads from workspace.yaml)

Three things in that flow are worth isolating.

The discovery step generates three or four code search queries from the PRD, using an LLM or a regular expression, and then finds the relevant services by embedding similarity. So the tool does not ask you to list the services a feature touches, it proposes them, which is what makes the feature useful across five to ten repositories.

The generation step injects graph topology and real code snippets, applies the team's established design patterns and then calls a model to write the document. The model is the last step, not the first, and the cost is reported: token usage and estimated cost are displayed after every LLM call, and there is a template mode with no LLM key that produces a structured skeleton with the graph context filled in.

The last two commands are where a spec becomes work. spec review checks the claims in the document against the graph and writes a .review.md, and spec decompose turns the spec into parallel task tracks in YAML, which the exports then push to Linear or to Jira as issues carrying the method and service context.

Installation with extras, and what pulls in the weights

The install is a pip command with a set of extras:

pip install corbell

# With LLM support (pick one):
pip install "corbell[anthropic]"    # Claude (recommended)
pip install "corbell[openai]"       # GPT-4o

# With exports:
pip install "corbell[notion,linear,jira]"

# Everything:
pip install "corbell[anthropic,openai,notion,linear,jira]"

The requirement is Python 3.11 or newer, and the packaging metadata in the repository agrees, with requires-python set to >=3.11 and a classifier for Python 3.11. The build backend is hatchling.

The extras map onto the feature boundaries. anthropic and openai are the two LLM providers, with Claude marked as the recommended one. notion, linear and jira are the export targets. There are also neo4j and chroma for the graph and vector stores, mcp for the MCP server integration, and cloud provider extras for aws, azure and gcp.

One extra deserves a note: treesitter, with grammars for Python, JavaScript, TypeScript, Go, Java, C#, Rust and more, described in the metadata as being for accurate multi-language method extraction. That is the difference between a call graph that is right and one that is approximately right, and it is why the language list in the workspace configuration is a real constraint rather than a cosmetic one.

The base dependencies already include sentence-transformers and transformers, so the embedding index is part of the default install and comes with torch and scikit-learn in its dependency tree.

The workspace file is the whole configuration

corbell init creates a workspace.yaml in your project root, and that file is where services, models and integrations are declared.

workspace:
  name: my-platform

services:
  - id: payments-service
    repo: ../payments-service
    language: python        # python | javascript | typescript | go | java | csharp | rust | ruby | php

  - id: auth-service
    repo: ../auth-service
    language: go

llm:
  provider: anthropic   # or: openai, ollama, aws, azure, gcp
  model: claude-sonnet-4-5-20250929
  api_key: ${ANTHROPIC_API_KEY}
  context_budget: 100000  # Token limit for prompt context

Three fields carry most of the weight. The services list maps an id to a repository path and a language, and the comment enumerates the supported languages. The llm block names the provider, the model and the context budget, which is a token limit for the prompt context, and the api_key is written as an environment variable reference. The integrations block follows the same pattern for jira, with a url, an email, an api token, a project key and an issue type of Task, Story or Bug, and for linear with an api key and a team id.

The environment variable references are a good sign. A configuration file that holds a Jira token or an LLM key in plain text is a file that ends up in version control by accident, and writing them as ${CORBELL_JIRA_API_TOKEN} and ${ANTHROPIC_API_KEY} makes that mistake harder to make.

The documentation also notes that the file is edited at corbell-data/workspace.yaml, which is a detail worth knowing if you script around the tool.

Three commands build the index

Building the graph, the embeddings and the pattern index is three commands:

corbell graph build --methods    # service + dependency graph + call graph, typed signatures, flows
corbell embeddings build         # code chunk index for semantic search
corbell docs scan && corbell docs learn   # extract patterns from existing RFCs/ADRs

The graph build with the methods flag produces the service and dependency graph, the call graph, typed signatures and flows, and the documentation says the service graph lives in SQLite, which is why the whole tool can run on a laptop with no server.

The embeddings build creates the code chunk index used for semantic search, which is what the auto-discovery step queries when it decides which services a feature touches. The docs scan and docs learn pair is the third input, extracting patterns from existing RFCs and ADRs, and it is the part that turns the tool from a code search tool into something that knows your conventions.

The three are separate because they are expensive in different ways and on different schedules. The graph changes when the code changes, the embeddings change when the code changes, and the pattern index changes when the design documents change, which is far more often than anyone expects.

The spec command itself is flexible about its input. A spec can be generated from a PRD file, with services auto-discovered and no service flag needed, with the full call graph and infrastructure context added by a --full-graph flag, from an inline PRD string, from existing design docs passed as a --design-doc argument, or with no PRD at all using the --existing flag to document a codebase as it is.

Constraints that future specs are forced to respect

The mechanism for encoding architectural rules is a fenced block of markdown embedded in a spec, delimited by CORBELL_CONSTRAINTS_START and CORBELL_CONSTRAINTS_END markers, and the spec command that produces such a document looks like this:

corbell spec new \
  --feature "Payment Retry with Exponential Backoff" \
  --prd-file docs/payment-retry-prd.md

Once a spec carries that block, all future specs respect it, and corbell spec review checks proposed designs against those constraints. The graph browser surfaces them in a persistent bar as well.

The design is interesting because it puts the rules where the work happens, rather than in a policy document that the model never sees. A constraint written in a wiki is a constraint the model does not know about. A constraint written inside the spec template is in the prompt.

The example constraints the README shows are the kind that are easy to state and easy to violate, a cloud provider restriction, a latency objective and an encryption policy, and the review step is where a generated design that breaks one of them gets caught before it reaches a human as a finished document.

Apache-2.0, heavy dependencies and a repository that stopped in May

The licence is Apache-2.0, stated in the pyproject as license = {text = "Apache-2.0"} and with the LICENSE file at the repository root, which is the permissive end of the spectrum and includes an explicit patent grant.

The dependency weight is the practical cost. The requirements file in the repository shows the full install, and it includes torch 2.2.2, transformers 4.57.6, sentence-transformers 5.2.3, scikit-learn, scipy and sympy, alongside the ordinary CLI stack of typer, pydantic, rich, questionary, gitpython and pyyaml. The embedding index is the reason, since a local embedding model is a large download and a slow first import.

The release history shows a project in its first months. v1.2.0 was published on 2026-05-23, 1.1.0 on 2026-04-25 and 1.0.3 on 2026-04-11, so the 1.x line arrived in April 2026 and reached 1.2 within a month. The repository is not archived, but the last push was on 2026-05-23, more than six months before the present date, so the project is not currently receiving updates.

For an evaluator, that is the fact to plan around. The tool is young, it is well documented for its age, and the version you install is close to the newest code, but there is no track record of it surviving a change in the model providers it wraps, which is the dependency most likely to break it.

Editorial conclusion

Corbell fits a backend team whose features cross several repositories and whose architecture decisions keep being relitigated, because the tool's output is a graph and a spec that both point at real code rather than at a general model of how such systems are usually built. It does not fit a team without a local checkout of its services, since everything runs against local repositories with no server to point at, and it does not fit a team unwilling to send code context to a model provider, since the spec writing step calls Claude or GPT-4o. Before adopting it, run graph build and docs scan on one repository and read the output before generating anything, and note that the last push was on 2026-05-23, so the project is not currently being updated.

Frequently asked questions

Official sources

1. Corbell-AI/Corbell on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases