Codebase Argus

Multi-agent PR review and downstream fork-sync risk analysis for maintainers.

Live demo · CLI · GitHub App · Agent Playbook

Codebase Argus gives maintainers a review desk for codebase evidence. It reviews
pull requests, failing CI logs, and long-lived fork syncs with the same set of
signals: patches, checks, files, branch state, policy gates, provider consensus,
and local git simulations.

Use it when a single reviewer is not enough, but a fully automatic merge bot is
too risky. Argus can ask one model, several models, or local AI CLIs to review
the same evidence, then keeps every finding tied to something a maintainer can
check.

At a glance

Common workflows

Review a risky PR with multiple agents

npm run argus -- review owner/repo#123 --tribunal openai-api,claude-cli,codex-cli

Argus fetches the PR metadata, changed files, checks, reviews, commits, and
patch excerpts, then asks every configured reviewer to look at the same context.
Matching findings are grouped so agreement is visible; provider failures stay in
the report instead of disappearing.

Debug failing GitHub Actions logs

GITHUB_TOKEN=... npm run argus -- ci-github owner/repo#123 --provider codex-cli

The CI lane pulls failing job logs from GitHub Actions and asks for the first
failing command, likely root cause, affected files, and the smallest fix path.

Check whether a fork can safely rebase

npm run argus -- downstream owner/upstream me/fork --fork-branch feature/demo --tribunal codex-cli,claude-cli,gemini-cli

The downstream lane compares the fork with upstream, projects merge conflicts
with git merge-tree, simulates a rebase in a temporary worktree, checks
patch-equivalent commits with git cherry, and summarizes semantic movement
with git range-diff.

Quick start

npm install
npm run dev

Open http://localhost:3000.

For command-line review:

npm run argus -- review owner/repo#123
npm run argus -- ci-github owner/repo#123
npm run argus -- downstream owner/upstream me/fork

Public GitHub repositories work from the hosted demo. Private repositories,
server-side AI providers, GitHub App webhooks, local git analysis, and CLI agent
review belong in a local or deployed server environment.

Core capabilities

Pull request review

Codebase Argus fetches the PR shape that maintainers usually need before
trusting a review:

• metadata, labels, author, branch refs, and mergeability;
• changed files, patch excerpts, commits, and prior reviews;
• check status and GitHub Actions run metadata;
• policy rules from .codebase-argus.yml;
• stacked PR signals and merge-queue states.

The deterministic reviewer looks for failing checks, source changes without
tests, workflow edits, dependency changes, sensitive paths, policy violations,
large diffs, stacked PR bases, and blocked/dirty/behind/unstable merge states.

Multi-agent review and tribunal

The same upstream or downstream evidence package can go to one provider or
several providers:

Tribunal mode runs multiple reviewers against the same PR, CI log, or fork sync
context. It groups matching findings, raises confidence when providers agree,
and keeps provider failures in the report.

CI failures

Use ci-log for a local file, or ci-github for failing GitHub Actions jobs on
a PR. Webhook mode can include failing Actions logs in the automatic PR review.

Autofix planning

autofix-plan turns high-confidence, mechanical findings into a branch plan. It
covers narrow lanes such as npm lockfile refreshes, snapshot updates, and
formatter or linter fixes. The output includes commands, verification gates, and
push instructions for the maintainer or agent working in a real checkout.

Downstream fork sync

The fork workflow compares an upstream repository and a long-lived fork. Local
analysis runs git in .cache/repos and temporary worktrees, then reports:

• projected merge conflicts from git merge-tree;
• rebase simulation in a temporary worktree;
• patch-equivalent commits from git cherry;
• semantic movement from git range-diff;
• fork-ahead commits already covered upstream;
• agent-safe merge/rebase runbooks.

CLI

The CLI is the best entry point for scripts and coding agents.

npm run argus -- --help

PR review

npm run argus -- review owner/repo#123
npm run argus -- review owner/repo#123 --policy .codebase-argus.yml
npm run argus -- review owner/repo#123 --provider openai-api --model gpt-4.1-mini
npm run argus -- review owner/repo#123 --tribunal openai-api,claude-cli,codex-cli

CI review

npm run argus -- ci-log logs/failure.txt
npm run argus -- ci-log logs/failure.txt --provider codex-cli
GITHUB_TOKEN=... npm run argus -- ci-github owner/repo#123

Autofix plan

npm run argus -- autofix-plan owner/repo#123

Downstream fork sync

