---

What It Does

codereview sends your code to an LLM and returns a structured, color-coded review directly in your terminal — with severity ratings, line references, and concrete fix suggestions.

No browser. No PR required. No waiting for teammates. Just:

codereview app.py

Catching real security vulnerabilities — scored 2/10

Reviewing its own source code — scored 9/10

---

Why

• Solo developers — get a second pair of eyes without waiting for anyone
• Pre-commit check — catch bugs before they reach the PR
• Learning tool — understand why code is problematic, not just that it is
• CI integration — add to your pipeline for automated review gates
• Free — works with Groq (free tier, no credit card) or fully offline with Ollama

---

What It Catches

Severity	What it finds	Example
🔴 Critical	Security vulnerabilities, data loss, crashes	SQL injection, eval() on user input, hardcoded secrets
🟡 Warning	Bugs, missing error handling, race conditions	Division by zero, unhandled exceptions, resource leaks
🔵 Info	Performance improvements, better patterns	Unnecessary allocations, missing caching, N+1 queries
⚪ Style	Naming, formatting, documentation	Missing docstrings, inconsistent naming, dead code

---

Install

From source (recommended)

git clone https://github.com/jaydendancer12/ai-code-review.git
cd ai-code-review
./install.sh

Or manually:

git clone https://github.com/jaydendancer12/ai-code-review.git
cd ai-code-review
pip install -e .

All dependencies (rich, requests) install automatically. Nothing else to configure.

---

Quick Start (free, 60 seconds)

codereview needs an LLM to analyze your code. The fastest free option is Groq — no credit card, no trial, just free.

Step 1 — Get a free API key

1. Go to console.groq.com
2. Sign up with Google or GitHub (takes 30 seconds)
3. Click API Keys then Create API Key
4. Copy the key (starts with gsk_)

Step 2 — Set your key

export GROQ_API_KEY="gsk_your_key_here"

To make it permanent (so you don't have to set it every terminal session):

# For zsh (default on Mac)
echo 'export GROQ_API_KEY="gsk_your_key_here"' >> ~/.zshrc
source ~/.zshrc

# For bash (default on Linux)
echo 'export GROQ_API_KEY="gsk_your_key_here"' >> ~/.bashrc
source ~/.bashrc

Step 3 — Initialize

codereview --init groq

Step 4 — Review code

codereview yourfile.py

That's it. You're running AI code reviews.

First time running? Just type codereview with no arguments and it will walk you through the entire setup.

---

Usage

Review a file

codereview app.py

Review multiple files

codereview src/auth.py src/db.py src/api.py

Review staged git changes (pre-commit)

git add .
codereview --staged

Review the last N commits

codereview --last 3

Review diff between branches

codereview --diff origin/main

Pipe code from stdin

cat suspicious_code.py | codereview --stdin

Use a specific model

codereview app.py --model gpt-4

Use a specific provider for one review

codereview app.py --provider ollama

Show setup instructions

codereview --setup

---

Providers

codereview works with any OpenAI-compatible API. Pick what works for you:

⚡ Groq (recommended — free, fast)

export GROQ_API_KEY="gsk_your_key_here"
codereview --init groq

• Cost: Free tier, no credit card required
• Speed: Fastest inference available
• Model: Llama 3.3 70B
• Get a key: console.groq.com

🏠 Ollama (free, fully offline)

# 1. Install Ollama
# Mac: Download from https://ollama.com
# Linux: curl -fsSL https://ollama.com/install.sh | sh

# 2. Pull a model
ollama pull llama3

# 3. Start the server
ollama serve

# 4. Initialize (no API key needed)
codereview --init ollama

• Cost: Free forever
• Speed: Depends on your hardware
• Privacy: Code never leaves your machine
• Model: Any model Ollama supports

🧠 OpenAI

export OPENAI_API_KEY="sk-..."
codereview --init openai

• Cost: Pay per token
• Model: GPT-3.5 Turbo (default), GPT-4 with --model gpt-4
• Get a key: platform.openai.com

🔮 Anthropic

export ANTHROPIC_API_KEY="sk-ant-..."
codereview --init anthropic

• Cost: Pay per token
• Model: Claude 3 Haiku (default)
• Get a key: console.anthropic.com

---

Configuration

Config is stored at ~/.codereview/config.json:

{
  "provider": "groq",
  "model": "llama-3.3-70b-versatile",
  "base_url": "https://api.groq.com/openai/v1",
  "max_tokens": 2048,
  "temperature": 0.2
}

API keys are never stored in the config file. They are read from environment variables only.

Override anything via environment variables

export CODEREVIEW_API_KEY="any-key"     # Universal override
export CODEREVIEW_MODEL="gpt-4"         # Override model

Override via CLI flags

codereview app.py --model gpt-4 --provider openai

---

How It Works

Your Code  -->  codereview CLI  -->  LLM API  -->  Structured Terminal Output
(file/diff)     (prompt builder)    (any provider)  (color-coded findings)

1. Input — codereview reads your file, git diff, staged changes, or stdin
2. Prompt — Constructs a focused review prompt with strict rules to prevent hallucinated issues
3. LLM — Sends to any OpenAI-compatible API (Groq, OpenAI, Anthropic, Ollama)
4. Parse — Extracts structured JSON from the LLM response
5. Display — Renders color-coded, severity-sorted findings in your terminal

What makes this different from ChatGPT

• Structured output — Severity ratings, file references, concrete suggestions
• No hallucinations — Prompt engineering ensures the LLM only flags issues it can see in your code
• Works on diffs — Review only what changed, not the entire codebase
• One command — No copy-pasting into a browser
• Offline capable — Run with Ollama, your code never leaves your machine
• Free — No subscription required

---

Examples

Security audit on a suspicious file

$ codereview api/auth.py

Score: 3/10

🔴 CRITICAL — Hardcoded JWT secret
   Secret key is hardcoded on line 12.
   Suggestion: Use environment variable: os.environ["JWT_SECRET"]

🔴 CRITICAL — No password hashing
   Passwords stored in plaintext on line 34.
   Suggestion: Use bcrypt: bcrypt.hashpw(password, bcrypt.gensalt())