AI-powered automated code review CLI tool using Claude Agent SDK with multi-agent orchestration.
English | 中文
- Multi-Agent Parallel Review - 4 specialized agents run concurrently: security, logic, performance, style
- Smart Agent Selection - Automatically selects agents based on file characteristics
- Issue Validation - Challenge-mode multi-round validation significantly reduces false positives
- Realtime Deduplication - Two-layer dedup: fast rule-based check + LLM semantic verification
- Project Standards Aware - Auto-extracts ESLint/TypeScript/Prettier configs
- Custom Rules - Team-specific review rules and checklists
- Incremental Review - Only review new commits for better efficiency
- Service Integration - JSON event stream output for CI/CD and external service integration
npm install -g code-argusnpx code-argus review /path/to/repo feature-branch maingit clone https://github.com/anthropics/code-argus.git
cd code-argus/core
npm install
npm run build
npm linkSet your Anthropic API key:
# Option 1: Environment variable
export ANTHROPIC_API_KEY=your-api-key
# Option 2: .env file
echo "ANTHROPIC_API_KEY=your-api-key" > .env
# Option 3: Using config command (recommended)
argus config set api-key sk-ant-xxx# Set configuration
argus config set api-key sk-ant-xxx # API key
argus config set base-url https://proxy # Custom proxy URL
argus config set model claude-sonnet-4-5-20250929 # Model
# View configuration
argus config list # List all config
argus config get api-key # Get single config
argus config path # Show config file path
# Delete configuration
argus config delete base-urlargus <command> <repoPath> <sourceBranch> <targetBranch> [options]| Command | Description |
|---|---|
analyze |
Quick diff analysis (no AI agents) |
review |
Full AI code review (multi-agent parallel review) |
config |
Configuration management |
| Argument | Description |
|---|---|
repoPath |
Path to Git repository |
sourceBranch |
Source branch (PR branch, uses origin/<sourceBranch>) |
targetBranch |
Target branch (base branch, uses origin/<targetBranch>) |
Output JSON event stream for service integration
When enabled, all progress and final report are output as JSON Lines (NDJSON) to stderr, making it easy for external programs to parse.
argus review /repo feature main --json-logsOutput Example:
{"type":"review:start","data":{"repoPath":"/repo","sourceBranch":"feature","targetBranch":"main","agents":["security-reviewer","logic-reviewer"],"timestamp":"2025-01-15T10:00:00.000Z"}}
{"type":"phase:start","data":{"phase":1,"totalPhases":4,"name":"Building review context...","timestamp":"..."}}
{"type":"agent:start","data":{"agent":"security-reviewer","timestamp":"..."}}
{"type":"agent:progress","data":{"agent":"security-reviewer","activity":"Reading file: src/auth.ts","timestamp":"..."}}
{"type":"agent:complete","data":{"agent":"security-reviewer","status":"completed","issuesFound":3,"elapsedMs":5000,"timestamp":"..."}}
{"type":"validation:issue","data":{"issueId":"sql-injection-auth.ts","title":"SQL Injection","file":"src/auth.ts","line":42,"severity":"error","status":"confirmed","description":"User input directly concatenated into SQL query","suggestion":"Use parameterized queries instead","timestamp":"..."}}
{"type":"review:complete","data":{"totalIssues":5,"elapsedMs":30000,"timestamp":"..."}}
{"type":"report","data":{"report":{"issues":[...],"metrics":{...},"metadata":{...}},"timestamp":"..."}}Event Types:
| Event Type | Description |
|---|---|
review:start |
Review started, includes repo, branches, agent list |
review:complete |
Review completed, includes total issues and elapsed time |
review:error |
Review failed, includes error message |
phase:start |
Phase started (build context, run agents, validate, generate report) |
phase:complete |
Phase completed |
agent:start |
Agent started running |
agent:progress |
Agent activity (reading files, searching code, etc.) |
agent:complete |
Agent completed, includes issues found count |
validation:start |
Validation started |
validation:progress |
Validation progress |
validation:issue |
Issue validation result (confirmed/rejected/uncertain) |
validation:complete |
Validation completion statistics |
log |
Log message |
report |
Final report (includes complete review results) |
Service Integration Example:
import { spawn } from 'child_process';
const child = spawn('argus', ['review', repo, source, target, '--json-logs']);
child.stderr.on('data', (chunk) => {
for (const line of chunk.toString().split('\n').filter(Boolean)) {
const event = JSON.parse(line);
switch (event.type) {
case 'agent:start':
updateUI(`Agent ${event.data.agent} started...`);
break;
case 'agent:complete':
updateUI(`Agent ${event.data.agent} completed, found ${event.data.issuesFound} issues`);
break;
case 'validation:issue':
if (event.data.status === 'confirmed') {
addIssue(event.data);
}
break;
case 'report':
// Final report - review completed
saveReport(event.data.report);
break;
}
}
});Output language
| Value | Description |
|---|---|
zh |
Chinese (default) |
en |
English |
argus review /repo feature main --language=enIncremental review mode
Only review commits added since the last review, significantly improving review efficiency.
# First review (full review)
argus review /repo feature main
# Subsequent review (only new commits)
argus review /repo feature main --incrementalHow it works:
- First review records the current source branch SHA
- Subsequent
--incrementalreviews only analyze new commits - If no new commits, it will notify and skip the review
- Review state is saved in
~/.argus/reviews/directory
Reset review state
Clear previous review records and force a full review.
# Reset and perform full review
argus review /repo feature main --reset-state
# Reset then enable incremental (first run will be full review)
argus review /repo feature main --reset-state --incrementalSkip issue validation
Skip challenge-mode validation to speed up review, but may increase false positives.
argus review /repo feature main --skip-validationUse cases:
- Quick preview of review results
- Fast checks in CI/CD
- Scenarios with higher tolerance for false positives
Note: Not recommended for formal reviews. Validation filters approximately 30-50% of false positives.
Configuration directory
Specify a config directory that auto-loads rules/ and agents/ subdirectories.
argus review /repo feature main --config-dir=./.ai-reviewDirectory structure:
.ai-review/
├── rules/ # Supplement built-in agent rules
│ ├── global.md # Global rules (apply to all agents)
│ ├── security.md # Security review rules
│ ├── logic.md # Logic review rules
│ ├── style.md # Style review rules
│ ├── performance.md # Performance review rules
│ └── checklist.yaml # Custom checklist
└── agents/ # Custom agents (domain-specific review)
├── component-plugin.yaml
└── api-security.yaml
Custom rules directory
Specify a rules directory separately. Can be used multiple times.
# Single rules directory
argus review /repo feature main --rules-dir=./team-rules
# Multiple rules directories (merged in order)
argus review /repo feature main --rules-dir=./base-rules --rules-dir=./team-rulesRules file format (Markdown):
# Security Review Rules
## Must Check
- All user input must be validated and escaped
- Prohibit use of eval() and new Function()
- SQL queries must use parameterized queries
## Best Practices
- Use Content-Security-Policy headers
- Store sensitive data with encryptionCustom agents directory
Specify a custom agent definitions directory. Can be used multiple times.
argus review /repo feature main --agents-dir=./custom-agentsAgent definition file format (YAML):
name: api-security
description: API security review specialist
trigger_mode: rule # rule | llm | hybrid
triggers:
files:
- '**/api/**/*.ts'
- '**/routes/**/*.ts'
exclude_files:
- '**/*.test.ts'
- '**/*.spec.ts'
prompt: |
You are an API security review expert. Check for:
1. Authentication and Authorization
- Is user identity properly verified
- Are user permissions checked
2. Input Validation
- Are request parameters validated for type and range
- Is injection attack prevention in place
3. Response Security
- Is sensitive information leaked
- Are error messages too detailed
output:
category: security
default_severity: errorVerbose output mode
Output more debug information, including agent selection reasons, tool call details, etc.
argus review /repo feature main --verbose# Quick diff analysis (no AI)
argus analyze /path/to/repo feature-branch main
# Full AI code review
argus review /path/to/repo feature-branch main
# English output
argus review /path/to/repo feature-branch main --language=en# First review
argus review /repo feature main
# After pushing new code, only review new changes
argus review /repo feature main --incremental
# Force full review
argus review /repo feature main --reset-state# Using config directory
argus review /repo feature main --config-dir=./.ai-review
# Specify rules and agents separately
argus review /repo feature main \
--rules-dir=./company-rules \
--agents-dir=./domain-agents
# Multi-layer config merge
argus review /repo feature main \
--config-dir=./base-config \
--rules-dir=./team-overrides# JSON event stream output
argus review /repo feature main --json-logs 2>events.jsonl
# Fast check (skip validation)
argus review /repo feature main --skip-validation --json-logs
# Incremental CI check
argus review /repo feature main --incremental --json-logssrc/
├── index.ts # CLI entry, command parsing
├── cli/
│ ├── progress.ts # Interactive progress output
│ ├── events.ts # Event type definitions
│ └── structured-progress.ts # JSON event stream output
├── review/
│ ├── orchestrator.ts # Main review orchestrator
│ ├── streaming-orchestrator.ts # Streaming review mode
│ ├── agent-selector.ts # Smart agent selection
│ ├── validator.ts # Issue validation (challenge mode)
│ ├── realtime-deduplicator.ts # Realtime deduplication
│ ├── deduplicator.ts # Batch semantic dedup
│ ├── aggregator.ts # Issue aggregation
│ ├── report.ts # Report generation
│ ├── state-manager.ts # Incremental review state management
│ ├── prompts/ # Agent prompt building
│ ├── standards/ # Project standards extraction
│ ├── rules/ # Custom rules loading
│ ├── custom-agents/ # Custom agent loading
│ └── types.ts # Type definitions
├── git/
│ ├── diff.ts # Git diff operations
│ ├── parser.ts # Diff parsing
│ └── commits.ts # Commit history
├── llm/
│ ├── factory.ts # LLM provider factory
│ └── providers/ # Claude/OpenAI implementations
└── analyzer/
├── local-analyzer.ts # Local fast analysis
└── diff-analyzer.ts # LLM semantic analysis
.claude/agents/ # Built-in agent prompt definitions
├── security-reviewer.md # Security review
├── logic-reviewer.md # Logic review
├── style-reviewer.md # Style review
├── performance-reviewer.md # Performance review
└── validator.md # Issue validation
┌─────────────────┐
│ 1. Build Context │ Get Diff → Parse Files → Extract Project Standards
└────────┬────────┘
▼
┌─────────────────┐
│ 2. Smart Select │ Select needed agents based on file characteristics
└────────┬────────┘
▼
┌─────────────────┐
│ 3. Parallel Review │ 4 agents run concurrently + realtime dedup
└────────┬────────┘
▼
┌─────────────────┐
│ 4. Validation │ Challenge-mode multi-round validation, filter false positives
└────────┬────────┘
▼
┌─────────────────┐
│ 5. Generate Report │ Aggregate issues, generate structured report
└─────────────────┘
Uses git diff origin/target...origin/source:
main: A --- B --- C
\
feature: D --- E
- Only shows changes in D and E (actual source branch changes)
- Excludes other commits on target branch
Two-layer deduplication mechanism:
- Rule Layer - Same file + overlapping lines → fast check
- LLM Layer - Semantic similarity → precise dedup
Challenge mode: Validator agent attempts to "challenge" discovered issues
- Verify if code location is correct
- Verify if issue description is accurate
- Verify if it's a real issue vs false positive
# Development
npm run dev -- <command> ... # Run CLI
npm run exec src/file.ts # Run any TS file
# Build
npm run build # Compile to dist/
npm run type-check # Type checking
# Code Quality
npm run lint # ESLint check
npm run lint:fix # Auto-fix
npm run format # Prettier format
npm run format:check # Check format
# Testing
npm run test # Watch mode
npm run test:run # Run once
npm run test:coverage # Coverage reportUsing Conventional Commits:
git commit -m "feat: add new feature"
git commit -m "fix: resolve bug"
git commit -m "docs: update documentation"Types: feat, fix, docs, style, refactor, perf, test, chore
MIT