Codebase Argus

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.

Try it on a public PR

The shortest useful path is a local, read-only review. No model key is needed for the deterministic pass.

git clone https://github.com/AaronZ345/codebase-argus.git
cd codebase-argus
npm ci
npm run argus -- review zhayujie/CowAgent#2965

To give the same evidence to an installed Codex CLI:

npm run argus -- review zhayujie/CowAgent#2965 --provider codex-cli

The CowAgent #2965 case study records both passes: low risk, no blocking issue, and one remaining integration-test boundary for a maintainer to judge.

Run it in pull requests

The companion Codebase Argus Action puts the deterministic review in a workflow job summary. It is read-only by default and needs no model key.

- uses: AaronZ345/codebase-argus-action@v1
  with:
    pull-request: ${{ github.repository }}#${{ github.event.pull_request.number }}

The Action also exposes failing-CI diagnosis, autofix planning, optional agent providers, and a pinned core-ref.

At a glance

Workflow	Input	Output
PR review	owner/repo#123 or a GitHub PR URL	risk summary, findings, inline-ready comments
CI review	local log file or failing GitHub Actions jobs	likely root cause, affected command, fix path
Autofix plan	PR review findings	gated branch plan for mechanical fixes
Downstream fork sync	upstream repo + fork repo	ahead/behind, conflict notes, rebase/merge risk
Agent handoff	dashboard or CLI report	task package with commands and acceptance gates

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.

Run the dashboard locally

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:

Provider	Mode
openai-api	API
anthropic-api	API
gemini-api	API
codex-cli	local CLI
claude-cli	local CLI
gemini-cli	local CLI

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:

Permission	Access
Pull requests	Read and write
Issues	Read and write
Contents	Read
Checks	Read
Actions	Read
Metadata	Read

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               # ClawHub/OpenClaw-compatible skill entrypoint

Recommended setup:

• OpenClaw: add agent-playbooks/codebase-argus/PLAYBOOK.md to the agent or project instructions, or install the skill from skills/codebase-argus/.

• Codex: either read the portable playbook directly or install the skill from skills/codebase-argus/.

• Claude Code: install the plugin marketplace from this repository:

  /plugin marketplace add AaronZ345/codebase-argus
  /plugin install codebase-argus@codebase-argus
  

  Or copy the playbook into .claude/skills/codebase-argus/SKILL.md for a project-local skill.

Skill registries

Codebase Argus is packaged for open SKILL.md registries and agent-specific install surfaces:

• Claude Code plugin marketplace: AaronZ345/codebase-argus
• ClawHub/OpenClaw skill folder: skills/codebase-argus
• Codex/OpenAI-compatible Agent Skills folder: skills/codebase-argus
• SkillsMD public registry repository: AaronZ345/codebase-argus

ClawHub publish command:

clawhub skill publish skills/codebase-argus \
  --slug codebase-argus \
  --name "Codebase Argus" \
  --version 0.1.0 \
  --tags latest,code-review,pull-request,ci,multi-agent,fork-sync

SkillsMD submission payload:

{
  "repo": "AaronZ345/codebase-argus",
  "name": "codebase-argus",
  "description": "Multi-agent PR, CI, and downstream fork-sync review desk for coding agents."
}

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:

Surface	Write behavior
Hosted demo	Read-only browser inspection
Local CLI review	Markdown or JSON output
GitHub App review	COMMENT PR reviews
PR commands	Review, CI review, autofix plan, pause, resume
Sync command	Dry-run by default; --execute, --push, and --create-pr are explicit gates
Generated Actions workflow	Uses pull_request for untrusted fork PRs