Kodus Cheat Sheet

Overview

Kodus is an open-source AI code review tool that automates pull request analysis. It integrates with GitHub, GitLab, and Bitbucket to automatically review code changes, identify bugs, security vulnerabilities, performance issues, and code quality problems. Kodus uses large language models to understand code context and provide actionable, human-readable feedback directly on pull requests.

Kodus goes beyond simple linting by understanding the semantic meaning of code changes. It can detect logic errors, suggest better patterns, identify missing error handling, flag potential security issues, and ensure consistency with project conventions. The tool is configurable through a YAML file that lets teams customize review rules, severity levels, and which types of feedback to provide.

Installation

GitHub App

1. Visit https://github.com/apps/kodus-ai (or self-host)
2. Click "Install" and select your repositories
3. Configure which repositories to monitor
4. Kodus will automatically review new pull requests

Self-Hosted (Docker)

# Clone the repository
git clone https://github.com/kodus-ai/kodus.git
cd kodus

# Copy environment configuration
cp .env.example .env

# Configure environment variables
nano .env
# Set API keys, database URL, and GitHub/GitLab tokens

# Start with Docker Compose
docker compose up -d

# Access the dashboard at http://localhost:3000

Docker Compose

version: "3.8"
services:
  kodus:
    image: kodus/kodus:latest
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://kodus:password@db:5432/kodus
      GITHUB_APP_ID: "${GITHUB_APP_ID}"
      GITHUB_PRIVATE_KEY: "${GITHUB_PRIVATE_KEY}"
      GITHUB_WEBHOOK_SECRET: "${GITHUB_WEBHOOK_SECRET}"
      LLM_PROVIDER: "anthropic"
      LLM_API_KEY: "${ANTHROPIC_API_KEY}"
      LLM_MODEL: "claude-sonnet-4-20250514"
    depends_on:
      - db
      - redis
  db:
    image: postgres:16
    environment:
      POSTGRES_DB: kodus
      POSTGRES_USER: kodus
      POSTGRES_PASSWORD: password
    volumes:
      - pgdata:/var/lib/postgresql/data
  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
volumes:
  pgdata:
  redis_data:

Core Features

Automatic PR Review

# When a PR is opened or updated, Kodus:
1. Fetches the diff and changed files
2. Analyzes code context (imports, dependencies, project structure)
3. Reviews each changed file for issues
4. Posts inline comments on specific lines
5. Provides a summary review with overall assessment
6. Assigns severity levels (critical, warning, suggestion, nitpick)

Review Categories

Category	What It Checks
Bugs	Logic errors, null references, race conditions
Security	SQL injection, XSS, hardcoded secrets, insecure patterns
Performance	N+1 queries, unnecessary iterations, memory leaks
Error Handling	Missing try/catch, unhandled promises, silent failures
Code Quality	Dead code, complexity, naming conventions
Best Practices	Framework-specific patterns, idiomatic code
Documentation	Missing comments, unclear function names
Testing	Missing test coverage, fragile tests
Accessibility	ARIA labels, semantic HTML, keyboard navigation

Comment Format

# Kodus posts comments like:

🔴 [Critical] SQL Injection Vulnerability
Line 42: `query = f"SELECT * FROM users WHERE id = {user_id}"`

This query is vulnerable to SQL injection. Use parameterized queries:
```python
query = "SELECT * FROM users WHERE id = %s"
cursor.execute(query, (user_id,))

🟡 [Warning] Unhandled Promise Rejection Line 78: The async function does not have error handling.

Consider wrapping in try/catch:

try {
  const data = await fetchUser(id);
} catch (error) {
  logger.error('Failed to fetch user', { id, error });
  throw new AppError('User not found', 404);
}

🔵 [Suggestion] Consider using Optional Chaining Line 15: user && user.address && user.address.city

This can be simplified to: user?.address?.city

## Configuration

### Project Configuration (.kodus.yml)

```yaml
# .kodus.yml — place in repository root

# General settings
language: auto  # auto-detect or specify: javascript, python, go, etc.
review_on: pull_request  # pull_request, push, or both

# Review scope
include:
  - "src/**"
  - "lib/**"
  - "app/**"
exclude:
  - "**/*.test.*"
  - "**/*.spec.*"
  - "**/migrations/**"
  - "**/generated/**"
  - "vendor/**"
  - "node_modules/**"

# Review categories to enable/disable
categories:
  bugs: true
  security: true
  performance: true
  error_handling: true
  code_quality: true
  best_practices: true
  documentation: false
  testing: true
  accessibility: true

# Severity settings
severity:
  minimum: suggestion  # critical, warning, suggestion, nitpick
  block_on: critical   # Block merge on this severity or above
  max_comments: 20     # Maximum comments per review

