Hodor

Agentic code reviewer for GitHub PRs, GitLab MRs, and local diffs. Powered by the pi-coding-agent SDK.

Hodor runs as a stateful agent with tools (bash, grep, read, git diff) to autonomously analyze code changes, find bugs, and post structured reviews.

Install

# Just run it (zero install, always latest)
npx @mrkaran/hodor <PR_URL>

# Or install globally
npm install -g @mrkaran/hodor

Docker images are also available at ghcr.io/mr-karan/hodor:latest for CI environments.

Setup

# Set an API key for your LLM provider
export ANTHROPIC_API_KEY=sk-...   # Anthropic (default)
export OPENAI_API_KEY=sk-...      # OpenAI
export AWS_PROFILE=default        # AWS Bedrock (no API key needed)

# For posting reviews as comments
gh auth login                     # GitHub
glab auth login                   # GitLab

Usage

# Review a GitHub PR
npx @mrkaran/hodor https://github.com/owner/repo/pull/123

# Review a GitLab MR (including self-hosted)
npx @mrkaran/hodor https://gitlab.example.com/org/project/-/merge_requests/42

# Post the review as a PR/MR comment
npx @mrkaran/hodor <PR_URL> --post

# Use a different model
npx @mrkaran/hodor <PR_URL> --model openai/gpt-5
npx @mrkaran/hodor <PR_URL> --model bedrock/converse/anthropic.claude-sonnet-4-5-v2

# Extended reasoning for complex PRs
npx @mrkaran/hodor <PR_URL> --reasoning-effort high

# Custom review instructions
npx @mrkaran/hodor <PR_URL> --prompt "Focus on SQL injection and auth bypasses"

# Verbose mode (watch the agent think)
npx @mrkaran/hodor <PR_URL> -v

If you installed globally with npm install -g, replace npx @mrkaran/hodor with hodor.

Local Mode

Review local git changes without a PR URL. Useful for pre-push reviews, Bitbucket PRs, or any git repo.

# Review uncommitted changes against origin/main (default)
npx @mrkaran/hodor --local

# Review against a specific branch or ref
npx @mrkaran/hodor --local --diff-against develop
npx @mrkaran/hodor --local --diff-against HEAD~3

# Review a feature branch against main
git checkout feature-branch
npx @mrkaran/hodor --local --diff-against origin/main

# Use a specific workspace directory
npx @mrkaran/hodor --local --workspace /path/to/repo

# Combine with other flags
npx @mrkaran/hodor --local --diff-against origin/main --model openai/gpt-5 -v

Local mode:

• Includes uncommitted changes (staged + unstaged), not just commits
• Auto-resolves to the git repo root (works from subdirectories)
• Skips PR metadata fetching and workspace cloning
• --post is disabled (no remote to post to)

CLI Flags

Flag	Default	Description
--model	anthropic/claude-sonnet-4-5-20250929	LLM model (Anthropic, OpenAI, or Bedrock)
--reasoning-effort	–	Extended thinking: low, medium, high
--ultrathink	Off	Maximum reasoning effort
--local	Off	Review local git changes (no PR URL required)
--diff-against	origin/main	Git ref to diff against in --local mode
--post	Off	Post review as a comment on the PR/MR
--prompt	–	Append custom instructions to the review prompt
--prompt-file	–	Use a custom prompt file
--workspace	Temp dir	Workspace directory (reuse for faster multi-PR reviews)
--bedrock-tags	–	JSON cost allocation tags for AWS Bedrock
--prometheus-push	–	Push review metrics to a Prometheus Pushgateway
-v, --verbose	Off	Stream agent reasoning and tool calls

Environment Variables

Variable	Purpose
ANTHROPIC_API_KEY	Claude API key
OPENAI_API_KEY	OpenAI API key
LLM_API_KEY	Generic fallback (when provider-specific key is not set)
GITHUB_TOKEN / GITLAB_TOKEN	Post comments to PRs/MRs (with --post)
AWS_PROFILE or AWS_ACCESS_KEY_ID	AWS Bedrock auth (no API key needed)

CI/CD

GitHub Actions

name: Hodor Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    container: ghcr.io/mr-karan/hodor:latest
    steps:
      - name: Run Hodor
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          hodor "https://github.com/${{ github.repository }}/pull/${{ github.event.pull_request.number }}" --post

GitLab CI

include:
  - project: 'commons/gitlab-templates'
    ref: master
    file: '/hodor/.gitlab-ci-template.yml'

hodor-review:
  extends: .hodor-review

See AUTOMATED_REVIEWS.md for advanced CI workflows.

Token Optimization

Hodor automatically optimizes token usage:

• Diff embedding: For PRs under 200KB, the diff is embedded directly in the prompt, cutting agent turns from ~60 to ~5.
• Incremental reviews: On re-runs, only reviews changes since the last hodor comment (detected via SHA markers in posted comments).
• Compaction: SDK auto-summarizes older conversation turns when context grows too large.

Skills

Hodor discovers repository-specific review guidelines from .pi/skills/ or .hodor/skills/:

mkdir -p .hodor/skills/review-guidelines

# .hodor/skills/review-guidelines/SKILL.md
---
name: review-guidelines
description: Security and performance review checklist.
---

- All API endpoints must have authentication checks.
- Database queries must use parameterized statements.
- API responses should be < 200ms p95.

Skills are loaded automatically during reviews. See SKILLS.md for details.

Development

bun install          # Install dependencies
bun run build        # Build
bun run test         # Run tests
bun run dev -- <url> # Run from source

License

MIT