Metadata-Version: 2.4
Name: alphacodin
Version: 0.54.1
Summary: The codebase intelligence layer for your AI coding agent — dependency graph, git history, dead code, decisions, and code health, exposed over MCP
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/DeejayAI/alphacodin
Project-URL: Repository, https://github.com/DeejayAI/alphacodin
Project-URL: Issues, https://github.com/DeejayAI/alphacodin/issues
Project-URL: Documentation, https://github.com/DeejayAI/alphacodin/blob/main/docs/start/USER_GUIDE.md
Keywords: documentation,codebase,wiki,llm,ai,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Environment :: Console
Classifier: Framework :: FastAPI
Classifier: Topic :: Software Development :: Documentation
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx<1,>=0.27
Requires-Dist: tree-sitter<1,>=0.25
Requires-Dist: tree-sitter-python<1,>=0.23
Requires-Dist: tree-sitter-typescript<1,>=0.23
Requires-Dist: tree-sitter-javascript<1,>=0.23
Requires-Dist: tree-sitter-go<1,>=0.23
Requires-Dist: tree-sitter-rust<1,>=0.23
Requires-Dist: tree-sitter-java<1,>=0.23
Requires-Dist: tree-sitter-cpp<1,>=0.23
Requires-Dist: tree-sitter-dart<1,>=0.1
Requires-Dist: tree-sitter-kotlin<2,>=1
Requires-Dist: tree-sitter-ruby<1,>=0.23
Requires-Dist: tree-sitter-c-sharp<1,>=0.23
Requires-Dist: tree-sitter-swift>=0.0.1
Requires-Dist: tree-sitter-scala<1,>=0.23
Requires-Dist: tree-sitter-php<1,>=0.23
Requires-Dist: tree-sitter-pascal<1,>=0.11
Requires-Dist: tree-sitter-language-pack<2,>=1.14
Requires-Dist: tree-sitter-luau<2,>=1.2
Requires-Dist: tree-sitter-bash<1,>=0.23
Requires-Dist: tree-sitter-gdscript<7,>=6.1
Requires-Dist: tree-sitter-vb-dotnet<1,>=0.3
Requires-Dist: tree-sitter-elixir<1,>=0.3.5
Requires-Dist: tree-sitter-fsharp<1,>=0.3.11
Requires-Dist: tree-sitter-objc<4,>=3.0.2
Requires-Dist: tree-sitter-svelte<2,>=1
Requires-Dist: tree-sitter-html<1,>=0.23
Requires-Dist: sqlglot<28,>=26
Requires-Dist: networkx<4,>=3.3
Requires-Dist: scipy<2,>=1.11
Requires-Dist: jinja2<4,>=3.1
Requires-Dist: pathspec<1,>=0.12
Requires-Dist: structlog<25,>=24
Requires-Dist: sqlalchemy[asyncio]<3,>=2.0
Requires-Dist: aiosqlite<1,>=0.20
Requires-Dist: alembic<2,>=1.13
Requires-Dist: pydantic<3,>=2.8
Requires-Dist: tenacity<10,>=9
Requires-Dist: gitpython<4,>=3.1
Requires-Dist: pyyaml<7,>=6.0
Requires-Dist: lancedb<1,>=0.12
Requires-Dist: click<8.2,>=8.1
Requires-Dist: rich<14,>=13
Requires-Dist: watchdog<5,>=4
Requires-Dist: fastapi<1,>=0.115
Requires-Dist: uvicorn[standard]<1,>=0.32
Requires-Dist: mcp<2,>=1.0
Requires-Dist: apscheduler<4,>=3.10
Requires-Dist: cryptography<51,>=50.0.0
Requires-Dist: anthropic<1,>=0.40
Requires-Dist: openai<3,>=1.50
Requires-Dist: google-genai<2,>=1.0
Requires-Dist: litellm<2,>=1.84.0
Provides-Extra: postgres
Requires-Dist: pgvector<1,>=0.3; extra == "postgres"
Requires-Dist: asyncpg<1,>=0.29; extra == "postgres"
Provides-Extra: graph-extra
Requires-Dist: graspologic<4,>=3.4; extra == "graph-extra"
Provides-Extra: dev
Requires-Dist: pytest<9,>=8; extra == "dev"
Requires-Dist: pytest-asyncio<1,>=0.23; extra == "dev"
Requires-Dist: pytest-snapshot<1,>=0.9; extra == "dev"
Requires-Dist: respx<1,>=0.21; extra == "dev"
Requires-Dist: time-machine<3,>=2.14; extra == "dev"
Requires-Dist: ruff<1,>=0.6; extra == "dev"
Requires-Dist: mypy<2,>=1.11; extra == "dev"
Requires-Dist: types-networkx<4,>=3.3; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Dynamic: license-file

# Alpha CodIn

<p align="center">
  <a href="https://www.alphacodin.dev"><img src=".github/assets/banner-v2.png" alt="Alpha CodIn — evidence-backed codebase intelligence" width="100%" /></a>
</p>

<p align="center">
  <strong>The codebase intelligence layer for developers and AI coding agents.</strong><br/>
  A continuously updated local index of your code, git history, tests, and decisions —<br/>
  with cited answers, change-impact analysis, and code-health improvements across
  your editor, your pull requests, and your dashboard.
</p>

<p align="center">
  <a href="#quick-start"><img src="https://img.shields.io/badge/install-pip%20%7C%20uvx%20%7C%20docker-DC2626?style=flat-square" alt="Install" /></a>
  <a href="https://pypi.org/project/alphacodin/"><img src="https://img.shields.io/pypi/v/alphacodin?color=DC2626&style=flat-square" alt="PyPI" /></a>
  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.12%2B-DC2626?style=flat-square" alt="Python" /></a>
  <a href="https://github.com/DeejayAI/alphacodin/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0-DC2626?style=flat-square" alt="License" /></a>
</p>

---

## 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](website/claude-code-plugin.md) |
| **Codex CLI** | MCP config + AGENTS.md guidance | [website/codex.md](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](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](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

![Product map](.github/assets/product-map-dark.png)

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](website/self-hosting.md) — full server deployments.
- [ci/gitlab/alphacodin.gitlab-ci.yml](ci/gitlab/alphacodin.gitlab-ci.yml) — GitLab CI template.
- [.github/workflows](.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](website/contributing.md) first. PRs welcome.

## License

[AGPL-3.0](LICENSE) — see [LICENSE](LICENSE) for the full text.