# Custom rules
rules:
  - name: no-console-log
    description: "Disallow console.log in production code"
    severity: warning
    pattern: "console\\.log"
    exclude: ["**/*.test.*", "**/debug/**"]

  - name: require-error-class
    description: "Use custom error classes instead of generic Error"
    severity: suggestion
    pattern: "throw new Error\\("
    message: "Consider using a specific error class (e.g., ValidationError, NotFoundError)"

# Framework-specific rules
frameworks:
  react:
    check_hooks_rules: true
    check_accessibility: true
    prefer_function_components: true
  nextjs:
    check_server_components: true
    check_metadata: true

# LLM settings (self-hosted only)
llm:
  provider: anthropic
  model: claude-sonnet-4-20250514
  max_tokens: 4096
  temperature: 0.1

Environment Variables

# GitHub App configuration
GITHUB_APP_ID=123456
GITHUB_PRIVATE_KEY_PATH=/path/to/private-key.pem
GITHUB_WEBHOOK_SECRET=your-webhook-secret

# GitLab configuration
GITLAB_TOKEN=glpat-xxxxx
GITLAB_WEBHOOK_SECRET=your-secret

# LLM Provider
LLM_PROVIDER=anthropic  # anthropic, openai, azure, local
LLM_API_KEY=sk-ant-...
LLM_MODEL=claude-sonnet-4-20250514

# Database
DATABASE_URL=postgres://user:pass@localhost:5432/kodus

# Redis (for job queuing)
REDIS_URL=redis://localhost:6379

# Optional
LOG_LEVEL=info
MAX_CONCURRENT_REVIEWS=5
REVIEW_TIMEOUT=300

Advanced Usage

Custom Review Prompts

# .kodus.yml
custom_prompts:
  pre_review: |
    This project follows these conventions:
    - We use the Repository pattern for data access
    - All API responses follow the JSON:API specification
    - Error codes should map to HTTP status codes
    - We prefer composition over inheritance

  security_focus: |
    Pay special attention to:
    - Authentication and authorization checks
    - Input validation on all API endpoints
    - Rate limiting configuration
    - CORS settings

API Integration

# Trigger a review manually
curl -X POST "https://your-kodus-instance.com/api/v1/reviews" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "repository": "org/repo",
    "pull_request": 42,
    "force": true
  }'

# Get review results
curl "https://your-kodus-instance.com/api/v1/reviews/REVIEW_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"

# List reviews for a repository
curl "https://your-kodus-instance.com/api/v1/repos/org/repo/reviews?limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Get review metrics
curl "https://your-kodus-instance.com/api/v1/repos/org/repo/metrics" \
  -H "Authorization: Bearer YOUR_TOKEN"

CI/CD Integration

# GitHub Actions
name: Kodus Code Review
on:
  pull_request:
    types: [opened, synchronize]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: kodus-ai/review-action@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          kodus-api-key: ${{ secrets.KODUS_API_KEY }}
          config-path: .kodus.yml

Team Dashboard

# Dashboard features (self-hosted):
- Review history per repository
- Common issue trends over time
- Top categories of findings
- Team metrics (issues found, resolved, ignored)
- Per-developer statistics
- Resolution rate tracking
- Weekly/monthly reports

Webhooks and Notifications

# .kodus.yml
notifications:
  slack:
    webhook_url: "https://hooks.slack.com/services/..."
    on: [critical, warning]
    channel: "#code-reviews"

  email:
    recipients: ["team-lead@example.com"]
    on: [critical]
    digest: daily

Interaction with Reviews

# Developers can interact with Kodus comments:

# Dismiss a suggestion
Reply: "@kodus dismiss - This is intentional for backward compatibility"

# Ask for clarification
Reply: "@kodus explain - Why is this pattern problematic?"

# Request alternative
Reply: "@kodus suggest - What would be a better approach here?"

# Re-review after changes
Comment on PR: "@kodus review"

# Ignore a rule for this PR
Comment on PR: "@kodus ignore no-console-log"

Troubleshooting

Issue	Solution
Reviews not triggering	Check webhook configuration; verify app has repository access
Too many comments	Increase severity.minimum to warning; reduce max_comments
Irrelevant suggestions	Add paths to exclude list; fine-tune custom_prompts for project context
Reviews timing out	Reduce PR size; increase REVIEW_TIMEOUT; check LLM provider status
GitHub rate limits	Use a GitHub App (higher limits) instead of personal tokens
Duplicate comments	Check webhook isn’t firing multiple times; verify deduplication settings
Self-hosted not starting	Check Docker logs; verify database and Redis connections
LLM API errors	Verify API key; check provider status page; ensure model is available
Comments on wrong lines	Ensure git fetch depth is sufficient in CI; check diff accuracy