code-review-agent-cli 1.0.0

package/README.md

@@ -0,0 +1,273 @@
+# Code Review Agent
+
+A code review and audit CLI tool powered by the Claude Agent SDK. It analyzes codebases for bugs, security issues, performance problems, and maintainability concerns — all from your terminal.
+
+## Prerequisites
+
+- **Node.js** v18+
+- An **Anthropic API key** — get one from the [Claude Console](https://platform.claude.com/)
+
+## Setup
+
+### From source
+
+```bash
+git clone <your-repo-url>
+cd my-first-agent
+npm install
+```
+
+### As an npm package
+
+```bash
+npm install -g code-review-agent
+```
+
+Then run from any project directory:
+
+```bash
+code-review-agent "Review this codebase"
+code-review-agent --fix-recursive
+```
+
+### Authentication
+
+This tool uses the **Claude Agent SDK**, which calls the Anthropic API directly. You need an `ANTHROPIC_API_KEY` set in your environment.
+
+**Add it to your shell profile** (recommended — works for both npm and source installs):
+
+```bash
+# Add to ~/.bashrc, ~/.zshrc, or ~/.bash_profile
+export ANTHROPIC_API_KEY=your-api-key
+```
+
+Then reload your shell (`source ~/.zshrc`) or open a new terminal.
+
+**Or pass it inline** for a single run:
+
+```bash
+ANTHROPIC_API_KEY=your-api-key code-review-agent "Review this codebase"
+```
+
+**Or use a `.env` file** (when running from source only):
+
+```bash
+echo "ANTHROPIC_API_KEY=your-api-key" > .env
+```
+
+The SDK also supports third-party API providers:
+
+- **Amazon Bedrock**: set `CLAUDE_CODE_USE_BEDROCK=1` and configure AWS credentials
+- **Google Vertex AI**: set `CLAUDE_CODE_USE_VERTEX=1` and configure Google Cloud credentials
+
+## Usage
+
+### Quick start
+
+Run with no arguments to explore and review the current directory:
+
+```bash
+npm start
+```
+
+Or pass a specific prompt:
+
+```bash
+npx tsx index.ts "Review utils.py for bugs"
+```
+
+With npm start:
+
+```bash
+npm start -- "Review the authentication module"
+```
+
+### Fix mode
+
+Use `--fix` to have the agent apply its recommended fixes directly to your source files:
+
+```bash
+npx tsx index.ts --fix "Review utils.py for bugs"
+```
+
+The agent will review the code, then edit the files to fix Critical and Warning issues.
+
+### Recursive fix mode
+
+Use `--fix-recursive` to run a review/fix loop that keeps going until there are no more critical issues:
+
+```bash
+npx tsx index.ts --fix-recursive "Review all source files"
+```
+
+Each pass reviews the code, applies fixes, then re-reviews the modified files to catch any issues introduced by the fixes. The loop stops when the agent reports all clear or the pass limit is reached.
+
+Control the maximum number of passes with `--max-passes` (default: 5):
+
+```bash
+npx tsx index.ts --fix-recursive --max-passes 3 "Audit agent.ts"
+```
+
+### Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-m, --model <model>` | Claude model to use | `claude-sonnet-4-5-20250929` |
+| `-t, --tools <tools>` | Comma-separated list of allowed tools | `Read,Edit,Glob,Grep,Write,Bash` |
+| `-p, --permission-mode <mode>` | `default`, `acceptEdits`, or `bypassPermissions` | `acceptEdits` |
+| `--max-turns <n>` | Maximum number of agentic turns | unlimited |
+| `--fix` | Apply recommended fixes to source files | off |
+| `--fix-recursive` | Review, fix, re-review until no critical issues remain | off |
+| `--max-passes <n>` | Max review/fix passes for `--fix-recursive` | `5` |
+| `--cwd <dir>` | Working directory for the agent | current directory |
+
+### Examples
+
+```bash
+# Review only (report issues, don't touch files)
+npx tsx index.ts "Review src/ for security issues" -t Read,Glob,Grep
+
+# Review and fix in one pass
+npx tsx index.ts --fix "Find and fix bugs in utils.py"
+
+# Recursive fix until clean
+npx tsx index.ts --fix-recursive "Audit this codebase"
+
+# Recursive fix with limited passes and a specific directory
+npx tsx index.ts --fix-recursive --max-passes 3 --cwd ./src "Review all files"
+
+# Use a different model
+npx tsx index.ts "Audit this codebase" -m claude-sonnet-4-5-20250929
+
+# Full permissions (use with caution)
+npx tsx index.ts --fix "Fix all critical bugs" -p bypassPermissions
+```
+
+## Architecture
+
+```
+my-first-agent/
+├── index.ts              # CLI entry point — parses args, calls agent
+├── agent.ts              # Core agent — identity, tools, prompt, runs query()
+├── prompts/
+│   └── system.md         # System prompt — agent identity and behavior
+├── skills/
+│   └── code-review.md    # Code review methodology (loaded at startup)
+├── utils/
+│   ├── display.ts        # Message rendering for the terminal
+│   └── formatting.ts     # String helpers (truncation, tool formatting)
+├── marked-terminal.d.ts  # Type declaration for marked-terminal
+├── package.json
+└── tsconfig.json
+```
+
+### How it works
+
+**`index.ts`** — Thin CLI entry point. Uses Commander to parse arguments and options, then calls `runAgent()`.
+
+**`agent.ts`** — Core agent module. Loads the system prompt from `prompts/system.md`, configures tools, and streams output through `showMessage()`. Supports three modes:
+
+- **Review only** (default) — runs a single review pass
+- **`--fix`** — appends fix-mode instructions to the system prompt so the agent edits files after reviewing
+- **`--fix-recursive`** — runs the agent in a loop: review, fix, re-review modified files, repeat until `ALL_CLEAR` or max passes reached
+
+**`prompts/system.md`** — Defines who the agent is and how it behaves. This is what makes it a code review agent rather than a generic CLI tool.
+
+**`skills/`** — Skill files (`.md`) loaded at startup and appended to the system prompt. Each file adds a specific capability. Drop in a new `.md` file to extend the agent — no code changes needed.
+
+### Message streaming
+
+The agent uses an async iterator from `query()`. Each message has a `type`:
+
+- **`assistant`** — Claude's response. Contains text blocks and tool-use blocks.
+- **`user`** — Tool results returned to Claude (stderr shown for Bash).
+- **`tool_progress`** — Progress updates for long-running tools.
+- **`result`** — Final message with stats (turns, duration, cost).
+
+### Environment variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `ANTHROPIC_API_KEY` | Your Anthropic API key (required) | — |
+| `MAX_PROMPT_LENGTH` | Maximum allowed prompt length in characters (capped at 100,000) | `50000` |
+| `DEBUG` | Show stack traces and verbose error output | off |
+
+## Flow Diagrams
+
+### Normal mode (`--fix` or no flags)
+
+```mermaid
+flowchart TD
+    A[CLI: parse args] --> B[Validate prompt]
+    B --> C[Load system prompt]
+    C --> D{--fix flag?}
+    D -- Yes --> E[Append fix instructions]
+    D -- No --> F[Use base prompt]
+    E --> G[Build options]
+    F --> G
+    G --> H[query prompt, options]
+
+    H --> I{Stream messages}
+    I -- assistant --> J[Render text / tool calls]
+    I -- user --> K[Show stderr if any]
+    I -- tool_progress --> L[Show progress]
+    I -- result --> M[Show summary]
+
+    J --> I
+    K --> I
+    L --> I
+    M --> N[Done]
+```
+
+### Recursive fix mode (`--fix-recursive`)
+
+```mermaid
+flowchart TD
+    A[CLI: parse args] --> B[Validate prompt]
+    B --> C[Load system prompt]
+    C --> D[Append recursive fix instructions]
+    D --> E[Build options]
+
+    E --> F["Pass 1: executeQuery(user prompt)"]
+    F --> G[Agent reviews + fixes files]
+    G --> H[Capture last output text]
+
+    H --> I{Output contains\nALL_CLEAR?}
+    I -- Yes --> J["All critical issues resolved"]
+    I -- No --> K{pass < maxPasses?}
+    K -- Yes --> L["Pass N: executeQuery(re-review prompt)"]
+    L --> G
+    K -- No --> M["Reached max passes\n⚠ issues may remain"]
+
+    style J fill:#2d6,color:#fff
+    style M fill:#d93,color:#fff
+```
+
+## Adding Skills
+
+Drop a `.md` file into the `skills/` directory. It will be loaded automatically at startup and appended to the system prompt.
+
+For example, to add a dependency audit skill:
+
+```bash
+cat > skills/dependency-audit.md << 'EOF'
+# Dependency Audit
+
+When asked to audit dependencies, follow this process.
+
+## Process
+1. Read package.json (or requirements.txt, go.mod, etc.)
+2. Run the appropriate audit command (npm audit, pip audit, etc.)
+3. Check for outdated packages
+4. Flag packages with restrictive or incompatible licenses
+
+## Output Format
+For each issue found:
+- **Package**: name and version
+- **Severity**: Critical / High / Medium / Low
+- **Issue**: what's wrong
+- **Fix**: recommended action
+EOF
+```
+
+Skills are loaded alphabetically by filename.

package/dist/agent.js

@@ -0,0 +1,317 @@
+import { readFile, readdir } from "node:fs/promises";
+import { resolve, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import { showMessage } from "./utils/display.js";
+import { stripAnsiCodes } from "./utils/formatting.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const VALID_MODELS = new Set(["claude-sonnet-4-5-20250929", "claude-opus-4-6", "claude-opus-4"]);
+const VALID_PERMISSION_MODES = new Set(["default", "acceptEdits", "bypassPermissions"]);
+const MAX_PROMPT_LENGTH = (() => {
+    if (!process.env.MAX_PROMPT_LENGTH)
+        return 50000;
+    const parsed = Number.parseInt(process.env.MAX_PROMPT_LENGTH, 10);
+    if (Number.isNaN(parsed) || parsed < 1)
+        return 50000;
+    return Math.min(parsed, 100000);
+})();
+let cachedSystemPrompt = null;
+async function loadSystemPrompt() {
+    if (cachedSystemPrompt !== null)
+        return cachedSystemPrompt;
+    const promptPath = resolve(__dirname, "prompts/system.md");
+    try {
+        cachedSystemPrompt = await readFile(promptPath, "utf-8");
+        return cachedSystemPrompt;
+    }
+    catch (error) {
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        const wrapped = new Error(`Failed to load system prompt from ${promptPath}. Ensure prompts/system.md exists.\nCause: ${errorMsg}`, error instanceof Error ? { cause: error } : undefined);
+        if (error instanceof Error && error.stack) {
+            wrapped.stack = `${wrapped.stack}\n\nCaused by:\n${error.stack}`;
+        }
+        throw wrapped;
+    }
+}
+let cachedSkills = null;
+async function loadSkills() {
+    if (cachedSkills !== null)
+        return cachedSkills;
+    const skillsDir = resolve(__dirname, "skills");
+    let entries;
+    try {
+        entries = await readdir(skillsDir);
+    }
+    catch (error) {
+        const errCode = error.code;
+        if (errCode === "ENOENT" || errCode === "ENOTDIR") {
+            cachedSkills = "";
+            return cachedSkills;
+        }
+        throw new Error(`Failed to read skills directory: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const mdFiles = entries.filter(f => f.endsWith(".md")).sort((a, b) => a.localeCompare(b));
+    if (mdFiles.length === 0) {
+        cachedSkills = "";
+        return cachedSkills;
+    }
+    const contents = await Promise.all(mdFiles.map(file => readFile(join(skillsDir, file), "utf-8")));
+    const parts = contents.map(c => c.trim());
+    cachedSkills = "\n\n" + parts.join("\n\n");
+    return cachedSkills;
+}
+function validatePrompt(prompt) {
+    if (!prompt || prompt.trim().length === 0) {
+        throw new Error("Prompt cannot be empty");
+    }
+    if (prompt.length > MAX_PROMPT_LENGTH) {
+        throw new Error(`Prompt exceeds maximum length of ${MAX_PROMPT_LENGTH} characters`);
+    }
+}
+const FIX_MODE_INSTRUCTIONS = `
+
+## Fix Mode
+
+Fix mode is enabled. You MUST apply fixes, not just report them.
+
+### Process
+1. Review the code and identify Critical and Warning issues.
+2. For EACH issue found, immediately use the Edit tool to fix it in the source file.
+3. After all edits are applied, output a summary listing every file you changed and what you fixed.
+
+### Rules
+- Fix Critical and Warning issues. Skip Suggestions unless they are trivial.
+- Make the smallest possible change for each fix — do not refactor surrounding code.
+- You MUST call the Edit tool for each fix. Do not just describe the fix — apply it.
+`;
+const FIX_RECURSIVE_INSTRUCTIONS = `
+
+## Recursive Fix Mode
+
+Recursive fix mode is enabled. You MUST apply fixes, not just report them.
+
+### Process
+1. Review the code and identify Critical and Warning issues.
+2. For EACH issue found, immediately use the Edit tool to fix it in the source file.
+3. After all edits are applied, output a summary in this exact format:
+
+### Fixes Applied
+- **file.ts:LINE** — description of what was fixed
+
+If no fixes were needed, write: "No fixes needed."
+
+4. On your VERY LAST line of output (after everything else), write ONLY one of these two status markers on its own line:
+  - CRITICAL_REMAINING: N  (where N is the count of Critical issues you could NOT fix)
+  - ALL_CLEAR  (if zero Critical issues remain after your fixes)
+
+### Rules
+- You MUST call the Edit tool for each fix. Do not just describe the fix — apply it.
+- Fix Critical and Warning issues. Skip Suggestions.
+- Make the smallest possible change — do not refactor surrounding code.
+- The status marker must be the VERY LAST line, with nothing after it.
+`;
+const DEFAULT_MAX_PASSES = 5;
+const FIX_PROMPT_PREFIX = "IMPORTANT: You are in fix mode. You MUST apply fixes using the Edit tool — do not just report issues. " +
+    "For each bug or issue you find, immediately call the Edit tool to fix it in the source file. " +
+    "Do NOT ask the user if they want fixes applied — apply them directly.\n\n";
+function getFixInstructions(opts) {
+    if (opts.fixRecursive)
+        return FIX_RECURSIVE_INSTRUCTIONS;
+    if (opts.fix)
+        return FIX_MODE_INSTRUCTIONS;
+    return "";
+}
+function resolveOptions(opts, promptAppend) {
+    const model = opts.model ?? "claude-sonnet-4-5-20250929";
+    if (!VALID_MODELS.has(model)) {
+        throw new Error(`Invalid model: ${model}`);
+    }
+    const permissionMode = (opts.permissionMode ?? "acceptEdits");
+    if (!VALID_PERMISSION_MODES.has(permissionMode)) {
+        throw new Error(`Invalid permission mode: ${permissionMode}`);
+    }
+    if (permissionMode === "bypassPermissions" && !opts.bypassConfirmed) {
+        throw new Error("bypassPermissions requires confirmation via the CLI");
+    }
+    return {
+        model,
+        allowedTools: opts.tools ?? ["Read", "Edit", "Glob", "Grep", "Write", "Bash"],
+        permissionMode,
+        systemPrompt: {
+            type: "preset",
+            preset: "claude_code",
+            append: promptAppend,
+        },
+        ...(opts.maxTurns && { maxTurns: opts.maxTurns }),
+        ...(opts.cwd && { cwd: opts.cwd }),
+    };
+}
+// Returns the last text block from an assistant message, or null if none found.
+function extractLastText(msg) {
+    if (msg.type !== "assistant")
+        return null;
+    const assistant = msg;
+    const content = assistant.message?.content;
+    if (!Array.isArray(content))
+        return null;
+    let text = null;
+    for (const block of content) {
+        if (typeof block === "object" && block !== null && "text" in block) {
+            const textValue = block.text;
+            if (typeof textValue === "string") {
+                text = textValue;
+            }
+        }
+    }
+    return text;
+}
+function isValidMessage(message) {
+    return !!message && typeof message === "object" && !Array.isArray(message);
+}
+function isFileModificationBlock(block) {
+    if (typeof block !== "object" || block === null || !("name" in block))
+        return false;
+    const name = block.name;
+    return name === "Edit" || name === "Write";
+}
+function getEditFilePath(block) {
+    if (typeof block.input !== "object" || block.input === null)
+        return null;
+    const input = block.input;
+    const filePath = input.file_path;
+    if (typeof filePath === "string" && filePath.length > 0)
+        return filePath;
+    return null;
+}
+function collectEdits(msg, editedFiles) {
+    if (msg.type !== "assistant")
+        return 0;
+    const assistant = msg;
+    const content = assistant.message?.content;
+    if (!Array.isArray(content))
+        return 0;
+    let count = 0;
+    for (const block of content) {
+        if (isFileModificationBlock(block)) {
+            count++;
+            const filePath = getEditFilePath(block);
+            if (filePath)
+                editedFiles.add(filePath);
+        }
+    }
+    return count;
+}
+async function executeQuery(prompt, options) {
+    let lastText = "";
+    let editCount = 0;
+    const editedFiles = new Set();
+    // Validate prompt is not empty after sanitization
+    // Strip control characters except tabs (\x09), newlines (\x0A), and carriage returns (\x0D)
+    const sanitizedPrompt = prompt.replaceAll(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, "");
+    if (sanitizedPrompt.trim().length === 0) {
+        throw new Error("Prompt is empty after sanitization");
+    }
+    try {
+        for await (const message of query({ prompt: sanitizedPrompt, options })) {
+            if (!isValidMessage(message))
+                continue;
+            if (typeof message.type !== "string")
+                continue;
+            editCount += collectEdits(message, editedFiles);
+            await showMessage(message);
+            lastText = extractLastText(message) ?? lastText;
+        }
+    }
+    catch (error) {
+        if (error instanceof Error)
+            throw error;
+        throw new Error(`Query execution failed: ${String(error)}`);
+    }
+    return { lastText, editCount, editedFiles: Array.from(editedFiles) };
+}
+function getStatusFromOutput(text) {
+    const trimmed = text.trim();
+    if (trimmed.length === 0)
+        return "unknown";
+    const lines = trimmed.split("\n");
+    const lastLine = lines.length > 0 ? stripAnsiCodes(lines[lines.length - 1].trim()).toUpperCase() : "";
+    if (lastLine === "ALL_CLEAR")
+        return "all_clear";
+    const match = /^CRITICAL_REMAINING:\s*(\d+)$/i.exec(lastLine);
+    if (match && match[1]) {
+        const count = Number.parseInt(match[1], 10);
+        if (!Number.isNaN(count) && count >= 0 && count < 1000000) {
+            return count === 0 ? "all_clear" : "critical_remaining";
+        }
+    }
+    return "unknown";
+}
+async function runRecursive(prompt, options, maxPasses) {
+    if (!Number.isInteger(maxPasses) || maxPasses < 1 || maxPasses > 100) {
+        throw new Error("maxPasses must be an integer between 1 and 100");
+    }
+    console.log(`\n\x1b[35m━━━ Pass 1/${maxPasses} ━━━\x1b[0m\n`);
+    let result = await executeQuery(FIX_PROMPT_PREFIX + prompt, options);
+    console.log(`\n\x1b[36m━━━ Pass 1 complete: ${result.editCount} file edit(s) applied ━━━\x1b[0m`);
+    for (let pass = 2; pass <= maxPasses; pass++) {
+        if (result.editCount === 0) {
+            // No edits in the last pass — check if the agent confirmed all clear
+            const status = getStatusFromOutput(result.lastText);
+            if (status === "all_clear") {
+                console.log("\n\x1b[32m━━━ All critical issues resolved ━━━\x1b[0m\n");
+            }
+            else {
+                console.log("\x1b[33m⚠ No edits were made — stopping early.\x1b[0m\n");
+            }
+            return;
+        }
+        // Edits were made — always re-review to verify fixes didn't introduce new issues
+        const fileList = result.editedFiles.length > 0
+            ? `Re-review these modified files: ${result.editedFiles.join(", ")}.`
+            : "Re-review all source files that were just modified.";
+        const reReviewPrompt = fileList +
+            " Check if the fixes introduced new issues. Fix any remaining Critical or Warning issues.";
+        console.log(`\n\x1b[35m━━━ Pass ${pass}/${maxPasses} ━━━\x1b[0m\n`);
+        result = await executeQuery(reReviewPrompt, options);
+        console.log(`\n\x1b[36m━━━ Pass ${pass} complete: ${result.editCount} file edit(s) applied ━━━\x1b[0m`);
+    }
+    const finalStatus = getStatusFromOutput(result.lastText);
+    if (finalStatus === "all_clear") {
+        console.log("\n\x1b[32m━━━ All critical issues resolved ━━━\x1b[0m\n");
+    }
+    else {
+        console.log(`\n\x1b[33m━━━ Reached max passes (${maxPasses}). Some critical issues may remain. ━━━\x1b[0m\n`);
+    }
+}
+function wrapQueryError(error) {
+    if (error instanceof Error) {
+        const wrapped = new Error(`Agent query failed: ${error.message}`);
+        if (error.stack) {
+            wrapped.stack = `${wrapped.stack}\nCaused by: ${error.stack}`;
+        }
+        return wrapped;
+    }
+    return new Error(`Agent query failed: ${String(error)}`);
+}
+export async function runAgent(prompt, opts = {}) {
+    validatePrompt(prompt);
+    await loadSystemPrompt(); // Validate that system prompt exists
+    const skills = await loadSkills();
+    const promptAppend = skills + getFixInstructions(opts);
+    const options = resolveOptions(opts, promptAppend);
+    try {
+        if (opts.fixRecursive) {
+            await runRecursive(prompt, options, opts.maxPasses ?? DEFAULT_MAX_PASSES);
+        }
+        else if (opts.fix) {
+            const { editCount } = await executeQuery(FIX_PROMPT_PREFIX + prompt, options);
+            console.log(`\n\x1b[36m━━━ ${editCount} file edit(s) applied ━━━\x1b[0m\n`);
+        }
+        else {
+            await executeQuery(prompt, options);
+        }
+    }
+    catch (error) {
+        throw wrapQueryError(error);
+    }
+}

package/dist/index.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env npx tsx
+import { createInterface } from "node:readline";
+import { Command } from "commander";
+import { runAgent } from "./agent.js";
+const DEFAULT_PROMPT = "Explore all the files in the current directory. List them and provide a brief summary of what this project is about. Then review all source files for bugs, security issues, and code quality.";
+const VALID_TOOLS = new Set(["Read", "Edit", "Glob", "Grep", "Write", "Bash"]);
+const VALID_PERMISSION_MODES = new Set(["default", "acceptEdits", "bypassPermissions"]);
+function checkApiKey() {
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    if (!apiKey || apiKey.trim().length === 0) {
+        console.error("\x1b[31mError: ANTHROPIC_API_KEY is not set or empty.\x1b[0m\n");
+        console.error("Set it in your shell profile (persists across sessions):");
+        console.error("  echo 'export ANTHROPIC_API_KEY=your-api-key' >> ~/.zshrc");
+        console.error("  source ~/.zshrc\n");
+        console.error("Or pass it inline for a single run:");
+        console.error("  ANTHROPIC_API_KEY=your-api-key code-review-agent \"Review this codebase\"\n");
+        console.error("Get your API key at: https://platform.claude.com/");
+        process.exit(1);
+    }
+    // Basic format validation
+    const trimmed = apiKey.trim();
+    if (trimmed.length < 40 || !/^sk-ant-[a-zA-Z0-9_-]{40,}$/.test(trimmed)) {
+        console.error("\x1b[33m⚠ Warning: ANTHROPIC_API_KEY may have an invalid format.\x1b[0m");
+        console.error("\x1b[33m  Expected format: sk-ant-...\x1b[0m\n");
+    }
+}
+const program = new Command();
+program
+    .name("code-review-agent")
+    .description("Code review and audit agent powered by Claude")
+    .version("1.0.0")
+    .argument("[prompt]", "The prompt to send to the agent")
+    .option("-m, --model <model>", "Model to use", "claude-sonnet-4-5-20250929")
+    .option("-t, --tools <tools>", "Comma-separated allowed tools", "Read,Edit,Glob,Grep,Write,Bash")
+    .option("-p, --permission-mode <mode>", "Permission mode: default, acceptEdits, bypassPermissions", "acceptEdits")
+    .option("--max-turns <n>", "Max turns", (val) => {
+    const parsed = Number.parseInt(val, 10);
+    if (Number.isNaN(parsed) || parsed <= 0) {
+        throw new Error("--max-turns must be a positive integer");
+    }
+    return parsed;
+})
+    .option("--fix", "Apply recommended fixes to source files")
+    .option("--fix-recursive", "Review, fix, and re-review until no critical issues remain")
+    .option("--max-passes <n>", "Max review passes for --fix-recursive (default: 5)", (val) => {
+    const parsed = Number.parseInt(val, 10);
+    if (Number.isNaN(parsed) || parsed <= 0) {
+        throw new Error("--max-passes must be a positive integer");
+    }
+    return parsed;
+}, 5)
+    .option("--cwd <dir>", "Working directory")
+    .action(async (prompt, opts) => {
+    checkApiKey();
+    try {
+        const tools = opts.tools.split(",").map((t) => t.trim());
+        const invalidTools = tools.filter((t) => !VALID_TOOLS.has(t));
+        if (invalidTools.length > 0) {
+            throw new Error(`Invalid tools: ${invalidTools.join(", ")}`);
+        }
+        if (!VALID_PERMISSION_MODES.has(opts.permissionMode)) {
+            throw new Error(`Invalid permission mode: ${opts.permissionMode}. Must be one of: ${Array.from(VALID_PERMISSION_MODES).join(", ")}`);
+        }
+        if (opts.permissionMode === "bypassPermissions") {
+            if (process.env.CONFIRM_BYPASS_PERMISSIONS !== "1") {
+                throw new Error("bypassPermissions mode requires CONFIRM_BYPASS_PERMISSIONS=1 environment variable. " +
+                    "Example: CONFIRM_BYPASS_PERMISSIONS=1 code-review-agent --fix -p bypassPermissions \"Review this\"");
+            }
+            if (!process.stdin.isTTY) {
+                throw new Error("bypassPermissions mode requires an interactive terminal (no piped input).");
+            }
+            const cwd = opts.cwd ?? process.cwd();
+            console.error("\x1b[33m⚠ WARNING: Running in bypassPermissions mode.\x1b[0m");
+            console.error("\x1b[33m⚠ Files may be modified without confirmation.\x1b[0m");
+            console.error(`\x1b[33m⚠ Working directory: ${cwd}\x1b[0m`);
+            const rl = createInterface({ input: process.stdin, output: process.stderr });
+            let answer;
+            try {
+                answer = await new Promise((resolve, reject) => {
+                    const timeout = setTimeout(() => {
+                        rl.close();
+                        reject(new Error("Timeout waiting for confirmation (30s)."));
+                    }, 30000);
+                    rl.question("\x1b[33m⚠ Type 'yes' to confirm: \x1b[0m", (ans) => {
+                        clearTimeout(timeout);
+                        resolve(ans);
+                    });
+                });
+            }
+            finally {
+                rl.close();
+            }
+            if (answer.trim().toLowerCase() !== "yes") {
+                console.error("\x1b[31mAborted.\x1b[0m");
+                process.exit(1);
+            }
+        }
+        await runAgent(prompt ?? DEFAULT_PROMPT, {
+            model: opts.model,
+            tools,
+            permissionMode: opts.permissionMode,
+            maxTurns: opts.maxTurns,
+            fix: Boolean(opts.fix || opts.fixRecursive),
+            fixRecursive: Boolean(opts.fixRecursive),
+            maxPasses: opts.maxPasses,
+            cwd: opts.cwd,
+            bypassConfirmed: opts.permissionMode === "bypassPermissions",
+        });
+    }
+    catch (error) {
+        const isValidation = error instanceof Error &&
+            (error.message.includes("Invalid") || error.message.includes("must be"));
+        if (error instanceof Error) {
+            console.error("\x1b[31mError:\x1b[0m", error.message);
+            if (process.env.DEBUG) {
+                console.error(error.stack);
+            }
+        }
+        else {
+            console.error("\x1b[31mError:\x1b[0m", String(error));
+        }
+        process.exit(isValidation ? 2 : 1);
+    }
+});
+program.parse(process.argv);

package/dist/prompts/prompts/system.md

@@ -0,0 +1,16 @@
+# Code Review Agent
+
+You are a code review and audit agent. Your primary purpose is to analyze codebases
+for bugs, security issues, performance problems, and maintainability concerns.
+
+## Capabilities
+- Read and analyze source files
+- Search codebases with glob patterns and grep
+- Run commands to understand project structure
+- Provide structured, actionable feedback
+
+## Behavior
+- Always read files before commenting on them
+- Be specific — reference exact file paths and line numbers
+- Prioritize critical issues over style preferences
+- Provide code snippets showing fixes, not just descriptions

package/dist/prompts/system.md

@@ -0,0 +1,16 @@
+# Code Review Agent
+
+You are a code review and audit agent. Your primary purpose is to analyze codebases
+for bugs, security issues, performance problems, and maintainability concerns.
+
+## Capabilities
+- Read and analyze source files
+- Search codebases with glob patterns and grep
+- Run commands to understand project structure
+- Provide structured, actionable feedback
+
+## Behavior
+- Always read files before commenting on them
+- Be specific — reference exact file paths and line numbers
+- Prioritize critical issues over style preferences
+- Provide code snippets showing fixes, not just descriptions

package/dist/skills/code-review.md

@@ -0,0 +1,65 @@
+---
+name: code-review
+description: >
+  Perform structured, multi-pass code reviews with severity-rated findings.
+  Use when the user asks to review code, check for bugs, audit files, analyze
+  code quality, find vulnerabilities, or requests a code audit. Also trigger
+  when the user says "review this", "check this code", "find bugs", or
+  "is this code safe".
+---
+
+# Code Review
+
+When asked to review code, follow this structured methodology.
+
+## Review Process
+
+Go through each file and check these areas in order:
+
+### 1. Bugs & Correctness
+- Logic errors, off-by-one mistakes, race conditions
+- Null/undefined access, unhandled edge cases
+- Type mismatches or incorrect assumptions about data shapes
+- Incorrect return values or missing return statements
+
+### 2. Security
+- Injection vulnerabilities (SQL, command, XSS)
+- Hardcoded secrets, exposed credentials
+- Unsafe input handling, missing validation
+- Insecure dependencies or configurations
+
+### 3. Error Handling
+- Missing try/catch around operations that can fail
+- Swallowed errors, uninformative error messages
+- Unhandled promise rejections or missing async error paths
+- Missing cleanup in error paths (file handles, connections)
+
+### 4. Performance
+- Unnecessary loops, repeated computations
+- Memory leaks, unclosed resources
+- N+1 queries, blocking operations in async code
+- Inefficient data structures or algorithms
+
+### 5. Readability & Maintainability
+- Confusing naming, overly complex logic
+- Code duplication that should be extracted
+- Functions doing too many things
+- Missing or misleading comments on non-obvious logic
+
+## Output Format
+
+For each issue found, report:
+- **File and line**: exact location
+- **Severity**: Critical / Warning / Suggestion
+- **Issue**: what's wrong
+- **Fix**: how to fix it with a code snippet
+
+End with a summary table counting issues by severity per file.
+
+## Guidelines
+
+- Read each file fully before reporting issues
+- Focus on real problems, not style nitpicks
+- Prioritize Critical issues first
+- If no issues are found in a category, skip it
+- Provide actionable fixes, not vague suggestions

package/dist/skills/skills/code-review.md

@@ -0,0 +1,65 @@
+---
+name: code-review
+description: >
+  Perform structured, multi-pass code reviews with severity-rated findings.
+  Use when the user asks to review code, check for bugs, audit files, analyze
+  code quality, find vulnerabilities, or requests a code audit. Also trigger
+  when the user says "review this", "check this code", "find bugs", or
+  "is this code safe".
+---
+
+# Code Review
+
+When asked to review code, follow this structured methodology.
+
+## Review Process
+
+Go through each file and check these areas in order:
+
+### 1. Bugs & Correctness
+- Logic errors, off-by-one mistakes, race conditions
+- Null/undefined access, unhandled edge cases
+- Type mismatches or incorrect assumptions about data shapes
+- Incorrect return values or missing return statements
+
+### 2. Security
+- Injection vulnerabilities (SQL, command, XSS)
+- Hardcoded secrets, exposed credentials
+- Unsafe input handling, missing validation
+- Insecure dependencies or configurations
+
+### 3. Error Handling
+- Missing try/catch around operations that can fail
+- Swallowed errors, uninformative error messages
+- Unhandled promise rejections or missing async error paths
+- Missing cleanup in error paths (file handles, connections)
+
+### 4. Performance
+- Unnecessary loops, repeated computations
+- Memory leaks, unclosed resources
+- N+1 queries, blocking operations in async code
+- Inefficient data structures or algorithms
+
+### 5. Readability & Maintainability
+- Confusing naming, overly complex logic
+- Code duplication that should be extracted
+- Functions doing too many things
+- Missing or misleading comments on non-obvious logic
+
+## Output Format
+
+For each issue found, report:
+- **File and line**: exact location
+- **Severity**: Critical / Warning / Suggestion
+- **Issue**: what's wrong
+- **Fix**: how to fix it with a code snippet
+
+End with a summary table counting issues by severity per file.
+
+## Guidelines
+
+- Read each file fully before reporting issues
+- Focus on real problems, not style nitpicks
+- Prioritize Critical issues first
+- If no issues are found in a category, skip it
+- Provide actionable fixes, not vague suggestions

package/dist/utils/display.js

@@ -0,0 +1,125 @@
+import { marked } from "marked";
+import { markedTerminal } from "marked-terminal";
+import { cleanMarkdownRemnants, formatToolCall, } from "./formatting.js";
+marked.use(markedTerminal({ showSectionPrefix: false }));
+const MAX_DIFF_LINES = 30;
+function showEditDiff(input) {
+    const filePath = typeof input.file_path === "string" ? input.file_path : "unknown";
+    const oldStr = typeof input.old_string === "string" ? input.old_string : null;
+    const newStr = typeof input.new_string === "string" ? input.new_string : null;
+    if (oldStr === null || newStr === null)
+        return;
+    const oldLines = oldStr.split("\n");
+    const newLines = newStr.split("\n");
+    const totalLines = oldLines.length + newLines.length;
+    // Show short file path (last 2 segments)
+    const pathSegments = filePath.split("/");
+    const shortPath = pathSegments.length >= 2 ? pathSegments.slice(-2).join("/") : filePath;
+    console.log(`\x1b[2m  ┌─ ${shortPath}\x1b[0m`);
+    const truncated = totalLines > MAX_DIFF_LINES;
+    const maxOld = truncated ? Math.floor(MAX_DIFF_LINES / 2) : oldLines.length;
+    const maxNew = truncated ? Math.floor(MAX_DIFF_LINES / 2) : newLines.length;
+    for (let i = 0; i < Math.min(oldLines.length, maxOld); i++) {
+        console.log(`\x1b[31m  - ${oldLines[i]}\x1b[0m`);
+    }
+    for (let i = 0; i < Math.min(newLines.length, maxNew); i++) {
+        console.log(`\x1b[32m  + ${newLines[i]}\x1b[0m`);
+    }
+    if (truncated) {
+        const remainingLines = totalLines - maxOld - maxNew;
+        console.log(`\x1b[2m  ... ${remainingLines} more lines\x1b[0m`);
+    }
+    console.log(`\x1b[2m  └─\x1b[0m`);
+}
+async function handleContentBlock(block) {
+    if (typeof block !== "object" || block === null)
+        return;
+    const b = block;
+    if (b.type === "thinking" && typeof b.thinking === "string") {
+        console.log("\n\x1b[2m💭 Thinking:\x1b[0m");
+        let thinking = b.thinking;
+        if (thinking.length > 1000) {
+            thinking = thinking.slice(0, 997) + "...";
+        }
+        console.log(`\x1b[2m${thinking}\x1b[0m\n`);
+        return;
+    }
+    if (b.type === "tool_use" && typeof b.name === "string") {
+        const input = (typeof b.input === "object" && b.input !== null)
+            ? b.input
+            : {};
+        console.log(`\n\x1b[36m🔧 ${formatToolCall(b.name, input)}\x1b[0m`);
+        if (b.name === "Edit") {
+            showEditDiff(input);
+        }
+        return;
+    }
+    if (typeof b.text === "string") {
+        const textContent = b.text;
+        try {
+            const rendered = await marked.parse(textContent);
+            process.stdout.write(cleanMarkdownRemnants(rendered));
+        }
+        catch (error) {
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            console.error(`\x1b[33m⚠ Markdown rendering failed: ${errorMsg}\x1b[0m`);
+            console.error("\x1b[2m  (Set DEBUG=1 for stack trace)\x1b[0m");
+            if (process.env.DEBUG && error instanceof Error) {
+                console.error(error.stack);
+            }
+            // Fallback: strip ANSI/control chars and output as plain text
+            const sanitized = textContent
+                .replaceAll(/\x1b\[[0-9;]*m/g, "")
+                .replaceAll(/[\x00-\x08\x0B-\x1F\x7F-\x9F]/g, "");
+            process.stdout.write(sanitized + "\n");
+        }
+    }
+}
+function handleToolResult(message) {
+    if (typeof message.tool_use_result !== "object" || message.tool_use_result === null)
+        return;
+    const result = message.tool_use_result;
+    if ("stderr" in result && typeof result.stderr === "string") {
+        const stderrTrimmed = result.stderr.trim();
+        if (stderrTrimmed.length > 0) {
+            console.log(`\x1b[31m   ${stderrTrimmed}\x1b[0m`);
+        }
+    }
+}
+function handleToolProgress(message) {
+    console.log(`\x1b[33m⏳ ${message.tool_name} (${message.elapsed_time_seconds}s)\x1b[0m`);
+}
+function handleResult(message) {
+    if (message.is_error) {
+        const errorDetail = message.errors && message.errors.length > 0 ? message.errors.join(", ") : "unknown error";
+        console.log(`\n\x1b[31m❌ Failed: ${errorDetail}\x1b[0m`);
+    }
+    else {
+        console.log("\n\x1b[32m✅ Done\x1b[0m");
+    }
+    console.log(`   Turns: ${message.num_turns}`);
+    console.log(`   Duration: ${(message.duration_ms / 1000).toFixed(1)}s`);
+    console.log(`   Cost: $${message.total_cost_usd.toFixed(4)}`);
+}
+export async function showMessage(message) {
+    const msgType = message.type;
+    if (msgType === "assistant") {
+        const msg = message;
+        if (msg.message?.content && Array.isArray(msg.message.content)) {
+            for (const block of msg.message.content) {
+                await handleContentBlock(block);
+            }
+        }
+    }
+    else if (msgType === "user") {
+        if (message.tool_use_result) {
+            handleToolResult(message);
+        }
+    }
+    else if (msgType === "tool_progress") {
+        handleToolProgress(message);
+    }
+    else if (msgType === "result") {
+        handleResult(message);
+    }
+}

package/dist/utils/formatting.js

@@ -0,0 +1,46 @@
+export function truncate(value, max) {
+    if (!Number.isInteger(max) || max < 3) {
+        throw new Error("max must be an integer >= 3 to accommodate ellipsis");
+    }
+    const chars = Array.from(value);
+    if (chars.length <= max)
+        return value;
+    return chars.slice(0, max - 3).join("") + "...";
+}
+export function stripAnsiCodes(text) {
+    return text.replaceAll(/\x1b\[[0-9;]*m/g, "");
+}
+// Sanitize for single-line display: removes control chars, ANSI codes, and converts whitespace to spaces
+function sanitize(str) {
+    return String(str)
+        .replaceAll(/[\x00-\x08\x0B-\x1F\x7F-\x9F]/g, "")
+        .replaceAll(/\x1b\[[0-9;]*m/g, "")
+        .replaceAll(/[\r\n\t]/g, " ")
+        .trim();
+}
+export function cleanMarkdownRemnants(text) {
+    return text
+        .replaceAll(/\*\*(.+?)\*\*/g, "\x1b[1m$1\x1b[22m") // **bold**
+        .replaceAll(/\*(.+?)\*/g, "\x1b[3m$1\x1b[23m") // *italic*
+        .replaceAll(/`([^`]+)`/g, "\x1b[36m$1\x1b[39m"); // `code`
+}
+const toolFormatters = {
+    Bash: (input) => `Bash > ${sanitize(input.command)}`,
+    Read: (input) => `Read > ${sanitize(input.file_path)}`,
+    Write: (input) => `Write > ${sanitize(input.file_path)}`,
+    Edit: (input) => `Edit > ${sanitize(input.file_path)}`,
+    Glob: (input) => `Glob > ${sanitize(input.pattern)}${input.path ? ` in ${sanitize(input.path)}` : ""}`,
+    Grep: (input) => `Grep > "${sanitize(input.pattern)}"${input.path ? ` in ${sanitize(input.path)}` : ""}`,
+    WebSearch: (input) => `WebSearch > "${sanitize(input.query)}"`,
+    WebFetch: (input) => `WebFetch > ${sanitize(input.url)}`,
+};
+const DEFAULT_TERMINAL_WIDTH = 100;
+const TOOL_DISPLAY_PADDING = 20;
+export function formatToolCall(name, input) {
+    const formatter = toolFormatters[name];
+    if (formatter)
+        return formatter(input);
+    const columns = process.stdout.columns ?? DEFAULT_TERMINAL_WIDTH;
+    const maxWidth = Math.max(20, columns - TOOL_DISPLAY_PADDING);
+    return `${name} > ${truncate(JSON.stringify(input), maxWidth)}`;
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "code-review-agent-cli",
+  "version": "1.0.0",
+  "type": "module",
+  "bin": {
+    "code-review-agent": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "start": "FORCE_COLOR=1 tsx index.ts",
+    "build": "npx tsc && cp -r prompts dist/prompts && cp -r skills dist/skills",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.41",
+    "commander": "^13.1.0",
+    "marked": "^15.0.12",
+    "marked-terminal": "^7.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}