> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codeant.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Code Review

> Run AI-powered agentic code reviews from the command line

The `codeant review` command runs an AI-powered code review using an agentic architecture. The agent analyzes your code changes, reads surrounding context from your codebase, and provides detailed suggestions with severity levels.

## Basic Usage

```bash theme={null}
# Review all changes (committed + uncommitted) — default
codeant review

# Review only uncommitted changes
codeant review --uncommitted

# Review only staged files
codeant review --staged

# Review only unpushed commits
codeant review --committed
```

## Options

### Review Scope

| Option                   | Description                                      |
| ------------------------ | ------------------------------------------------ |
| `--all`                  | Review committed + uncommitted changes (default) |
| `--committed`            | Review only unpushed commits                     |
| `--uncommitted`          | Review only uncommitted changes                  |
| `--staged`               | Review only staged files                         |
| `--last-commit`          | Review the last commit                           |
| `--last-n-commits <n>`   | Review the last n commits (max 5)                |
| `--base <branch>`        | Compare against a specific base branch           |
| `--base-commit <commit>` | Compare against a specific commit SHA            |

### Filtering & Thresholds

| Option                 | Description                                                                           |
| ---------------------- | ------------------------------------------------------------------------------------- |
| `--fail-on <level>`    | Fail threshold: `BLOCKER`, `CRITICAL`, `MAJOR`, `MINOR`, `INFO` (default: `CRITICAL`) |
| `--include <patterns>` | Comma-separated glob patterns to include files                                        |
| `--exclude <patterns>` | Comma-separated glob patterns to exclude files                                        |

### CI / Headless Mode

| Option       | Description                                                        |
| ------------ | ------------------------------------------------------------------ |
| `--headless` | Output clean JSON to stdout (disables spinners and interactive UI) |

Use `--headless` when running inside CI pipelines or AI agents. In this mode:

* All results are written to stdout as JSON
* Progress and status messages are written to stderr
* No interactive prompts are shown

```bash theme={null}
# Use in CI — parse JSON output with jq
codeant review --headless --all | jq '.suggestions[] | select(.severity == "CRITICAL")'
```

## How It Works

The review runs in a multi-phase pipeline:

### Phase 1: Per-File Analysis

Each changed file is analyzed independently and **in parallel**. For each file, the agent:

1. Receives the diff and full file content
2. Can use tools to read other files, search the codebase, and explore directory structures
3. Iterates through up to 5 conversation turns to gather context and form suggestions
4. Returns file-specific suggestions with severity labels

**Agent Tools Available:**

| Tool     | Description                                  |
| -------- | -------------------------------------------- |
| **Read** | Read file contents with optional line ranges |
| **Glob** | Find files matching glob patterns            |
| **Grep** | Search file contents with regex patterns     |
| **LS**   | List directory contents                      |

### Phase 2: Reflector

After all per-file analyses complete, the reflector phase:

1. Combines all per-file suggestions
2. Runs a final analysis pass to deduplicate, refine, and prioritize
3. Produces the final set of code suggestions

## Severity Levels

Each suggestion is assigned a severity based on its label:

| Label             | Severity |
| ----------------- | -------- |
| `security`        | CRITICAL |
| `bug`             | MAJOR    |
| `performance`     | MAJOR    |
| `maintainability` | MINOR    |
| `code quality`    | MINOR    |
| `best practice`   | MINOR    |

The `--fail-on` flag determines the exit code:

* `0` — No suggestions at or above the threshold
* `1` — Suggestions found at or above the threshold

## File Filtering

The review automatically excludes files that are unlikely to benefit from code review:

**Lock files:** `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `composer.lock`, `Gemfile.lock`, `Cargo.lock`, `poetry.lock`, `Pipfile.lock`, `go.sum`

**Binary/compiled:** `.exe`, `.dll`, `.so`, `.dylib`, `.bin`, `.o`, `.a`, `.class`, `.pyc`, `.wasm`, `.jar`, `.war`

**Media:** `.png`, `.jpg`, `.jpeg`, `.gif`, `.svg`, `.webp`, `.mp3`, `.mp4`, `.wav`, `.avi`, `.mov`

**Fonts:** `.woff`, `.woff2`, `.ttf`, `.eot`, `.otf`

**Archives:** `.zip`, `.tar`, `.gz`, `.bz2`, `.7z`, `.rar`

**Generated/minified:** `.min.js`, `.min.css`, `.map`, `.pb`

**Documents:** `.pdf`, `.doc`, `.docx`, `.xls`, `.xlsx`, `.ppt`, `.pptx`

**System:** `.DS_Store`, `Thumbs.db`

### Size Limits

* **Maximum file size:** 5,000 lines per file
* **Maximum files per review:** 10 unique files

Files exceeding these limits are skipped with a warning.

## Examples

```bash theme={null}
# Review all changes with default settings
codeant review

# Review against a specific branch
codeant review --base develop

# Review against a specific commit
codeant review --base-commit abc1234

# Review last 3 commits
codeant review --last-n-commits 3

# Only review TypeScript files, fail on MAJOR and above
codeant review --include '**/*.ts' --exclude '**/*.test.ts' --fail-on MAJOR

# Review staged files only
codeant review --staged

# Review uncommitted changes, include MINOR severity
codeant review --uncommitted --fail-on MINOR
```

## Terminal UI

The review displays a live progress indicator in your terminal:

```
⠋ Analyzing... (12s)
  Step 2/4: Reviewing src/auth.ts (turn 3/5)
```

Progress steps:

1. **Init** — Initializing review session
2. **Fetch** — Gathering diffs and file contents
3. **Analyze** — Per-file agent analysis (parallel)
4. **Reflect** — Final reflector pass

When complete, suggestions are displayed with color-coded severity and file locations.