{"id":49652427,"url":"https://github.com/sourcebridge-ai/sourcebridge","last_synced_at":"2026-05-06T05:02:14.077Z","repository":{"id":349296627,"uuid":"1190170431","full_name":"sourcebridge-ai/sourcebridge","owner":"sourcebridge-ai","description":"SourceBridge.ai — Understand any codebase, fast. A codebase field guide and context layer for unfamiliar systems.","archived":false,"fork":false,"pushed_at":"2026-05-01T15:13:30.000Z","size":12401,"stargazers_count":10,"open_issues_count":7,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-01T15:24:36.632Z","etag":null,"topics":["code-comprehension","code-navigation","codebase-analysis","developer-tools","documentation","go","graphql","grpc","nextjs","ollama","open-source","static-analysis"],"latest_commit_sha":null,"homepage":"https://sourcebridge.ai","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sourcebridge-ai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":"CLA.md"}},"created_at":"2026-03-24T03:02:51.000Z","updated_at":"2026-05-01T14:11:59.000Z","dependencies_parsed_at":null,"dependency_job_id":"d6fa31a2-d83d-4447-b02b-b04e58a25ed3","html_url":"https://github.com/sourcebridge-ai/sourcebridge","commit_stats":null,"previous_names":["jstuart0/sourcebridge","sourcebridge-ai/sourcebridge"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/sourcebridge-ai/sourcebridge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcebridge-ai%2Fsourcebridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcebridge-ai%2Fsourcebridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcebridge-ai%2Fsourcebridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcebridge-ai%2Fsourcebridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sourcebridge-ai","download_url":"https://codeload.github.com/sourcebridge-ai/sourcebridge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcebridge-ai%2Fsourcebridge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32679444,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-06T02:33:58.958Z","status":"ssl_error","status_checked_at":"2026-05-06T02:33:39.611Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["code-comprehension","code-navigation","codebase-analysis","developer-tools","documentation","go","graphql","grpc","nextjs","ollama","open-source","static-analysis"],"created_at":"2026-05-06T05:02:13.013Z","updated_at":"2026-05-06T05:02:14.068Z","avatar_url":"https://github.com/sourcebridge-ai.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"web/public/logo.png\" alt=\"SourceBridge.ai\" width=\"128\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eSourceBridge.ai\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\u003cstrong\u003eThe field guide your codebase should have had.\u003c/strong\u003e\u003c/p\u003e\n\n[![CI](https://github.com/sourcebridge-ai/sourcebridge/actions/workflows/ci.yml/badge.svg)](https://github.com/sourcebridge-ai/sourcebridge/actions/workflows/ci.yml)\n[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](LICENSE)\n[![Go](https://img.shields.io/badge/Go-1.25+-00ADD8.svg)](https://go.dev/)\n[![Release](https://img.shields.io/github/v/release/sourcebridge-ai/sourcebridge)](https://github.com/sourcebridge-ai/sourcebridge/releases)\n[![Docker Pulls](https://img.shields.io/docker/pulls/sourcebridge/sourcebridge-api)](https://hub.docker.com/u/sourcebridge)\n\n## What is SourceBridge?\n\nSourceBridge is a requirement-aware code comprehension platform. Point it at any codebase and it generates field guides -- cliff notes, learning paths, code tours, architecture diagrams, and workflow stories -- so your team can understand how a system actually works. It also traces requirements to code, runs AI-powered reviews, and serves as an MCP server for AI agent integration.\n\nMost tools help you search code. **SourceBridge helps you understand systems.**\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/SourceBridge-Overview.png\" alt=\"Repository overview showing cliff notes, code tours, and learning paths\" width=\"800\"\u003e\n\u003c/p\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eMore screenshots\u003c/strong\u003e\u003c/summary\u003e\n\n### Cliff Notes\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/SourceBridge-CliffNotes.png\" alt=\"AI-generated cliff notes with hierarchical code summaries\" width=\"800\"\u003e\n\u003c/p\u003e\n\n### Admin Monitor\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/SourceBridge-Generation.png\" alt=\"LLM job queue with real-time generation progress\" width=\"800\"\u003e\n\u003c/p\u003e\n\n### Semantic Search\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/SourceBridge-Search.png\" alt=\"Natural language search against the repository graph\" width=\"800\"\u003e\n\u003c/p\u003e\n\n\u003c/details\u003e\n\n## Key Features\n\n- **Code Indexing** -- Tree-sitter based parsing for Go, Python, TypeScript, JavaScript, Java, Rust, and C++\n- **Field Guides** -- Cliff notes, learning paths, code tours, workflow stories, and system explanations at repository, file, and symbol levels\n- **Requirement Tracing** -- Import requirements from Markdown or CSV, auto-link to code, generate traceability matrices\n- **Code Review** -- AI-powered structured reviews (security, SOLID, performance, reliability, maintainability)\n- **Code Discussion** -- Conversational exploration with full codebase context\n- **Architecture Diagrams** -- Auto-generated Mermaid diagrams from code structure\n- **Impact Analysis** -- Simulate changes and see affected requirements and code paths\n- **MCP Server** -- Model Context Protocol support for AI agent integration ([setup guide](docs/user/mcp-clients.md))\n- **VS Code Extension** -- First-class editor integration: inline requirement lenses, streaming AI chat (`Cmd+I`), create/edit requirements from the sidebar, one-keystroke field guides ([install guide](plugins/vscode/README.md))\n- **Multi-Provider LLM** -- Works with cloud APIs (Anthropic, OpenAI, Gemini, OpenRouter) or fully local inference (Ollama, vLLM, llama.cpp, SGLang, LM Studio)\n- **GraphQL API** -- Full programmatic access to all platform capabilities\n- **CLI** -- Complete command-line interface for scripting and automation\n\n## Quick Start\n\n### Docker Hub (fastest)\n\nNo git clone needed. Just pull and run:\n\n```bash\n# Download the compose file\ncurl -O https://raw.githubusercontent.com/sourcebridge-ai/sourcebridge/main/docker-compose.hub.yml\n\n# Start SourceBridge (uses Ollama by default — no API key required)\ndocker compose -f docker-compose.hub.yml up -d\n```\n\nOpen [http://localhost:3000](http://localhost:3000) and create your admin account.\n\n\u003e **Security: set your secrets before exposing SourceBridge to a network.**\n\u003e\n\u003e The default compose file uses sentinel values (`INSECURE-DEFAULT-CHANGE-ME-NOW`)\n\u003e for the database password, gRPC shared secret, and JWT signing key.  These are\n\u003e intentionally loud and self-identifying — the API server will emit a repeating\n\u003e warning until they are replaced.\n\u003e\n\u003e Run the init script once before starting the stack:\n\u003e\n\u003e ```bash\n\u003e # Generates .env with strong random values (chmod 0600)\n\u003e curl -O https://raw.githubusercontent.com/sourcebridge-ai/sourcebridge/main/scripts/init-hub-secrets.sh\n\u003e chmod +x init-hub-secrets.sh \u0026\u0026 ./init-hub-secrets.sh\n\u003e\n\u003e # Then start the stack — it picks up .env automatically\n\u003e docker compose -f docker-compose.hub.yml up -d\n\u003e ```\n\u003e\n\u003e **Environment variables the init script sets:**\n\u003e\n\u003e | Variable | Purpose |\n\u003e |---|---|\n\u003e | `SURREAL_PASS` | SurrealDB admin password (also controls `SURREAL_USER`, default `root`) |\n\u003e | `SOURCEBRIDGE_GRPC_SECRET` | Shared secret between the API server and the AI worker |\n\u003e | `SOURCEBRIDGE_JWT_SECRET` | JWT signing key for all user sessions |\n\u003e\n\u003e To rotate secrets later, run `./init-hub-secrets.sh --force`.\n\u003e All active sessions will be invalidated.\n\n\u003e **Encryption key: auto-generated on first boot, persisted in a named volume.**\n\u003e\n\u003e The `encryption-key-init` service in `docker-compose.hub.yml` generates a unique\n\u003e 32-byte key on first boot and writes it to the `sourcebridge-secrets` named volume.\n\u003e Subsequent `up` calls reuse the existing key — no environment variable setup needed\n\u003e for encryption.\n\u003e\n\u003e **`docker compose down -v` deletes both data and the encryption key**, which means\n\u003e all stored API keys (saved through `/admin/llm`) are unrecoverable without the key.\n\u003e Back up the `sourcebridge-secrets` volume before any `-v` teardown.\n\u003e See [`docs/admin/llm-config.md`](docs/admin/llm-config.md#wipe-and-re-enter) for the\n\u003e wipe-and-re-enter procedure when you need to start fresh.\n\n\u003e **Using a cloud LLM?** Pass your provider config inline:\n\u003e\n\u003e ```bash\n\u003e SOURCEBRIDGE_LLM_PROVIDER=anthropic \\\n\u003e SOURCEBRIDGE_LLM_API_KEY=sk-ant-... \\\n\u003e SOURCEBRIDGE_LLM_MODEL=claude-sonnet-4-20250514 \\\n\u003e docker compose -f docker-compose.hub.yml up -d\n\u003e ```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eFull configuration examples\u003c/strong\u003e\u003c/summary\u003e\n\n#### Anthropic (recommended for quality)\n\n```bash\nSOURCEBRIDGE_LLM_PROVIDER=anthropic \\\nSOURCEBRIDGE_LLM_API_KEY=sk-ant-api03-xxxxx \\\nSOURCEBRIDGE_LLM_MODEL=claude-sonnet-4-20250514 \\\ndocker compose -f docker-compose.hub.yml up -d\n```\n\n#### OpenAI\n\n```bash\nSOURCEBRIDGE_LLM_PROVIDER=openai \\\nSOURCEBRIDGE_LLM_API_KEY=sk-xxxxx \\\nSOURCEBRIDGE_LLM_MODEL=gpt-4o \\\ndocker compose -f docker-compose.hub.yml up -d\n```\n\n#### Ollama (local, free)\n\n```bash\n# Install Ollama first: https://ollama.com\nollama pull qwen3:32b\n\n# No API key needed — Ollama is the default\ndocker compose -f docker-compose.hub.yml up -d\n```\n\n\u003e **Quality gates**: Living Wiki evaluates generated pages against tier-aware thresholds.\n\u003e `qwen3:32b` is classified as `TierLocal` automatically, which uses relaxed thresholds\n\u003e appropriate for open-weight models. No configuration required for the default install.\n\u003e To override the tier for a specific model, set it in **Admin → Comprehension → Model\n\u003e Registry**. See [`docs/admin/llm-config.md`](docs/admin/llm-config.md#capability-tiers-and-quality-gates).\n\n#### OpenRouter (access to 100+ models)\n\n```bash\nSOURCEBRIDGE_LLM_PROVIDER=openrouter \\\nSOURCEBRIDGE_LLM_API_KEY=sk-or-xxxxx \\\nSOURCEBRIDGE_LLM_MODEL=anthropic/claude-sonnet-4-20250514 \\\ndocker compose -f docker-compose.hub.yml up -d\n```\n\n#### Production secrets\n\nRun `scripts/init-hub-secrets.sh` (recommended) to generate a `.env` with strong\nrandom values for `SURREAL_PASS`, `SOURCEBRIDGE_GRPC_SECRET`, and\n`SOURCEBRIDGE_JWT_SECRET`.  The compose file reads them automatically.\n\n```bash\n./scripts/init-hub-secrets.sh          # creates .env (chmod 0600)\ndocker compose -f docker-compose.hub.yml up -d\n```\n\nOr set them inline without a `.env`:\n\n```bash\nSURREAL_PASS=$(openssl rand -hex 32) \\\nSOURCEBRIDGE_JWT_SECRET=$(openssl rand -hex 32) \\\nSOURCEBRIDGE_GRPC_SECRET=$(openssl rand -hex 32) \\\nSOURCEBRIDGE_LLM_PROVIDER=anthropic \\\nSOURCEBRIDGE_LLM_API_KEY=sk-ant-api03-xxxxx \\\nSOURCEBRIDGE_LLM_MODEL=claude-sonnet-4-20250514 \\\ndocker compose -f docker-compose.hub.yml up -d\n```\n\n\u003c/details\u003e\n\n### Try the demo\n\nSourceBridge includes a sample TypeScript project you can index immediately:\n\n```bash\ngit clone https://github.com/sourcebridge-ai/sourcebridge.git\ncd sourcebridge\n./demo.sh\n```\n\nThe demo starts SourceBridge, indexes a 44-file sample API, and generates cliff notes, code tours, and architecture diagrams. Open [http://localhost:3000](http://localhost:3000) to explore.\n\n### CLI — one line, any platform\n\n```bash\ncurl -fsSL https://\u003cyour-sourcebridge-server\u003e/install.sh | sh -s -- --server https://\u003cyour-sourcebridge-server\u003e\n```\n\nInstalls to `~/.local/bin/sourcebridge` (no `sudo`), authenticates against\nyour server, and you're ready to run `sourcebridge setup claude` in any\nindexed repository. See [Installation](docs/user/installation.md) for the\ntrust model, alternate paths (`brew install sourcebridge-ai/tap/sourcebridge`,\nmanual download, build from source), and upgrade/uninstall instructions.\n\n### Server — Docker compose\n\n```bash\ngit clone https://github.com/sourcebridge-ai/sourcebridge.git\ncd sourcebridge\ncp .env.example .env   # configure your LLM provider\ndocker compose up -d\n```\n\n### Helm / Kubernetes\n\nFor production deployments:\n\n```bash\nhelm install sourcebridge deploy/helm/sourcebridge/ \\\n  --set llm.provider=anthropic \\\n  --set llm.apiKey=$ANTHROPIC_API_KEY\n```\n\nSee [Helm Guide](docs/self-hosted/helm-guide.md) for full configuration options, including air-gapped and local inference setups.\n\n## VS Code Extension\n\nUse SourceBridge without leaving your editor. The extension is in [`plugins/vscode/`](plugins/vscode/) and talks to any SourceBridge server — local, Docker, Helm, or a shared team deployment.\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eInline requirement lenses · streaming AI chat · sidebar CRUD · one-keystroke field guides\u003c/em\u003e\n\u003c/p\u003e\n\n### Install\n\nFrom a pre-built VSIX:\n\n```bash\n# Build the VSIX from source\nmake package-vscode\n\n# Install it into your local VS Code\nmake install-vscode\n```\n\nOr from inside VS Code: `Cmd+Shift+P` → **Extensions: Install from VSIX…** → pick `plugins/vscode/sourcebridge-*.vsix`.\n\n### Configure\n\n1. `Cmd+Shift+P` → **SourceBridge: Sign In**\n2. Enter your server URL (e.g. `http://localhost:8080` for local dev, or your team's deployed URL)\n3. Pick sign-in method (browser OIDC or local password)\n\nThe status bar (bottom-left) reflects connection state: `connected · \u003crepo\u003e`, `offline · retry in Ns`, `sign in required`, etc. Click it for quick actions.\n\n### Highlights\n\n| Flow | How | What happens |\n|---|---|---|\n| **Ask streaming** | `Cmd+I` on any selection | Chat panel opens; tokens stream in live via MCP (fallback: non-streaming GraphQL if server doesn't mount MCP) |\n| **Show linked requirements** | `Cmd+.` on a function | Lightbulb menu lists linked requirements; click to open detail panel |\n| **Create requirement** | `Cmd+.` on an unlinked symbol → *Create requirement from this symbol…* | Inline flow pre-fills title from the symbol name; the new requirement is linked automatically |\n| **Edit / delete from sidebar** | Hover a requirement row in the activity bar | Pencil + trash icons; delete soft-deletes (30-day recycle bin) |\n| **Field guide for file** | `Cmd+K N` | Generates cliff notes for the active file and opens the panel |\n| **Change Risk tree** | Activity bar → Change Risk | Shows changed files / affected requirements / stale field guides from the latest impact report |\n| **Scoped palette** | `Cmd+Shift+;` | Context-filtered picker — only shows actions valid for your current focus |\n\nFull feature list + troubleshooting in [`plugins/vscode/README.md`](plugins/vscode/README.md).\n\n### Develop / contribute\n\n```bash\ncd plugins/vscode\nnpm install\nnpm run watch      # rebuilds on save\n# Open the folder in VS Code, press F5 → \"Run Extension\" for a dev host\n```\n\nTests: `make test-vscode` (or `npm test` from inside `plugins/vscode/`).\n\n## Architecture\n\n```\n                    ┌──────────────────────────────────┐\n                    │           Clients                │\n                    │   Web UI / CLI / MCP / GraphQL   │\n                    └──────────────┬───────────────────┘\n                                   │\n                    ┌──────────────▼───────────────────┐\n                    │        Go API Server             │\n                    │   chi router + gqlgen GraphQL    │\n                    │   JWT auth, OIDC SSO, REST       │\n                    │   tree-sitter code indexer        │\n                    └───────┬──────────────┬───────────┘\n                            │              │\n               ┌────────────▼──┐    ┌──────▼──────────┐\n               │   SurrealDB   │    │  Python Worker   │\n               │   (embedded   │    │  gRPC service    │\n               │   or external)│    │  AI reasoning,   │\n               └───────────────┘    │  linking,        │\n                                    │  requirements,   │\n               ┌───────────────┐    │  knowledge,      │\n               │  Redis Cache  │    │  contracts       │\n               │  (optional,   │    └──────┬───────────┘\n               │  defaults to  │           │\n               │  in-memory)   │    ┌──────▼───────────┐\n               └───────────────┘    │   LLM Provider   │\n                                    │  Cloud or Local   │\n                                    └──────────────────┘\n```\n\n**Go API Server** (`internal/`, `cmd/`) -- HTTP and GraphQL API, authentication, code indexing, and request routing. Handles tree-sitter parsing for 7 languages.\n\n**Python gRPC Worker** (`workers/`) -- AI reasoning engine that communicates with LLM providers. Services include reasoning, linking, requirements analysis, knowledge extraction, and contract generation.\n\n**Next.js Web UI** (`web/`) -- React 19, Tailwind CSS, CodeMirror 6 for code display, @xyflow/react for dependency graphs, recharts for metrics, Mermaid for architecture diagrams.\n\n**SurrealDB** -- Primary data store. Runs embedded for single-node setups or connects to an external instance for production.\n\n**Redis** -- Optional caching layer. Defaults to an in-memory cache when Redis is not configured.\n\n## Configuration\n\nSourceBridge reads configuration from a TOML config file and environment variables. Environment variables use the `SOURCEBRIDGE_` prefix and override file values.\n\nSee [`config.toml.example`](config.toml.example) for a complete annotated example.\n\n### Key Environment Variables\n\n| Variable | Description | Default |\n|---|---|---|\n| `SOURCEBRIDGE_LLM_PROVIDER` | LLM provider name | `ollama` |\n| `SOURCEBRIDGE_LLM_BASE_URL` | LLM API endpoint | (provider default) |\n| `SOURCEBRIDGE_LLM_MODEL` | Model name | (provider default) |\n| `SOURCEBRIDGE_LLM_API_KEY` | API key for cloud providers | -- |\n| `SOURCEBRIDGE_SERVER_HTTP_PORT` | API server port | `8080` |\n| `SOURCEBRIDGE_SERVER_GRPC_PORT` | gRPC port for worker communication | `50051` |\n| `SOURCEBRIDGE_STORAGE_SURREAL_MODE` | `embedded` or `external` | `embedded` |\n| `SOURCEBRIDGE_STORAGE_SURREAL_URL` | SurrealDB connection URL | -- |\n| `SOURCEBRIDGE_STORAGE_REDIS_MODE` | `redis` or `memory` | `memory` |\n| `SOURCEBRIDGE_SECURITY_JWT_SECRET` | JWT signing secret | (required for auth) |\n| `SOURCEBRIDGE_SECURITY_MODE` | Security mode (`oss` or `enterprise`) | `oss` |\n\n## OSS vs Enterprise tenancy\n\nSourceBridge OSS uses **single-tenant mode**: all repositories are owned by the\nbuilt-in `tenant=default` principal. Every authenticated user can access every\nrepository — there is no per-user or per-team repo isolation.\n\nThis is the intended OSS posture for small teams and individual use.\n\n**Multi-user deployments that require repo isolation** (i.e. user A cannot see\nuser B's repositories) need the enterprise edition, which adds per-tenant\n`RepoAccessMiddleware` enforcement.\n\nThe API server emits a one-time `oss_single_tenant_mode` warning at boot as a\nreminder. This is informational, not an error — it confirms that the OSS posture\nis active and expected.\n\n## LLM Providers\n\nSourceBridge supports both cloud-hosted and local inference providers. Configure per-operation models for cost optimization (e.g., a smaller model for summaries, a larger one for reviews).\n\n### Cloud Providers\n\n| Provider | Config Value | API Key Variable | Models |\n|---|---|---|---|\n| Anthropic | `anthropic` | `ANTHROPIC_API_KEY` | Claude Sonnet 4, Claude Haiku, etc. |\n| OpenAI | `openai` | `OPENAI_API_KEY` | GPT-4o, GPT-4o-mini, etc. |\n| Google Gemini | `gemini` | `GOOGLE_API_KEY` | Gemini 2.5 Pro, Flash, etc. |\n| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` | Any model on OpenRouter |\n\n### Local Inference\n\n| Provider | Config Value | Notes |\n|---|---|---|\n| Ollama | `ollama` | Easiest local setup. Pull a model and go. |\n| vLLM | `vllm` | High-throughput serving with PagedAttention |\n| llama.cpp | `llamacpp` | CPU/GPU inference, GGUF models |\n| SGLang | `sglang` | Optimized serving with RadixAttention |\n| LM Studio | `lmstudio` | Desktop app with OpenAI-compatible API |\n\nAll local providers expose an OpenAI-compatible API. Set `base_url` to the local endpoint.\n\n## Using with Claude Code\n\nAfter indexing a repository, generate a `.claude/CLAUDE.md` skill card that gives Claude Code a structured map of the codebase — per-subsystem sections, call-graph-derived warnings, and representative symbols — so the agent understands the architecture before refactoring:\n\n```bash\nsourcebridge setup claude --repo-id \u003cid\u003e\n```\n\nThis writes three files into the repository:\n\n- `.claude/CLAUDE.md` — the skill card with `## Subsystem:` sections derived from clustering data\n- `.claude/sourcebridge.json` — metadata for future refreshes (gitignored by default)\n- `.mcp.json` — Claude Code MCP server configuration so the agent can call SourceBridge tools directly\n\nRe-run the command after re-indexing to refresh the skill card.\n\nSee [Claude Code memory documentation](https://docs.claude.com/en/docs/claude-code/memory) for how Claude Code reads `.claude/CLAUDE.md`.\n\n## CLI Reference\n\n| Command | Description |\n|---|---|\n| `sourcebridge serve` | Start the API server |\n| `sourcebridge index \u003cpath\u003e` | Index a repository with tree-sitter |\n| `sourcebridge setup claude` | Generate a `.claude/CLAUDE.md` skill card for Claude Code |\n| `sourcebridge import \u003cfile\u003e` | Import requirements from Markdown or CSV |\n| `sourcebridge trace \u003creq-id\u003e` | Trace a requirement to linked code |\n| `sourcebridge review \u003cpath\u003e` | Run an AI-powered code review |\n| `sourcebridge ask \u003cquestion\u003e` | Ask a question about the codebase |\n\nSee [CLI Reference](docs/user/cli-reference.md) for full flag documentation.\n\n## Development\n\n### Prerequisites\n\n- Go 1.25+\n- Python 3.12+ with [uv](https://docs.astral.sh/uv/)\n- Node.js 22+\n- Git\n\n### Building from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/sourcebridge-ai/sourcebridge.git\ncd sourcebridge\n\n# Build the Go API server\nmake build-go\n\n# Install Python worker dependencies\nmake build-worker\n\n# Build the web UI\nmake build-web\n\n# Or build everything at once\nmake build\n```\n\n### Container Images\n\nPre-built images are published on every push to `main` (and on `v*` tags) to\nboth registries below, with identical tags:\n\n| Registry | Image |\n|----------|-------|\n| GitHub Container Registry | `ghcr.io/sourcebridge-ai/sourcebridge-{api,worker,web}` |\n| Docker Hub | `sourcebridge/sourcebridge-{api,worker,web}` |\n\nTag policy:\n\n- `sha-\u003cshort\u003e` — the seven-character commit SHA of the build (e.g. `sha-9d15856`)\n- `latest` — moves with the latest `main` commit\n- `vX.Y.Z` and `stable` — set when a `v*` tag is pushed (no prerelease suffix)\n\nFor local image builds (mirrors the CI tag policy), see\n[`scripts/build-and-deploy.sh`](scripts/build-and-deploy.sh) — `--help` for usage.\n\n### Running Locally\n\nSourceBridge runs three processes in development. The API server embeds\nSurrealDB by default, so you do not need a separate database\ncontainer — just start the three processes below in their own terminals\nand you have a working stack.\n\n```bash\n# Terminal 1 — API server (builds first)\nmake dev\n\n# Terminal 2 — Next.js web UI\nmake dev-web\n\n# Terminal 3 — Python AI worker (required for agentic features,\n# embeddings, and code review). Run after `make build-worker`.\nmake dev-worker\n```\n\nThe worker can also be invoked directly via the registered console\nscript: `cd workers \u0026\u0026 uv run sourcebridge-worker`. Both forms are\nequivalent; `make dev-worker` is the canonical entry point used\nthroughout the docs.\n\nStart the worker before (or shortly after) the API server. Agentic and\nembedding features activate when the worker is reachable on\n`localhost:50051`; without the worker the API server still serves\nindexing, browsing, and CRUD.\n\n### Testing\n\n```bash\n# Run all tests (Go + web + worker)\nmake test\n\n# Run linting (Go + web + worker)\nmake lint\n\n# Run CI checks locally (lint + test)\nmake ci\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the full development workflow.\n\n## Deployment\n\n### Docker Compose\n\nBest for evaluation and small teams. See [Docker Compose quick start](#docker-compose-recommended) above.\n\n### Kubernetes with Helm\n\nFor production and multi-team deployments:\n\n- [Helm Guide](docs/self-hosted/helm-guide.md) -- Installation, values reference, and examples\n- [Deployment Guide](docs/admin/deployment.md) -- Architecture considerations and scaling\n- [Air-Gapped Installations](docs/self-hosted/air-gapped.md) -- Deploying without internet access\n- [Upgrade Guide](docs/self-hosted/upgrade.md) -- Version upgrades and migrations\n- [Backup and Restore](docs/admin/backup-restore.md) -- Data protection procedures\n\n### Migrating external uptime monitors\n\nPrior to Phase 5, the paths `/healthz` and `/readyz` were exposed via the public Ingress. They have been removed from public routing — those paths still exist on the API pod (kubelet probes them directly via pod IP), but they are no longer reachable at `https://\u003chost\u003e/healthz` or `https://\u003chost\u003e/readyz`.\n\n**If you run an external uptime check against either of those paths, update it to:**\n\n```\nhttps://\u003chost\u003e/api/health\n```\n\nThis endpoint returns `{\"ok\":true}` with HTTP 200 and requires no authentication. It was added in the same release cycle and is the intended public health signal for external monitors, CDN origin checks, and load balancer health probes that operate outside the cluster.\n\n## Versioning\n\nEvery SourceBridge build carries a version string that's derived from\ngit — no hand-editing, no manifest bumping. The same string is reported\nby the running API server, the Python worker, the Next.js web bundle,\nand the OCI image labels.\n\n| Build context | Version | Example |\n|---|---|---|\n| Tagged release (`git tag v1.2.3`) | `\u003ctag\u003e` | `v1.2.3` |\n| `main` between releases | `\u003ctag\u003e-dev.\u003cN\u003e+g\u003csha\u003e` | `v0.9.0-rc.3-dev.216+g956607e` |\n| Pull-request build | `\u003ctag\u003e-pr\u003cNUMBER\u003e+g\u003csha\u003e` | `v0.9.0-rc.3-pr147+g956607e` |\n| Local `make build` | `\u003ctag\u003e-local+g\u003csha\u003e[.dirty]` | `v0.9.0-rc.3-local+g956607e.dirty` |\n| No git context (source tarball) | `0.0.0-unknown` | `0.0.0-unknown` |\n\nThe grammar is implemented by `scripts/version.sh`, which the Makefile,\nthe Dockerfiles, and the GitHub Actions workflows all consume. To find\nyour build:\n\n- **Web UI**: sidebar footer (always visible) or **Admin → System\n  status → Build info** (full payload + copy-to-clipboard for support\n  tickets).\n- **HTTP**: `curl https://\u003cyour-server\u003e/api/v1/version` (no auth\n  required).\n- **CLI**: `sourcebridge --version`.\n- **Image**: `docker inspect \u003cimage\u003e | jq '.[0].Config.Labels'` —\n  surfaces `org.opencontainers.image.version` and friends.\n\nTo cut a release: push a `v*` tag. The release workflow takes care of\nbinary builds, image labels, the Homebrew tap formula, and the GitHub\nrelease page. There is no version file to bump by hand.\n\nSee [docs/admin/build-info.md](docs/admin/build-info.md) for the full\nbuild-info reference (debugging mismatches between the web bundle and\nthe API server during a rolling deploy, etc.).\n\n## Documentation\n\n- [Getting Started](docs/user/getting-started.md)\n- [CLI Reference](docs/user/cli-reference.md)\n- [Web UI Guide](docs/user/web-ui-guide.md)\n- [Configuration](docs/admin/configuration.md)\n- [Troubleshooting](docs/admin/troubleshooting.md)\n- [Architecture: Living Wiki orchestrator contract](docs/architecture/livingwiki-orchestrator-contract.md)\n- [Architecture: MCP tool registration](docs/architecture/mcp-tool-registration.md)\n- [Security: CSP audit 2026-05-04](docs/security/csp-audit-2026-05-04.md)\n- [Admin runbook: init-hub-secrets](docs/admin-runbooks/init-hub-secrets.md)\n- [Admin runbook: CSRF and API token roles](docs/admin-runbooks/csrf-and-api-token-roles.md)\n- [Legacy name census (CodeAware → SourceBridge)](docs/codeaware-legacy-census.md)\n\n## Contributing\n\nContributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding standards, and the pull request process.\n\nFirst-time contributors must agree to the [Contributor License Agreement](CLA.md) before their PR can be merged.\n\n## License\n\nSourceBridge is licensed under the [GNU Affero General Public License v3.0](LICENSE).\n\n---\n\n## Did it work?\n\nIf SourceBridge helped you understand a codebase, let us know:\n\n- **It worked?** Give the repo a star — it helps others find the project\n- **Something broke?** [Open an issue](https://github.com/sourcebridge-ai/sourcebridge/issues) — we want to fix it\n- **Have ideas?** [Start a discussion](https://github.com/sourcebridge-ai/sourcebridge/discussions)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsourcebridge-ai%2Fsourcebridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsourcebridge-ai%2Fsourcebridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsourcebridge-ai%2Fsourcebridge/lists"}