The Problem

Backend teams working across 5-10 repositories lose architectural context. Decisions live in Confluence pages nobody reads and Slack threads nobody finds. When an engineer returns to a service after six months, they start from scratch. Corbell builds a living knowledge graph from actual code and past design docs, so new specs respect established patterns instead of inventing new ones.

What This Does

Corbell scans multiple repositories and builds a service-level graph stored in SQLite (corbell/core/graph/sqlite_store.py), detecting service types, infrastructure dependencies (AWS, GCP, Azure patterns in corbell/core/graph/providers/), and method-level call paths (corbell/core/graph/method_graph.py). It also extracts design patterns from existing docs (corbell/core/docs/learner.py) and generates PRD-driven design specs via LLM calls (corbell/core/spec/generator.py).

The CLI (corbell/cli/main.py) exposes commands for graph building, spec generation/review/decomposition, doc scanning, and exports to Linear/Jira/Notion. A local UI server (corbell/core/ui/server.py) visualizes the graph at localhost:7433. An MCP server (corbell/core/mcp/server.py) exposes graph queries to AI coding agents.

How It Is Wired

Execution starts at corbell/cli/main.py:42 (init), which calls init_workspace_yaml to create the workspace config. The graph build path flows through corbell/core/graph/builder.py → schema.py → sqlite_store.py, touching the filesystem via file iteration and writing to SQLite. The MCP server entry points (get_architecture_context, graph_query, list_services) reach 20-29 functions each and access the database via sqlite3.connect.

The highest-blast-radius modules are corbell/core/graph/schema.py (imported by 16 modules, 0 outgoing dependencies) and corbell/core/workspace.py (imported by 12). Changes to these ripple widely. SQLiteGraphStore is called from 29 places, get_methods_for_service from 28, and upsert_node from 27. The graph has no circular dependencies across its 74 modules and 133 import edges.

File responsibilities: schema.py owns node/edge operations, workspace.py resolves paths and API keys, sqlite_store.py handles persistence, llm_client.py wraps Anthropic/OpenAI calls, spec/generator.py orchestrates spec generation with LLM inference and file writes, method_graph.py parses TypeScript/Python method structures.

How To Use It

git clone https://github.com/moses-y/Corbell
cd Corbell
pip install -e ".[anthropic,openai,notion,linear,jira]"

corbell init
corbell spec new --prd "Add user authentication feature"
corbell ui serve

Configuration lives in workspace.yaml (created by corbell init), which stores repo paths, API keys, and export credentials. Python ≥ 3.11 required. The README documents these commands verbatim.

Real-World Use

A staff engineer at a fintech company with 7 microservices runs corbell graph build across all repos. When a new payment retry feature is requested, they run corbell spec new --prd "Payment retry with exponential backoff". Corbell auto-discovers relevant services via embedding similarity, injects the graph topology and real code snippets into the LLM prompt, and produces a spec that matches existing patterns. corbell spec decompose then generates parallel task tracks, and corbell export linear creates issues carrying exact method signatures and cross-service impacts.

Code Health & Issues

Static analysis found 43 issues (5 high, 37 medium, 1 low) across 7 kinds:

  • High - Deep nesting (16 instances) in sqlite_store.py, workspace.py, builder.py; max indentation depth 6. Fix with guard clauses.
  • High - Duplicated 6-line blocks (112 instances) across 15 files in corbell/cli/commands/. Extract shared helpers.
  • Medium - Broad exception handling (17 instances) in extractor.py, prd_processor.py, docs/learner.py.
  • Medium - Hub modules with high blast radius: schema.py, sqlite_store.py, workspace.py.
  • Medium - Oversized files: builder.py (665 lines), method_graph.py, spec/generator.py.
  • Medium - File opened without context manager in corbell/cli/commands/ui.py.
  • Low - 3 TODO/FIXME markers in spec/decomposer.py.

Security audit found: no lockfile (non-reproducible builds), wildcard CORS origin in ui/server.py, no least-privilege GITHUB_TOKEN permissions, no Dependabot, no dependency vulnerability scan, and no job timeouts in CI. Tests exist (24 files) with GitHub Actions CI, but no Dockerfile.

The Bottom Line

Corbell solves a real problem for teams with multi-repo architectures: it turns scattered code knowledge into a queryable graph and generates specs that respect established patterns. The codebase is well-structured with no circular dependencies, but the duplicated CLI logic and hub modules need refactoring before heavy customization. Production teams should address the security findings (lockfile, CORS, CI permissions) before deploying. Best suited for staff engineers who want AI-assisted spec generation grounded in actual code topology.