CodeSpy
An open-source AI reviewer that catches bugs, improves code quality, and integrates directly into your PR workflow, without sacrificing control or security.
Table of Contents
Why CodeSpy?
Most AI code reviewers are:
- ❌ Black boxes
- ❌ SaaS-only
- ❌ Opaque about reasoning
- ❌ Risky for sensitive codebases
CodeSpy is different:
- 🔍 Transparent reasoning
- 🔐 Self-hostable
- 🔄 Native PR integration
- 🧩 Extensible architecture
- 📦 100% open-source
Built for engineering teams that care about correctness, security, and control.
Features
- 🔒 Security Analysis — Detects common vulnerabilities (injection, auth issues, data exposure) with CWE references
- 🐛 Bug Detection — Identifies logic errors, null references, resource leaks, edge cases
- 📝 Documentation Review — Checks for missing docstrings, outdated comments, incomplete docs
- 🔍 Intelligent Scope Detection — Automatically identifies code scopes (frontend, backend, infra, microservice in monorepo, etc.)
- 🧠 Cross-Review Memory — Agents learn patterns, constants, and domain knowledge from past reviews of the same codebase
- 💰 Cost Tracking — Track LLM calls, tokens, and costs per review
- 🤖 Model Agnostic — Works with OpenAI, AWS Bedrock, Anthropic, Gemini, Ollama, and more via LiteLLM
- 🐳 Docker Ready — Run locally or in the cloud with Docker
GitHub & GitLab — Works with both platforms, auto-detects from URL
- 🖥️ Local Reviews — Review local git changes without GitHub/GitLab — diff against any branch, ref, or review uncommitted work
- 🧩 MCP Server — IDE integration via Model Context Protocol — trigger reviews from AI coding assistants without leaving your editor
- 🔌 GitHub Action — One-line integration for automatic PR reviews
Installation
Using pip
pip install codespy-ai
Using Homebrew (macOS/Linux)
brew tap khezen/codespy
brew install codespy
Using Docker
# Pull the pre-built image from GitHub Container Registry
docker pull ghcr.io/khezen/codespy:latest
# Or build locally
docker build -t codespy .
Using Poetry (for development)
# Clone the repository
git clone https://github.com/khezen/codespy.git
cd codespy
# Install dependencies
poetry install
# Or install only production dependencies
poetry install --only main
Quick Start
Get up and running in 30 seconds:
# 1. Set your Git token (or let codespy auto-discover from gh/glab CLI)
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx # For GitHub
# OR
export GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx # For GitLab
# 2. Set your LLM provider (example with Anthropic)
export DEFAULT_MODEL=anthropic/claude-opus-4-6
export ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxx
# 3. Review a PR or MR!
codespy review https://github.com/owner/repo/pull/123
# OR
codespy review https://gitlab.com/group/project/-/merge_requests/123
codespy auto-discovers credentials from standard locations (~/.aws/credentials, gh auth token, glab auth token, etc.) - see Configuration for details.
Documentation
| Guide | Contents |
|---|---|
| Usage | CLI commands, Docker, GitHub Action, MCP server, output formats |
| Configuration | Environment variables, YAML config, model strategy, per-signature settings |
| Architecture | Pipeline design, DSPy signatures, supported languages |
| Memory System | Hippocampus episodic memory for cross-review knowledge |
| Development | Setup, build, test, lint |
Contributors
- @khezen
- @pranavsriram8
License
MIT
1 maintainer
Metadata
1 maintainer
Release files for codespy-ai 1.0.14
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| codespy_ai-1.0.14.tar.gz | 161.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| codespy_ai-1.0.14-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 381.9 kB
Release files / codespy_ai-1.0.14.tar.gz
| Download URL | codespy_ai-1.0.14.tar.gz |
|---|---|
| Size | 161.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2363834aaab74bb460f62d29ab8203f1810ce0f1516046ebab555e21bc71f03d
|
|
BLAKE2b-256 checksum How to use checksums |
eea29fd45a4fbfb18ebaf045dec490583aa57a1ea8cee0519851ee86f0ed0dd9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / codespy_ai-1.0.14-py3-none-any.whl
| Download URL | codespy_ai-1.0.14-py3-none-any.whl |
|---|---|
| Size | 220.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
222c3b8d00ec5d48cb402dd45633b1faa4c7a3b760d97cb853bcfa06a2f32143
|
|
BLAKE2b-256 checksum How to use checksums |
1eab4f787ee35815761e0829c82b2458bf79e44befe3d07bd509a12e62814ce3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
