CodeSpy logo

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?
Features
Installation
Quick Start
Documentation
Contributors
License

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

Metadata

Release files for codespy-ai 1.0.15

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for codespy-ai 1.0.15
File	Size	Uploaded
codespy_ai-1.0.15.tar.gz	157.2 kB	Sep 1, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for codespy-ai 1.0.15
File	Interpreter	ABI	Platform	Reset
codespy_ai-1.0.15-py3-none-any.whl 216.0 kB Sep 1, 2026	Python 3	none	any	Details

Total release size: 373.2 kB

Release files / codespy_ai-1.0.15.tar.gz

Download URL	codespy_ai-1.0.15.tar.gz
Size	157.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`7ca210be6098ceac71358b4174c069b5745faa589f486b64b17e3171e34cde5b`
BLAKE2b-256 checksum How to use checksums	`46862731131e033892e1c62231de90e16d1dea7ef020d8b683a6c9baadfef4c9`
Upload date	Sep 1, 2026
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.15-py3-none-any.whl

Download URL	codespy_ai-1.0.15-py3-none-any.whl
Size	216.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`c23727beaafb43853bcea019f167daf2ecf6b13e0f6f1909567b4dad20c9adf5`
BLAKE2b-256 checksum How to use checksums	`4f1695d8183d06196e3f7748342f037907f60645e5e3ecc7ea254e8cb81e8e6a`
Upload date	Sep 1, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`