code-review-ai-agent

AI code review that runs automatically on every git commit. Your staged changes are reviewed by a local LLM (Ollama); high-severity issues can block the commit. Clean logs, zero fuss — just install and go. (Release notes · GitHub Releases)

Why you'll love it

| | | |---|---| | 🏠 Local-first | Every developer gets AI code review on their own machine — no cloud, no SaaS, no waiting. | | ⚡ Instant feedback | Catch security, logic, and quality issues before they leave your workstation. | | 🔒 Privacy & control | Your code never leaves your machine; run any Ollama model you want. | | 🚀 One install | Hook + config in one step. Commit as usual and the review runs automatically. |

For developers: quick start

1️⃣ Install

In your project root (where your package.json and Git repo live):

npm install --save-dev code-review-ai-agent

2️⃣ What happens automatically

• Config files (if missing):
  • .craai.json — project config (commit this)
  • .craai.local.json — your local overrides (gitignored)
• Git hook: a pre-commit hook is installed so every git commit runs the review.

3️⃣ Run a commit

git add .
git commit -m "your message"

If the AI finds issues at or above the blocking severity (default: High), the commit is blocked and you see the review comments. Fix the code (or adjust config) and commit again. If there are no blocking issues, the commit succeeds.

What you need

| Requirement | Details | |-------------|---------| | ✅ Node.js | Version 18 or higher | | ✅ Git | Normal Git setup | | 🦙 Ollama (optional) | ollama.ai. Install, then run e.g. ollama pull llama3. If Ollama is not running or the request fails, the commit is allowed (fail-open). |

Managing the tool in your project

📁 Config files (in project root)

| File | Purpose | Commit? | |------|---------|--------| | .craai.json | Shared rules, LLM settings, what to block on | Yes — so the whole team uses the same policy | | .craai.local.json | Your personal overrides (e.g. different model, or turn off) | No — added to .gitignore by the installer |

Settings are merged in this order: defaults → .craai.json → .craai.local.json (later overrides earlier).

Turn off review (only for you)

Create or edit .craai.local.json in the project root:

{
  "enabled": false
}

Commits will no longer run the AI review. Leave .craai.json as-is for the rest of the team.

Change what blocks the commit

In .craai.json (or .craai.local.json for just you):

{
  "review": {
    "blockOn": "High"
  }
}

Use "High", "Medium", or "Low". Only issues with this severity (or higher impact) will block.

Use a different Ollama model

Example in .craai.local.json:

{
  "llm": {
    "model": "codellama"
  }
}

Ignore more paths from the diff

In .craai.json:

{
  "review": {
    "ignorePatterns": ["node_modules", "dist", "*.min.js"]
  }
}

Only paths containing these substrings are excluded from the diff sent to the AI.

Add custom rules for the AI

In .craai.json:

{
  "prompt": {
    "additionalRules": [
      "Check for security issues",
      "Check for performance problems",
      "Follow clean code principles",
      "Prefer async/await over raw promises"
    ]
  }
}

Example output

🚫 Commit blocked — you see review comments:

--- PR review comments ---
[1] src/foo.js:11 [High] Security
    Hardcoded database password is a security risk.
    → Use environment variables for sensitive information.
    Suggested fix:
    process.env.DB_PASSWORD
--- end review ---
Commit blocked by code-review-ai-agent

✅ Commit allowed — no blocking issues:

No review comments.
Code is Approved by AI Agent

⏭️ Nothing to review (no staged changes or review skipped):

No changes to review.

Full config reference

🔧 Use these in .craai.json or .craai.local.json.

| Option | Default | What it does | |--------|---------|----------------| | enabled | true | false = no review, commit always allowed | | llm.provider | "ollama" | LLM backend (only ollama supported today) | | llm.model | "llama3" | Ollama model name | | llm.endpoint | "http://localhost:11434" | Ollama API URL | | llm.temperature | 0.2 | 0–1; lower = more stable output | | llm.timeout | 30000 | Request timeout in ms | | review.trigger | ["pre-commit"] | When to run; only pre-commit hook is installed by default | | review.blockOn | "High" | Severity that blocks: "High", "Medium", or "Low" | | review.ignorePatterns | ["node_modules", "dist"] | Path substrings to exclude from the diff | | review.skipBranches | ["publish"] | Branches to skip (for pre-push; not used if you only use pre-commit) | | prompt.additionalRules | (list in docs) | Extra instructions for the AI | | performance.maxDiffSize | 20000 | Max diff size in characters; above this, review is skipped and commit allowed | | git.defaultBranch | "main" | Default branch name (used when diff is not from push) |

Example .craai.json (good base for your repo)

{
  "enabled": true,
  "llm": {
    "provider": "ollama",
    "model": "llama3",
    "endpoint": "http://localhost:11434",
    "temperature": 0.2,
    "timeout": 30000
  },
  "review": {
    "trigger": ["pre-commit"],
    "blockOn": "High",
    "ignorePatterns": ["node_modules", "dist"],
    "skipBranches": ["publish"]
  },
  "prompt": {
    "additionalRules": [
      "Check for security issues",
      "Check for performance problems",
      "Follow clean code principles"
    ]
  },
  "performance": {
    "maxDiffSize": 20000
  },
  "git": {
    "defaultBranch": "main"
  }
}

Uninstall

🗑️ To remove the tool from the project:

npm uninstall code-review-ai-agent

This removes the package from node_modules only. You must manually remove the hook and config files from your project repo:

1. Remove the pre-commit hook
   Delete the file:

   • .git/hooks/pre-commit
     (If you added a pre-push hook from this package, remove .git/hooks/pre-push as well.)

2. Remove the config files
   From your project root, delete:

   • .craai.json
   • .craai.local.json

3. Remove the entry from .gitignore
   Open .gitignore and delete the line that contains:

   • .craai.local.json

Running without the hook (CI or one-off)

▶️ From the project root, with staged changes:

node node_modules/code-review-ai-agent/dist/index.js pre-commit

Same config and logic as the hook. Useful in CI or to test the review without committing.

To force a “block” for testing, set:

set CRAAI_TEST_BLOCK=1
node node_modules/code-review-ai-agent/dist/index.js pre-commit

Team workflow (production)

1. 📌 Commit .craai.json in the repo so everyone shares the same policy and LLM settings.
2. 👥 Each developer runs npm install; the postinstall creates the pre-commit hook and adds .craai.local.json to .gitignore.
3. 🎛️ Personal overrides go in .craai.local.json (e.g. different model, or enabled: false for a while).

When the commit is blocked vs allowed

| Situation | Result | |-----------|--------| | Config file invalid or missing (required parts) | Commit blocked (exit 1) | | enabled: false or trigger doesn’t include this hook | No review; commit allowed | | Git diff fails (e.g. not a repo) | Commit blocked | | Diff too large or empty | No review; commit allowed | | Ollama not running / timeout / empty response | Commit allowed (fail-open) | | AI returns blocking severity (e.g. High when blockOn is High) | Commit blocked | | AI returns only lower severity or no issues | Commit allowed |

So: config and Git problems block; LLM problems allow to avoid blocking the team when the AI is down.

GitHub Desktop and other GUIs

🖥️ The hook is a Node script. For it to run from GitHub Desktop (or other Git GUIs), Node must be on the PATH used when Git runs hooks. If commits from the GUI don’t run the review, run commits from a terminal where node works, or add Node to the PATH used by your Git installation.

License

MIT