1. Initialize a workspace

cd ~/my-platform   # wherever your repos live
corbell init

Edit corbell-data/workspace.yaml:

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

integrations:
  jira:
    url: https://yourcompany.atlassian.net
    email: you@yourcompany.com
    api_token: ${CORBELL_JIRA_API_TOKEN}   # or paste directly
    project_key: ENG
    issue_type: Task                        # Task | Story | Bug
  linear:
    api_key: ${CORBELL_LINEAR_API_KEY}
    team_id: ${CORBELL_LINEAR_TEAM_ID}

2. Build the knowledge graph

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

3. Generate a design document

export ANTHROPIC_API_KEY="sk-ant-..."

# From a PRD file — services are auto-discovered, no --service flag needed
corbell spec new \
  --feature "Payment Retry with Exponential Backoff" \
  --prd-file docs/payment-retry-prd.md

# Spec with full call graph and infrastructure context
corbell spec new --feature "Auth Flow" --prd-file prd.md --full-graph

# Inline PRD
corbell spec new --feature "Rate Limiting" --prd "Tier 1: 100 req/min..."

# Document your existing codebase with no PRD at all
corbell spec new --existing

# Add existing design docs as context (ADRs, Confluence exports, RFCs)
corbell spec new --feature "Auth Token Refresh" --prd-file prd.md \
  --design-doc docs/auth-design-2023.md

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.

4. Document architecture constraints

Add a constraints block to any spec and all future specs will respect it:

<!-- CORBELL_CONSTRAINTS_START -->
- **Cloud provider**: Only Azure — no AWS services permitted
- **Latency SLO**: p99 < 200ms for all synchronous API calls
- **Security**: All PII encrypted at rest (AES-256) and in transit (TLS 1.2+)
<!-- CORBELL_CONSTRAINTS_END -->

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.

5. Review, approve, decompose, export

corbell spec review specs/payment-retry.md     # → .review.md sidecar
corbell spec approve specs/payment-retry.md

corbell spec decompose specs/payment-retry.md  # → .tasks.yaml

# Export to Linear
export CORBELL_LINEAR_API_KEY="lin_api_..."
corbell export linear specs/payment-retry.tasks.yaml

# Export to Jira (credentials in workspace.yaml)
corbell export jira specs/payment-retry.tasks.yaml

corbell ui serve          # opens http://localhost:7433 · Ctrl+C to stop
corbell ui serve --port 8080 --no-browser

An interactive local graph view — no cloud, no sign-in, reads from your existing SQLite store:

• Force-directed graph — services (sized by method count), data stores, queues, execution flows. Zoom, pan, drag.
• 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 %.
• Constraints bar — all CORBELL_CONSTRAINTS_START blocks from your spec files shown as persistent amber pills at the bottom. Click to expand.
• Sidebar — filterable service list, stores, queues, flows with search.

graph       Service dependency graph
  build       --methods for call graph + typed signatures + git coupling + flows
  services    List discovered services
  deps        Show service dependencies
  callpath    Find call paths between methods

embeddings  Code embedding index
  build       Index code chunks
  query       Semantic search

docs        Design doc patterns
  scan / learn / patterns

spec        Design spec lifecycle
  new         --feature --prd-file --prd --design-doc --existing --no-llm
  lint        Validate structure (--ci exits 1)
  review      Check spec vs graph → .review.md
  approve / decompose / context

export      notion | linear | jira

ui          Architecture graph browser
  serve       --port (default 7433) --no-browser

mcp         Model Context Protocol server
  serve       stdio transport for Claude Desktop / Cursor

init        Create workspace.yaml

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.

Available Tools

Usage

# Default: stdio transport (for IDE integrations)
corbell mcp serve

# SSE transport (for web-based MCP clients / MCP Inspector)
corbell mcp serve --transport sse --port 8000

IDE Configuration

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "corbell": {
      "command": "corbell",
      "args": ["mcp", "serve"]
    }
  }
}

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "corbell": {
      "command": "corbell",
      "args": ["mcp", "serve"]
    }
  }
}

If your IDE overrides the working directory, set the CORBELL_WORKSPACE environment variable:

env CORBELL_WORKSPACE=/path/to/my-platform corbell mcp serve

When you run corbell spec new, Corbell discovers which services are relevant to your PRD automatically — without you having to specify --service:

1. Generates 3-4 natural-language code search queries from your PRD (using LLM or regex fallback)
2. Encodes them with the same sentence-transformers/all-MiniLM-L6-v2 model used for indexing
3. Runs similarity search against all indexed code chunks
4. Ranks services by how many of their chunks appear in the top results
5. Auto-includes any services tagged as infrastructure (e.g. AWS CDK repos) to provide comprehensive context
6. Selects the top-scoring services and builds context from them

Preview what would be discovered without generating a spec:

corbell spec context "Add exponential backoff retry to payment processing"

Corbell runs entirely locally, no cloud required:

• Graph store: SQLite (default). Optional: Neo4j for large multi-repo topologies.
• Embeddings: sentence-transformers/all-MiniLM-L6-v2 (local). Storage backend is pluggable via storage.embeddings.backend in workspace.yaml.
• UI: Python stdlib http.server + D3.js via CDN. Zero extra dependencies.
• LLM: Not required for graph/embedding/UI commands. Claude/GPT-4o/Ollama for spec generation.

What graph build --methods extracts

# .github/workflows/spec-lint.yml
- name: Lint architecture specs
  run: |
    pip install corbell
    corbell spec lint specs/my-feature.md --ci

git clone https://github.com/your-org/corbell && cd Corbell
pip install -e ".[dev]"
pytest tests/ -q
corbell --help