npm run argus -- downstream owner/upstream me/fork
npm run argus -- downstream owner/upstream me/fork --upstream-branch main --fork-branch feature/demo
npm run argus -- downstream owner/upstream me/fork --fork-branch feature/demo --provider codex-cli

Sync planning

npm run argus -- sync owner/upstream me/fork --mode merge --fork-branch feature/demo --test "npm test"
npm run argus -- sync owner/upstream me/fork --mode rebase --fork-branch feature/demo --execute --push --create-pr

Output defaults to markdown. Use --format json for tool integration.

Install the binary locally:

npm link
codebase-argus review owner/repo#123
codebase-argus autofix-plan owner/repo#123

downstream is the primary fork-sync review command. sync is reserved for
explicit integration branches.

Policy file

Add .codebase-argus.yml when the repository has local review rules:

requiredChecks: passing
maxChangedFiles: 30
maxTotalDelta: 1200
requiredTestPatterns:
  - .test.ts
forbiddenWorkflowPatterns:
  - pull_request_target
sensitivePathPatterns:
  - auth
  - token
  - webhook

Policy failures become normal findings with concrete evidence.

GitHub App

Deploy the Next.js server and point a GitHub App webhook at:

POST https://your-host.example.com/api/github/webhook

The server also emits a GitHub App manifest:

GET https://your-host.example.com/api/github/app-manifest

Recommended repository permissions:

Required webhook events:

• pull_request
• issue_comment

Server environment:

GITHUB_WEBHOOK_SECRET=...
GITHUB_APP_ID=...
GITHUB_APP_PRIVATE_KEY='<escaped-pem-private-key>'

Base64 private key storage is also supported:

GITHUB_APP_PRIVATE_KEY_BASE64=...

Review controls:

ARGUS_WEBHOOK_PROVIDER=rule-based
ARGUS_WEBHOOK_PROVIDER=openai-api
ARGUS_WEBHOOK_MODEL=gpt-4.1-mini
ARGUS_WEBHOOK_TRIBUNAL=openai-api,claude-cli,codex-cli
ARGUS_WEBHOOK_INLINE_COMMENTS=true
ARGUS_WEBHOOK_INCLUDE_CI_LOGS=true
ARGUS_WEBHOOK_DRY_RUN=true

Webhook behavior:

• verifies X-Hub-Signature-256 before payload handling;
• reviews opened, reopened, ready_for_review, and synchronize events;
• skips draft PRs and PRs labeled argus:paused;
• uses GitHub App installation tokens when app credentials are present;
• posts GitHub PR reviews with event COMMENT;
• anchors high-signal findings to changed patch lines when inline comments are enabled;
• fetches failing GitHub Actions job logs when checks fail.

PR comment commands

/argus help
/argus review
/argus ci
/argus autofix
/argus pause
/argus resume

/argus pause applies the argus:paused label. /argus resume removes it.
/argus autofix posts the same gated plan as the CLI.

AI provider setup

Set credentials for the providers you plan to use:

OPENAI_API_KEY=...
ANTHROPIC_API_KEY=...
GEMINI_API_KEY=...

Optional model overrides:

ARGUS_OPENAI_API_MODEL=gpt-4.1-mini
ARGUS_ANTHROPIC_API_MODEL=claude-3-5-sonnet-20241022
ARGUS_GEMINI_API_MODEL=gemini-2.0-flash

Local CLI providers expect authenticated commands:

codex exec --help
claude --help
gemini --help

Agent playbook

The repository includes a portable agent playbook. It is not tied to Codex:
OpenClaw, Codex, Claude Code, and other coding agents can all use the same
instructions.

agent-playbooks/codebase-argus/PLAYBOOK.md   # portable OpenClaw / Codex / Claude Code playbook
skills/codebase-argus/SKILL.md               # Codex adapter with skill metadata

Recommended setup:

• OpenClaw: add agent-playbooks/codebase-argus/PLAYBOOK.md to the agent or
  project instructions.
• Codex: either read the portable playbook directly or install the Codex adapter
  from skills/codebase-argus/.
• Claude Code: reference the portable playbook from the project instructions, or
  import it into whichever local skill/custom-instruction layout you use.

The playbook directs agents to use the CLI first, keep tokens out of logs, run
multi-provider review before risky downstream integration, and ask for explicit
authorization before approve, merge, rebase, push, PR creation, or GitHub
comments.

Write model

Codebase Argus keeps write operations narrow: