/codebase-argus

name: codebase-argus
description: Portable Codebase Argus agent playbook for evidence-first multi-agent review of GitHub pull requests, CI failures, GitHub Actions logs, GitHub App webhook review, /argus PR comment commands, autofix branch planning, OpenAI/Claude/Gemini/Codex provider tribunals, downstream merge/rebase work, and long-lived fork sync against an upstream repository.
version: 0.2.0
metadata:
  origin: local
  owner: aaron
  openclaw:
    requires:
      bins:
        - node
        - npm
        - git
    envVars:
      - name: GITHUB_TOKEN
        required: false
        description: Optional GitHub token for private repositories, higher API limits, and GitHub Actions log fetches.
      - name: OPENAI_API_KEY
        required: false
        description: Optional key for OpenAI API reviews.
      - name: ANTHROPIC_API_KEY
        required: false
        description: Optional key for Anthropic API reviews.
      - name: GEMINI_API_KEY
        required: false
        description: Optional key for Gemini API reviews.
      - name: GITHUB_WEBHOOK_SECRET
        required: false
        description: Optional GitHub App webhook secret when deploying the review server.
      - name: GITHUB_APP_ID
        required: false
        description: Optional GitHub App id when deploying the review server.
      - name: GITHUB_APP_PRIVATE_KEY
        required: false
        description: Optional GitHub App private key when deploying the review server.
      - name: GITHUB_APP_PRIVATE_KEY_BASE64
        required: false
        description: Optional base64-encoded GitHub App private key.
    emoji: "👁️"
    homepage: https://github.com/AaronZ345/codebase-argus

Codebase Argus

Use this portable agent playbook for evidence-first codebase review across GitHub PRs, CI failures, and downstream fork integration work. It works as an OpenClaw/ClawHub skill, Codex project instruction, Claude Code project instruction, or a plain Markdown playbook for any coding agent that can run local shell commands.

Both upstream and downstream workflows can send the same evidence package to one provider or a multi-agent tribunal.

Fast Path

From a Codebase Argus checkout:

npm install
npm run argus -- review owner/repo#123

For private repositories or higher GitHub API limits:

GITHUB_TOKEN=<read-only-token> npm run argus -- review owner/repo#123

Do not print tokens. Do not write tokens to files.

For a read-only GitHub Actions job summary, use the companion Action:

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

Upstream PR Review

Default review is deterministic and rule-based:

npm run argus -- review owner/repo#123 --format markdown

Use a policy file when the repository has local rules:

npm run argus -- review owner/repo#123 --policy .codebase-argus.yml

Use API providers when credentials are available in the environment:

OPENAI_API_KEY=<key> npm run argus -- review owner/repo#123 --provider openai-api
ANTHROPIC_API_KEY=<key> npm run argus -- review owner/repo#123 --provider anthropic-api
GEMINI_API_KEY=<key> npm run argus -- review owner/repo#123 --provider gemini-api

Use local CLI providers only in trusted local workspaces:

npm run argus -- review owner/repo#123 --provider codex-cli
npm run argus -- review owner/repo#123 --provider claude-cli
npm run argus -- review owner/repo#123 --provider gemini-cli

For multi-agent review:

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

Treat output as review assistance. Do not approve, merge, push, or post comments automatically unless the user explicitly asks.

CI Failure Review

When the user provides a failing job log or local log file, review it through the same provider system:

npm run argus -- ci-log logs/failure.txt
npm run argus -- ci-log logs/failure.txt --provider codex-cli
npm run argus -- ci-log logs/failure.txt --tribunal codex-cli,claude-cli,gemini-cli

When the user points at a GitHub PR with failing Actions checks, fetch the job logs directly:

GITHUB_TOKEN=<read-only-token> npm run argus -- ci-github owner/repo#123
GITHUB_TOKEN=<read-only-token> npm run argus -- ci-github owner/repo#123 --provider codex-cli

Focus on the first failing command, the most likely root cause, and the smallest fix that can be verified locally.

Autofix Plan

Use `autofix-plan` when the user asks for suggested fixes, safe automatic repair, or a branch plan for narrow mechanical failures:

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

The plan covers gated lanes such as npm lockfile refreshes, snapshot updates, and formatter/linter fixes. Treat it as a command plan; do not execute, push, or open a PR unless the user explicitly asks.

GitHub App Webhook Review

For automatic PR review, the deployed Next.js server exposes:

POST /api/github/webhook
GET /api/github/app-manifest

Required environment:

GITHUB_WEBHOOK_SECRET=<secret>
GITHUB_APP_ID=<app-id>
GITHUB_APP_PRIVATE_KEY=<pem-or-escaped-pem>

Use `GITHUB_APP_PRIVATE_KEY_BASE64` if storing multiline PEM is awkward. The webhook verifies `X-Hub-Signature-256`, reviews `opened`, `reopened`, `ready_for_review`, and `synchronize`, ignores draft PRs, posts `COMMENT` reviews only, and can add inline comments when `ARGUS_WEBHOOK_INLINE_COMMENTS=true`.

Supported PR comment commands:

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

`/argus pause` applies `argus:paused`; automatic review skips PRs with that label. `/argus resume` removes it.

Do not approve, request changes, merge, push, or post comments outside this configured webhook path unless the user explicitly asks.

What To Look For

Prioritize findings with concrete evidence:

• failing or pending checks;
• source changes wi