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.

---

Packages

Alpha CodIn ships as one PyPI package and a set of npm packages.

Python (PyPI)

Package	Version	Description	Install
alphacodin	0.55.0	CLI + core + server — everything you need	pip install alphacodin

The single PyPI package bundles all three Python layers (`alphacodin-core`, `alphacodin-cli`, `alphacodin-server`). Extras: `pip install "alphacodin[all]"` for server + UI dependencies.

JavaScript / TypeScript (npm — private, `@ltm-blueverse` org)

Package	Version	Description	Access
@ltm-blueverse/types	0.0.2	Shared TypeScript types	restricted
@ltm-blueverse/api-client	0.2.0	Typed API client for the server	restricted
@ltm-blueverse/ui	0.2.0	React component library (dashboard + webviews)	restricted

npm packages are private (restricted access). Installing them requires an npm access token: `npm_xxxxxx`. See npm installation.

Install on every platform

Platform	Command	Detailed guide
macOS / Linux — pip	`pip install alphacodin`	PyPI install guide
macOS / Linux — uv	`uv tool install alphacodin`	PyPI install guide
macOS / Linux — uvx (no install)	`uvx alphacodin --help`	PyPI install guide
Windows — pip	`py -m pip install alphacodin`	PyPI install guide
Windows — pipx	`pipx install alphacodin`	PyPI install guide
Docker — any OS	`docker run alphacodin`	Docker deployment
From source	`pip install -e ".[all]"`	Contributing

---

Installation

Python (PyPI)

Requirements: Python 3.12+ and `git`.

```bash

pip (macOS, Linux, Windows)

pip install alphacodin

pipx (isolated CLI install)

pipx install alphacodin

uv tool (fast, isolated)

uv tool install alphacodin

uvx — run without installing

uvx alphacodin --help

Windows via the py launcher

py -m pip install alphacodin ```

Verify:

```bash alphacodin --version # alphacodin, version 0.55.0 alphacodin doctor # environment health check ```

npm packages

The `@ltm-blueverse` packages are restricted: org members install them with an npm access token (`npm_xxxxxx`).

```bash

1. Get a token from npmjs.com → Access Tokens (or ask the org owner).

2. Authenticate — either via environment:

export NPM_TOKEN=npm_xxxxxx

...or write it to ~/.npmrc:

echo "//registry.npmjs.org/:_authToken=npm_xxxxxx" >> ~/.npmrc

3. Install

npm install @ltm-blueverse/types @ltm-blueverse/api-client @ltm-blueverse/ui ```

For CI, set the token as the `NPM_TOKEN` secret and use `.npmrc`:

```ini @ltm-blueverse:registry=https://registry.npmjs.org/ //registry.npmjs.org/:_authToken=npm_xxxxxx ```

The packages ship TypeScript source (`main` → `./src/index.ts`); consume them through a bundler or a TypeScript compiler, the way the monorepo does.

---

Quick Start

```bash

1. Index a repository (no API key needed — structural wiki)

cd /path/to/your-repo alphacodin init

2. (optional) Add prose pages with an LLM

export ANTHROPIC_API_KEY=sk-ant-... # or OPENAI_API_KEY / GEMINI_API_KEY alphacodin generate

3. Open the dashboard

alphacodin serve

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

→ http://localhost:7337 (API)

4. Wire up your AI agents

alphacodin agents add --target auto ```

Docker Deployment

Run the full local server + Web UI in a single container. The image bundles the FastAPI backend, the MCP server, and the Next.js dashboard.

```bash

Build

git clone https://github.com/DeejayAI/alphacodin.git cd alphacodin docker build -t alphacodin -f docker/Dockerfile .

Index a repo on the host first

alphacodin init /path/to/repo

Run — repo mounted read-only, index written to the /data volume

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 # optional — omit to clone remotes into a volume instead export ALPHACODIN_API_KEY=change-me export ALPHACODIN_GIT_TOKEN_GITHUB=ghp_xxxx # for private clone-from-URL export ALPHACODIN_CONFLUENCE_URL=https://yourorg.atlassian.net export ALPHACODIN_CONFLUENCE_EMAIL=you@company.com export ALPHACODIN_CONFLUENCE_TOKEN=ATATT... export ALPHACODIN_CONFLUENCE_SPACE=DOC export ALPHACODIN_JIRA_URL=https://yourorg.atlassian.net export ALPHACODIN_JIRA_EMAIL=you@company.com export ALPHACODIN_JIRA_TOKEN=ATATT... docker compose -f docker/docker-compose.yml up ```

