Alpha CodIn

The codebase intelligence layer for developers and AI coding agents.
A continuously updated local index of your code, git history, tests, and decisions —
with cited answers, change-impact analysis, and code-health improvements across your editor, your pull requests, and your dashboard.

---

What is Alpha CodIn?

Alpha CodIn builds a local knowledge graph of your repository — symbols, calls, imports, tests, ownership, architectural decisions — and keeps it continuously updated as you work. On top of that graph it serves:

• A documentation wiki generated from your code's actual structure, refreshed on every save.
• An MCP server that gives AI agents (Claude Code, Codex, Cursor, VS Code Copilot, OpenCode, Hermes) cited, graph-aware answers instead of stale grep results.
• A web dashboard for code health, architecture maps, drift detection, and refactoring opportunities.
• Agent tooling hooks that let every AI tool call resolve against the real graph.

Everything runs locally on your machine. Your code never leaves it unless you point Alpha CodIn at a hosted LLM provider.

Quick Start

1. Install the CLI

```bash

pip

pip install alphacodin

or uv / uvx (no install)

uvx alphacodin --help ```

2. Index your repository

```bash cd /path/to/your-repo alphacodin init # full wiki + knowledge graph

or the fast path for very large repos:

alphacodin init --mode fast ```

With no API key configured, Alpha CodIn renders the whole wiki structurally — no model, no cost. Add a provider key later for prose pages:

```bash export ANTHROPIC_API_KEY=sk-ant-... # or OPENAI_API_KEY / GEMINI_API_KEY alphacodin generate # writes the prose pages ```

3. Open the dashboard

```bash alphacodin serve

→ http://localhost:3000 (Web UI)

→ http://localhost:7337 (API)

```

4. Wire up your AI agents

```bash alphacodin agents add --target auto # detects installed agents

or pick explicitly:

alphacodin agents add --target claude-code,codex,cursor,vscode,opencode ```

That writes the correct MCP config, hooks, and instructions for each tool — repo-local by default.

Docker Deployment

Run the full stack (API + Web UI) in a single container:

```bash git clone https://github.com/DeejayAI/alphacodin.git cd alphacodin

Index a repo locally first (here: the alphacodin repo itself)

alphacodin init /path/to/repo

Build and run

docker build -t alphacodin -f docker/Dockerfile . docker run -p 127.0.0.1:7337:7337 -p 127.0.0.1:3000:3000
-v /path/to/repo/.alphacodin:/data
-e ALPHACODIN_API_KEY=change-me
alphacodin ```

Or with Docker Compose:

```bash export ALPHACODIN_DATA=/path/to/repo/.alphacodin export REPO_PATH=/path/to/repo export ALPHACODIN_API_KEY=change-me docker compose -f docker/docker-compose.yml up ```

• Web UI: http://localhost:3000
• API: http://localhost:7337
• The repo directory is mounted read-only; indexes are written to the mounted `/data` volume.
• An MCP-over-stdio image is also available: `docker/Dockerfile.mcp`.

The Web UI

The dashboard renders the generated wiki, the code-health map, architecture pages, decision records, and an AI chat grounded in the same index your agents use. Start it with `alphacodin serve` or the Docker image above.

Editor & Agent Integration

Alpha CodIn wires itself into every major AI coding tool with one command:

```bash alphacodin agents add --target auto ```

Agent	What gets installed	Docs
Claude Code	MCP server registration + CLAUDE.md instructions + hooks	website/claude-code-plugin.md
Codex CLI	MCP config + AGENTS.md guidance	website/codex.md
Cursor	`.cursor/mcp.json` + project rules	—
VS Code / Copilot	`.vscode/mcp.json` + extension (`alphacodin.alphacodin`)	—
OpenCode	Native config + plugin	website/opencode.md
Hermes	MCP transport registration	—

MCP Server

Start it standalone (stdio) or over HTTP/SSE:

```bash alphacodin mcp # stdio — for Claude Code, Codex, Cursor alphacodin mcp --transport http # streamable HTTP alphacodin mcp --transport sse # legacy SSE ```

Default tools (10) — available to every MCP client:

Tool	What it answers
`get_answer`	Cited natural-language questions about the codebase
`get_context`	Triage card for a file, module, or symbol
`get_symbol`	One symbol's body with live-verified line bounds
`search_codebase`	Keyword, meaning, or symbol-name search
`get_risk` / `get_change_risk`	Review priority for code and pending changes
`get_health`	Code-health scores, hotspots, trends
`get_dead_code`	Unused and unreachable code
`get_why`	Why the code is shaped this way — decisions, history
`get_overview`	The repo in one payload

Workspace mode adds `list_repos` and cross-repo reach; seven more specialist tools (blast radius, dependency paths, execution flows, conformance, architecture, and more) are opt-in via `--tools` or the `mcp.tools` config block.

The CLI at a Glance

```bash alphacodin ask "where do we validate API keys?" # cited answers alphacodin context src/auth/login.ts # triage a file alphacodin risk --branch feature/x # review priority alphacodin impacted-tests src/auth/ # tests to run alphacodin dead-code # unused code alphacodin why # decisions & history alphacodin health # code-health scores alphacodin doc-drift # stale documentation alphacodin watch # auto-update on save alphacodin next # ranked next actions ```

Full reference: website/cli-reference.md.

Why not just grep?

Grep returns files. Alpha CodIn returns understanding:

• Cited answers — every claim links to the exact symbol and line that proves it.
• Graph-aware — agents see callers, callees, tests, and ownership, not just text matches.
• Continuously updated — `alphacodin watch` and git hooks keep the index honest as you type.
• Token-efficient — agents read one triage card instead of thirty files. The `savings` ledger measures exactly what each agent didn't have to read.

Architecture

Five subsystems, one continuously updated local index:

• `packages/core` — ingestion, parsing (30+ languages), the knowledge graph, health scoring.
• `packages/server` — FastAPI app + MCP server behind the API and dashboard.
• `packages/cli` — the `alphacodin` command line and agent integrations.
• `packages/ui` — shared React component library (dashboard + webviews).
• `packages/web` — the Next.js dashboard.

Configuration

```bash

repo-level

.alphacodin/config.yaml # wiki style, providers, MCP tools, filters

environment

ALPHACODIN_API_KEY= # required for non-loopback deployments ALPHACODIN_EMBEDDER=mock # gemini | openai | openrouter | ollama | edenai | mock ANTHROPIC_API_KEY= # or OPENAI_API_KEY / GEMINI_API_KEY

phone-home (off by default)

ALPHACODIN_CHECK_UPDATES=1 # opt in to update checks ```

Security

• Everything is local-first; the index and wiki live in `.alphacodin/` inside your repo.
• Docker deployments mount the repository read-only and default ports to loopback.
• Non-loopback API access requires `ALPHACODIN_API_KEY`.
• The container runs as a non-root user.
• Telemetry: none. The update check is off by default (`ALPHACODIN_CHECK_UPDATES=1` to enable).

Self-Hosting & CI

• website/self-hosting.md — full server deployments.
• ci/gitlab/alphacodin.gitlab-ci.yml — GitLab CI template.
• .github/workflows — GitHub Actions for wiki sync on PRs.

Contributing

```bash git clone https://github.com/DeejayAI/alphacodin.git cd alphacodin cp .env.example .env pip install -e ".[dev]" && npm install --cache .npmcache pytest tests/unit -q # python test suite npm run build --workspace packages/web # web build ```

Please read website/contributing.md first. PRs welcome.

License

AGPL-3.0 — see LICENSE for the full text.