Skip to content
Back to search

Corbell

AI-powered spec generation and review using multi-repo code graph intelligence for backend teams that ship to production.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/corbell-ai--corbell/badge.svg)](/listings/corbell-ai--corbell)

HTML

<a href="/listings/corbell-ai--corbell"><img src="/api/listings/corbell-ai--corbell/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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]"

**Requirements**: Python ≥ 3.11

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 443 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <img src="assets/logo.png" width="300" alt="Corbell Logo" />
  3. <h1>Corbell</h1>
  4. <p><strong>Multi-repo architecture graph, AI-powered spec generation, and architecture review — for backend teams that ship to production.</strong></p>
  5. <p>
  6. <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License"/></a>
  7. <a href="CONTRIBUTING.md"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"/></a>
  8. <a href="https://agentseal.org/mcp/corbell"><img src="https://agentseal.org/api/v1/mcp/corbell/badge" alt="AgentSeal MCP"/></a>
  9. </p>
  10. </div>
  11. ---
  12. ## What problem does this solve?
  13. You're a staff engineer or architect at a company where features touch 5–10 repositories.<br/>
  14. Every quarter your 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?"
  15. The decisions live in Confluence pages nobody reads, Slack messages nobody can find, and the memories of engineers who've since left.
  16. When a new engineer joins—or even when you return to a service you haven't touched in 6 months—you're starting from scratch.
  17. **Corbell gives your team a living knowledge graph of your architecture** — built from the actual code in your repos and your team's past design docs. When you need a new spec, Corbell generates one that respects your established patterns instead of inventing new ones. When you push to Linear, each task carries the exact method signatures, call paths, and cross-service impacts an AI coding agent needs to work autonomously.
  18. ---
  19. ## How it looks
  20. <p align="center">
  21. <img src="assets/corbell_ui.png" width="48%" alt="Corbell UI" />
  22. <img src="assets/mermaid_diagram.png" width="48%" alt="Mermaid Diagram" />
  23. </p>
  24. ## Star History (thank you)
  25. <p align="center">
  26. <img src="assets/star_history.png" width="70%" alt="Corbell Star History" />
  27. </p>
  28. ## How it works
  29. ```
  30. Your repos → [graph:build] → Service graph (SQLite)
  31. Your docs → [docs:scan] → Design pattern extraction
  32. ↓
  33. [spec new --feature "Payment Retry" --prd-file prd.md]
  34. → Generates 3-4 PRD-driven code search queries (LLM or regex)
  35. → Auto-discovers relevant services via embedding similarity
  36. → Injects graph topology + real code snippets
  37. → Applies your team's established design patterns
  38. → Calls Claude / GPT-4o to write the full design doc
  39. → Displays token usage and estimated cost
  40. → specs/payment-retry.md ✓
  41. ↓
  42. [spec review] → Checks claims against graph → .review.md
  43. [spec decompose] → Parallel task tracks YAML
  44. [export linear] → Linear issues with full method/service context
  45. [export jira] → Jira issues via REST API v3 (reads from workspace.yaml)
  46. ```
  47. No servers. No cloud setup. Runs entirely from your laptop against local repos.
  48. ---
  49. ## Installation
  50. ```bash
  51. pip install corbell
  52. # With LLM support (pick one):
  53. pip install "corbell[anthropic]" # Claude (recommended)
  54. pip install "corbell[openai]" # GPT-4o
  55. # With exports:
  56. pip install "corbell[notion,linear,jira]"
  57. # Everything:
  58. pip install "corbell[anthropic,openai,notion,linear,jira]"
  59. ```
  60. **Requirements**: Python ≥ 3.11
  61. ---
  62. ## 🚀 Quick Setup (2 minutes)
  63. ### Prerequisites
  64. - Python 3.8+ or Node.js 16+ or Go 1.19+ (based on your project)
  65. - Git repository with source code
  66. ### Essential Steps
  67. 1. **Initialize Corbell workspace**
  68. ```bash
  69. corbell init
  70. ```
  71. ✅ Creates `workspace.yaml` in your project root
  72. 2. **Generate your first design document**
  73. ```bash
  74. corbell spec new --prd "Add user authentication feature"
  75. ```
  76. ✅ Creates design document with auto-discovered services
  77. 3. **View architecture graph** (optional)
  78. ```bash
  79. corbell ui serve
  80. ```
  81. ✅ Opens browser at http://localhost:7433
  82. ### Verify Setup
  83. - [ ] `workspace.yaml` exists in your project
  84. - [ ] Design document generated successfully
  85. - [ ] Architecture graph loads (if using UI)
  86. **Need more details?** See [Full Documentation](#full-documentation) below.
  87. ---
  88. ## 📖 Full Documentation
  89. <details>
  90. <summary><strong>Advanced Usage Guide</strong></summary>
  91. ### 1. Initialize a workspace
  92. ```bash
  93. cd ~/my-platform # wherever your repos live
  94. corbell init
  95. ```
  96. Edit `corbell-data/workspace.yaml`:
  97. ```yaml
  98. workspace:
  99. name: my-platform
  100. services:
  101. - id: payments-service
  102. repo: ../payments-service
  103. language: python # python | javascript | typescript | go | java | csharp | rust | ruby | php
  104. - id: auth-service
  105. repo: ../auth-service
  106. language: go
  107. llm:
  108. provider: anthropic # or: openai, ollama, aws, azure, gcp
  109. model: claude-sonnet-4-5-20250929
  110. api_key: ${ANTHROPIC_API_KEY}
  111. context_budget: 100000 # Token limit for prompt context
  112. integrations:
  113. jira:
  114. url: https://yourcompany.atlassian.net
  115. email: you@yourcompany.com
  116. api_token: ${CORBELL_JIRA_API_TOKEN} # or paste directly
  117. project_key: ENG
  118. issue_type: Task # Task | Story | Bug
  119. linear:
  120. api_key: ${CORBELL_LINEAR_API_KEY}
  121. team_id: ${CORBELL_LINEAR_TEAM_ID}
  122. ```
  123. ### 2. Build the knowledge graph
  124. ```bash
  125. corbell graph build --methods # service + dependency graph + call graph, typed signatures, flows
  126. corbell embeddings build # code chunk index for semantic search
  127. corbell docs scan && corbell docs learn # extract patterns from existing RFCs/ADRs
  128. ```
  129. ### 3. Generate a design document
  130. ```bash
  131. export ANTHROPIC_API_KEY="sk-ant-..."
  132. # From a PRD file — services are auto-discovered, no --service flag needed
  133. corbell spec new \
  134. --feature "Payment Retry with Exponential Backoff" \
  135. --prd-file docs/payment-retry-prd.md
  136. # Spec with full call graph and infrastructure context
  137. corbell spec new --feature "Auth Flow" --prd-file prd.md --full-graph
  138. # Inline PRD
  139. corbell spec new --feature "Rate Limiting" --prd "Tier 1: 100 req/min..."
  140. # Document your existing codebase with no PRD at all
  141. corbell spec new --existing
  142. # Add existing design docs as context (ADRs, Confluence exports, RFCs)
  143. corbell spec new --feature "Auth Token Refresh" --prd-file prd.md \
  144. --design-doc docs/auth-design-2023.md
  145. ```
  146. Token usage and estimated cost are shown after every LLM call. Template mode (no LLM key) generates a structured skeleton with graph context filled in.
  147. ### 4. Document architecture constraints
  148. Add a constraints block to any spec and all future specs will respect it:
  149. ```markdown
  150. <!-- CORBELL_CONSTRAINTS_START -->
  151. - **Cloud provider**: Only Azure — no AWS services permitted
  152. - **Latency SLO**: p99 < 200ms for all synchronous API calls
  153. - **Security**: All PII encrypted at rest (AES-256) and in transit (TLS 1.2+)
  154. <!-- CORBELL_CONSTRAINTS_END -->
  155. ```
  156. `corbell spec review` checks proposed designs against these constraints. The `corbell ui serve` graph browser also surfaces them in a persistent bar at the bottom.
  157. ### 5. Review, approve, decompose, export
  158. ```bash
  159. corbell spec review specs/payment-retry.md # → .review.md sidecar
  160. corbell spec approve specs/payment-retry.md
  161. corbell spec decompose specs/payment-retry.md # → .tasks.yaml
  162. # Export to Linear
  163. export CORBELL_LINEAR_API_KEY="lin_api_..."
  164. corbell export linear specs/payment-retry.tasks.yaml
  165. # Export to Jira (credentials in workspace.yaml)
  166. corbell export jira specs/payment-retry.tasks.yaml
  167. ```
  168. </details>
  169. <details>
  170. <summary><strong>Architecture graph browser</strong></summary>
  171. ```bash
  172. corbell ui serve # opens http://localhost:7433 · Ctrl+C to stop
  173. corbell ui serve --port 8080 --no-browser
  174. ```
  175. An interactive local graph view — no cloud, no sign-in, reads from your existing SQLite store:
  176. - **Force-directed graph** — services (sized by method count), data stores, queues, execution flows. Zoom, pan, drag.
  177. - **Detail panel** — click any service to see: language, dependencies, HTTP callers, typed method signatures, execution flows (e.g. `LoginFlow`), git change coupling pairs with strength %.
  178. - **Constraints bar** — all `CORBELL_CONSTRAINTS_START` blocks from your spec files shown as persistent amber pills at the bottom. Click to expand.
  179. - **Sidebar** — filterable service list, stores, queues, flows with search.
  180. </details>
  181. <details>
  182. <summary><strong>CLI Reference</strong></summary>
  183. ```
  184. graph Service dependency graph
  185. build --methods for call graph + typed signatures + git coupling + flows
  186. services List discovered services
  187. deps Show service dependencies
  188. callpath Find call paths between methods
  189. embeddings Code embedding index
  190. build Index code chunks
  191. query Semantic search
  192. docs Design doc patterns
  193. scan / learn / patterns
  194. spec Design spec lifecycle
  195. new --feature --prd-file --prd --design-doc --existing --no-llm
  196. lint Validate structure (--ci exits 1)
  197. review Check spec vs graph → .review.md
  198. approve / decompose / context
  199. export notion | linear | jira
  200. ui Architecture graph browser
  201. serve --port (default 7433) --no-browser
  202. mcp Model Context Protocol server
  203. serve stdio transport for Claude Desktop / Cursor
  204. init Create workspace.yaml
  205. ```
  206. </details>
  207. <details>
  208. <summary><strong>MCP – Model Context Protocol</strong></summary>
  209. Corbell exposes its architecture graph, code embeddings, and spec tools via MCP, so external AI platforms (Cursor, Claude Desktop, Antigravity) can query your codebase context directly.
  210. ### Available Tools
  211. | Tool | Description |
  212. |---|---|
  213. | `graph_query` | Query service dependencies, methods, and call paths |
  214. | `get_architecture_context` | Auto-discover relevant services for a feature description |
  215. | `code_search` | Semantic search across the code embedding index |
  216. | `list_services` | List all services in the workspace graph |
  217. ### Usage
  218. ```bash
  219. # Default: stdio transport (for IDE integrations)
  220. corbell mcp serve
  221. # SSE transport (for web-based MCP clients / MCP Inspector)
  222. corbell mcp serve --transport sse --port 8000
  223. ```
  224. ### IDE Configuration
  225. **Cursor** (`~/.cursor/mcp.json`):
  226. ```json
  227. {
  228. "mcpServers": {
  229. "corbell": {
  230. "command": "corbell",
  231. "args": ["mcp", "serve"]
  232. }
  233. }
  234. }
  235. ```
  236. **Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
  237. ```json
  238. {
  239. "mcpServers": {
  240. "corbell": {
  241. "command": "corbell",
  242. "args": ["mcp", "serve"]
  243. }
  244. }
  245. }
  246. ```
  247. If your IDE overrides the working directory, set the `CORBELL_WORKSPACE` environment variable:
  248. ```bash
  249. env CORBELL_WORKSPACE=/path/to/my-platform corbell mcp serve
  250. ```
  251. </details>
  252. <details>
  253. <summary><strong>Auto service discovery</strong></summary>
  254. When you run `corbell spec new`, Corbell discovers which services are relevant to your PRD **automatically** — without you having to specify `--service`:
  255. 1. Generates 3-4 natural-language code search queries from your PRD (using LLM or regex fallback)
  256. 2. Encodes them with the same `sentence-transformers/all-MiniLM-L6-v2` model used for indexing
  257. 3. Runs similarity search against all indexed code chunks
  258. 4. Ranks services by how many of their chunks appear in the top results
  259. 5. Auto-includes any services tagged as `infrastructure` (e.g. AWS CDK repos) to provide comprehensive context
  260. 6. Selects the top-scoring services and builds context from them
  261. Preview what would be discovered without generating a spec:
  262. ```bash
  263. corbell spec context "Add exponential backoff retry to payment processing"
  264. ```
  265. </details>
  266. <details>
  267. <summary><strong>LLM providers</strong></summary>
  268. | Provider | Models | Key env var |
  269. |---|---|---|
  270. | `anthropic` | `claude-sonnet-4-5`, `claude-haiku-4-5` | `ANTHROPIC_API_KEY` |
  271. | `openai` | `gpt-4o`, `gpt-4o-mini`, `gpt-4-turbo` | `OPENAI_API_KEY` |
  272. | `ollama` | `llama3`, `mistral`, any local model | (none) |
  273. | `aws` | `us.anthropic.claude-sonnet-4-*` | `BEDROCK_API_KEY` or IAM |
  274. | `azure` | `gpt-4o`, any deployment | `AZURE_OPENAI_API_KEY` + `AZURE_OPENAI_ENDPOINT` |
  275. | `gcp` | `claude-sonnet-4-5@20250514` | `GOOGLE_APPLICATION_CREDENTIALS` |
  276. </details>
  277. ---
  278. ## Advanced Topics
  279. <details>
  280. <summary><strong>Architecture Details</strong></summary>
  281. Corbell runs entirely locally, no cloud required:
  282. - **Graph store**: SQLite (default). Optional: Neo4j for large multi-repo topologies.
  283. - **Embeddings**: `sentence-transformers/all-MiniLM-L6-v2` (local). Storage backend is pluggable via `storage.embeddings.backend` in `workspace.yaml`.
  284. - **UI**: Python stdlib `http.server` + D3.js via CDN. Zero extra dependencies.
  285. - **LLM**: Not required for graph/embedding/UI commands. Claude/GPT-4o/Ollama for spec generation.
  286. ### What `graph build --methods` extracts
  287. | Signal | Languages | Result |
  288. |---|---|---|
  289. | Typed method signatures | Python, TS, Go, Java, C#, Rust, Ruby, PHP | `MethodNode.typed_signature` |
  290. | Call edges | All 9 | `method_call` edges |
  291. | DB/queue/HTTP dependencies | All 9 | `DataStoreNode`, `QueueNode`, `http_call` |
  292. | Git change coupling | Any git repo | `git_coupling` edges with strength score |
  293. | Execution flow traces | All 9 | `FlowNode` + `flow_step` edges |
  294. | Infrastructure as Code | TS / JS | Auto-tags CDK/Terraform as `infrastructure` |
  295. </details>
  296. <details>
  297. <summary><strong>CI integration</strong></summary>
  298. ```yaml
  299. # .github/workflows/spec-lint.yml
  300. - name: Lint architecture specs
  301. run: |
  302. pip install corbell
  303. corbell spec lint specs/my-feature.md --ci
  304. ```
  305. </details>
  306. <details>
  307. <summary><strong>Development</strong></summary>
  308. ```bash
  309. git clone https://github.com/your-org/corbell && cd Corbell
  310. pip install -e ".[dev]"
  311. pytest tests/ -q
  312. corbell --help
  313. ```
  314. </details>
  315. ---
  316. ## Roadmap
  317. We are moving away from hardcoded procedural flows toward a fully **agentic architecture**. Instead of a fixed pipeline, Corbell will treat its core capabilities as dynamic tools:
  318. - **Features as Tools**: Enabling agents to autonomously select when to query the graph, search embeddings, or analyze patterns based on the specific complexity of a feature request.
  319. - **Dynamic Reasoning**: Moving the orchestration logic into the agentic layer so it can backtrack, refine queries, and cross-reference services without hardcoded sequence constraints.
  320. - **Agentic Review Flow**: Self-correcting design docs where the agent uses the architecture graph as a real-time validator during the generation process.
  321. ---
  322. [![MseeP.ai Security Assessment Badge](https://mseep.net/pr/corbell-ai-corbell-badge.png)](https://mseep.ai/app/corbell-ai-corbell)
  323. ## License
  324. Apache 2.0 — see [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.