Without `REPO_PATH`, server-side `clone_from` checkouts land in a writable `repos-clones` volume; the Confluence and JIRA sections under Settings drive wiki sync and issue linking once these variables are set.

Service	URL	Notes
Web UI	http://localhost:3000	Next.js dashboard
API	http://localhost:7337	FastAPI + MCP over HTTP

An MCP-over-stdio image for CI and MCP hosts 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	Notes
Claude Code	MCP server registration + `CLAUDE.md` instructions + hooks	guide
Codex CLI	MCP config + `AGENTS.md` guidance	guide
Cursor	`.cursor/mcp.json` + project rules	—
VS Code / Copilot	`.vscode/mcp.json` + the `alphacodin.alphacodin` extension	—
OpenCode	Native config + plugin	guide
Hermes	MCP transport registration	—

```bash

explicit targets

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

write to user-level config instead of repo-local

alphacodin agents add --target cursor --scope user ```

MCP Server

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

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

Default tools (10) — every MCP client gets these:

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 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.

---

Architecture

Five subsystems, one continuously updated local index:

Package	Role
`packages/core`	Ingestion, parsing (30+ languages), knowledge graph, health scoring
`packages/server`	FastAPI app + MCP server behind the API and dashboard
`packages/cli`	The `alphacodin` CLI 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

OpenAI-compatible gateway (custom endpoint)

Point Alpha CodIn at any OpenAI-shaped endpoint — an LLM gateway, LiteLLM, vLLM, or a corporate proxy — with your own key and model:

export OPENAI_COMPATIBLE_BASE_URL=https://tokenhub.example.com/v1
export OPENAI_COMPATIBLE_API_KEY=ltmaigateway_xxxx   # optional for open proxies
export ALPHACODIN_PROVIDER=openai_compatible
export ALPHACODIN_MODEL=auto                         # any model your gateway serves

In the Web UI: Settings → Provider → OpenAI-compatible endpoint — set the Base URL, paste an API key, pick or type a model, then Test. Chat, generation, and the model defaults all ride the gateway.

clone-from-URL (private repositories)

ALPHACODIN_REPOS_ROOT=/repos # where server-cloned checkouts land ALPHACODIN_GIT_TOKEN_GITHUB=ghp_xxxx # applied only to github.com remotes ALPHACODIN_GIT_TOKEN_GITLAB=glpat-xxxx # applied only to gitlab.com remotes ALPHACODIN_GIT_CREDENTIAL_=user:token # named credential for credential_ref

Confluence wiki sync

ALPHACODIN_CONFLUENCE_URL=https://yourorg.atlassian.net ALPHACODIN_CONFLUENCE_EMAIL=you@company.com ALPHACODIN_CONFLUENCE_TOKEN=ATATT... # Atlassian API token ALPHACODIN_CONFLUENCE_SPACE=DOC

JIRA issue linking (read-only)

ALPHACODIN_JIRA_URL=https://yourorg.atlassian.net ALPHACODIN_JIRA_EMAIL=you@company.com ALPHACODIN_JIRA_TOKEN=ATATT... ALPHACODIN_JIRA_PROJECT=ABC ```

Clone from a URL (GitHub / GitLab, public or private)

Register a remote and the server clones it into ALPHACODIN_REPOS_ROOT before indexing — no manual git clone step:

```bash

public

curl -X POST http://localhost:7337/api/repos -H "Authorization: Bearer $ALPHACODIN_API_KEY"
-H 'Content-Type: application/json'
-d '{"name":"mini","clone_from":"https://github.com/owner/repo.git"}'

private (token read from ALPHACODIN_GIT_TOKEN_GITHUB on the server)

curl -X POST http://localhost:7337/api/repos -H "Authorization: Bearer $ALPHACODIN_API_KEY"
-H 'Content-Type: application/json'
-d '{"name":"private","clone_from":"git@github.com:owner/private.git","credential_ref":"work"}' ```

SSH remotes (git@host:owner/repo) are normalized to HTTPS. Tokens reach git through a one-shot credential.helper — never in the clone URL, so they cannot leak through git remote -v, logs, or error output. Re-registering the same remote reuses the existing checkout.

Confluence wiki sync & JIRA

Under Settings → Confluence / JIRA. Confluence pushes the generated wiki into a space: Test connection, Dry run (shows the create/update/skip/archive plan), then Sync now. Pages carry an alphacodin:<page_id> label plus a content hash, so re-syncs are idempotent and unchanged pages are skipped rather than version-churned.

JIRA is read-only: it resolves issue keys (ABC-123) to live title/status for link enrichment and can scan the last 500 commits for referenced keys. Alpha CodIn never creates or transitions issues.

Security

• 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 pytest tests/unit -q # python 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.