CACodebase Argus

Coordinate multi-agent codebase review across PRs, CI, and fork syncs.

Upstream maintainers get PR and CI tribunals. Downstream maintainers get merge or rebase evidence, agent handoff packages, and gated sync branches.

Overall

Evidence-first tribunal

Multiple agents can review the same files, checks, patch lines, policy gates, and local git output. Consensus raises confidence; execution still requires explicit CLI flags.

Upstream

PR and CI tribunal

Review pull requests and CI logs with deterministic checks, policy as code, API models, local AI CLIs, or a multi-agent tribunal.

Downstream

Fork sync tribunal

Compare a fork with upstream, project merge conflicts, simulate rebase, ask multiple agents to choose a path, then run a gated sync branch through the CLI.

Execution

Opt-in sync branch

`sync` prints a plan first. `--execute`, `--push`, and `--create-pr` are separate gates, and pushes target the sync branch.

Queue

Merge queue signals

Review output flags blocked, behind, dirty, and unstable queue states before a maintainer spends review time.

Stack

Stacked PR signals

PRs targeting non-default base branches get dependency review notes so stacked work is reviewed in the right order.

Checks

Direct CI log ingest

`ci-github` fetches failing GitHub Actions job logs and feeds them into the same rule-based, API, CLI, or tribunal reviewers.

Fix

Gated autofix plans

`autofix-plan` prepares lockfile, snapshot, and formatter lanes with explicit verification commands.

GitHub App setup

Generate the manifest, wire the webhook, and use PR comments for review, CI, pause, resume, and autofix plans.

App namePublic server URL

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

Webhookhttps://your-host.example.com/api/github/webhook

Manifest endpoint/api/github/app-manifest

{
  "name": "Codebase Argus",
  "url": "https://your-host.example.com",
  "hook_attributes": {
    "url": "https://your-host.example.com/api/github/webhook"
  },
  "redirect_url": "https://your-host.example.com",
  "callback_urls": [
    "https://your-host.example.com"
  ],
  "public": false,
  "default_permissions": {
    "actions": "read",
    "checks": "read",
    "contents": "read",
    "issues": "write",
    "metadata": "read",
    "pull_requests": "write"
  },
  "default_events": [
    "issue_comment",
    "pull_request"
  ]
}

ModeRead-only

No write scopes, no database, no token persistence.

InputsRepos

Use owner/repo values or GitHub repository URLs.

SignalSync + PRs

Compares branches, open PRs, checks, and cleanup hints.

APIGitHub REST

A real GitHub API integration suitable for iteration.

Upstream PR Review

For upstream maintainers: review a normal GitHub pull request with baseline checks, then hand the same context to Codex, Claude, Gemini, or an API model.

Paste a PR URL, inspect the deterministic baseline, then optionally ask one agent or a tribunal for a structured review.

Downstream Merge/Rebase Risk

Runs local git in a private cache, checks merge-upstream and rebase-upstream evidence, then prepares agent-safe review material before any real sync branch is created.

Hosted demo cannot run local git. Clone the repository and run the app locally to use merge/rebase risk analysis.

Downstream Sync Action

Generate a scheduled workflow for downstream fork sync reports, merge-tree evidence, range-diff, and optional tracking issue comments. Use the CLI `sync` lane when the agent should create a real integration branch.

Schedule cronIssue number, optional

Runs on schedule, manual dispatch, or upstream-updated dispatch.
Uses local git on the runner; no write operation except issue comment.
Reports behind/ahead counts, merge-tree conflicts, cherry evidence, and range-diff.
Actual merge or rebase execution belongs to the opt-in CLI sync command.

name: Codebase Argus Downstream Review

on:
  workflow_dispatch:
    inputs:
      upstream_repo:
        description: Upstream repository as owner/repo
        default: "upstream-owner/repo"
        required: true
      fork_repo:
        description: Fork repository as owner/repo
        default: "fork-owner/repo"
        required: true
      pr_head_repo:
        description: PR head repository as owner/repo
        default: "fork-owner/repo"
        required: true
      upstream_branch:
        description: Upstream branch to compare
        default: "main"
        required: true
      fork_branch:
        description: Fork branch to compare
        default: "main"
        required: true
  schedule:
    - cron: "17 1 * * *"
  repository_dispatch:
    types: [upstream-updated]

permissions:
  contents: read
  issues: write

jobs:
  downstream-review:
    runs-on: ubuntu-latest
    env:
      DEFAULT_UPSTREAM_REPO: "upstream-owner/repo"
      DEFAULT_FORK_REPO: "fork-owner/repo"
      DEFAULT_PR_HEAD_REPO: "fork-owner/repo"
      DEFAULT_UPSTREAM_BRANCH: "main"
      DEFAULT_FORK_BRANCH: "main"
      ARGUS_REPORT_ISSUE: ""
    steps:
      - name: Generate downstream review
        shell: bash
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          set -euo pipefail
          upstream="${{ github.event.inputs.upstream_repo || env.DEFAULT_UPSTREAM_REPO }}"
          fork="${{ github.event.inputs.fork_repo || env.DEFAULT_FORK_REPO }}"
          pr_head="${{ github.event.inputs.pr_head_repo || env.DEFAULT_PR_HEAD_REPO }}"
          upstream_branch="${{ github.event.inputs.upstream_branch || env.DEFAULT_UPSTREAM_BRANCH }}"
          fork_branch="${{ github.event.inputs.fork_branch || env.DEFAULT_FORK_BRANCH }}"
          workdir="$(mktemp -d)"
          trap 'rm -rf "$workdir"' EXIT
          repo_dir="$workdir/downstream.git"
          report="$workdir/codebase-argus-report.md"
          git init --bare "$repo_dir" >/dev/null
          git -C "$repo_dir" remote add upstream "https://github.com/${upstream}.git"
          git -C "$repo_dir" remote add fork "https://github.com/${fork}.git"
          git -C "$repo_dir" fetch --prune upstream "+refs/heads/${upstream_branch}:refs/remotes/upstream/${upstream_branch}"
          git -C "$repo_dir" fetch --prune fork "+refs/heads/${fork_branch}:refs/remotes/fork/${fork_branch}"
          upstream_ref="refs/remotes/upstream/${upstream_branch}"
          fork_ref="refs/remotes/fork/${fork_branch}"
          read -r behind ahead < <(git -C "$repo_dir" rev-list --left-right --count "$upstream_ref...$fork_ref")
          merge_exit=0
          git -C "$repo_dir" merge-tree --write-tree --name-only "$upstream_ref" "$fork_ref" > "$workdir/merge-tree.txt" 2>&1 || merge_exit=$?
          # Patch evidence uses git cherry -v and git range-diff --no-color.
          git -C "$repo_dir" cherry -v "$upstream_ref" "$fork_ref" > "$workdir/cherry.txt" || true
          git -C "$repo_dir" range-diff --no-color "$upstream_ref...$fork_ref" > "$workdir/range-diff.txt" 2>&1 || true
          covered=$(grep -c '^-' "$workdir/cherry.txt" || true)
          unique=$(grep -c '^+' "$workdir/cherry.txt" || true)
          changed=$(grep -cE '^[[:space:]]*[0-9-]+:.* ! ' "$workdir/range-diff.txt" || true)
          conflict_files=$(tail -n +2 "$workdir/merge-tree.txt" | sed '/^$/,$d' || true)
          {
            echo '# Downstream Fork Review'
            echo
            echo "Generated: $(date -u +'%Y-%m-%dT%H:%M:%SZ')"
            echo
            echo "- Upstream: \`$upstream\` branch \`$upstream_branch\`"
            echo "- Fork: \`$fork\` branch \`$fork_branch\`"
            echo "- PR head repo: \`$pr_head\`"
            echo "- Branch delta: $behind behind, $ahead ahead"
            echo "- Patch evidence: $covered covered, $unique unique, $changed changed"
            echo
            if [[ "$merge_exit" -eq 0 ]]; then
              echo '## Merge/Rebase risk'
              echo 'Clean projection from git merge-tree.'
            else
              echo '## Merge/Rebase risk'
              echo 'Potential conflicts from git merge-tree:'
              echo
              if [[ -n "$conflict_files" ]]; then
                while IFS= read -r file; do
                  [[ -n "$file" ]] && echo "- \`$file\`"
                done <<< "$conflict_files"
              else
                echo '- merge-tree returned non-zero; inspect raw output below.'
              fi
            fi
            echo
            echo '## Covered commits'
            grep '^-' "$workdir/cherry.txt" | head -20 | sed 's/^/- /' || true
            echo
            echo '## Unique commits'
            grep '^+' "$workdir/cherry.txt" | head -20 | sed 's/^/- /' || true
            echo
            echo '## Range-diff excerpt'
            echo '```'
            sed -n '1,80p' "$workdir/range-diff.txt"
            echo '```'
          } > "$report"
          cat "$report" >> "$GITHUB_STEP_SUMMARY"
          if [[ -n "$ARGUS_REPORT_ISSUE" ]]; then
            gh issue comment "$ARGUS_REPORT_ISSUE" --repo "$fork" --body-file "$report"
          fi

Downstream Agent Workflow

Export a prompt for merge or rebase preparation, inspect conflict evidence, or hand off the CLI sync path after agent review.

Mode

Task package

# Codebase Argus Agent Task Package

Task ID: `fork-owner-repo-main-inspect`
Generated: 2026-05-10T16:12:48.255Z
Mode: inspect
Risk: not computed

## Mission
Bring `fork-owner/repo` branch `main` up to date with `upstream-owner/repo` branch `main` using the selected gated mode. Review both merge-upstream and rebase-upstream risk before choosing the integration path.

## Inputs
- Upstream: `upstream-owner/repo`
- Upstream branch: `main`
- Fork: `fork-owner/repo`
- Fork branch: `main`

## Risk summary
Run local merge/rebase analysis before prepare or execute mode.

## Conflict dossier
- None reported.

## Patch evidence
- Local git evidence has not been computed yet.

## Forbidden actions
- Do not push unless the mode is execute and every acceptance gate is satisfied.
- Do not close pull requests, delete branches, or rewrite unrelated files.
- Do not resolve files outside the conflict dossier without explicit approval.
- Do not continue after conflicts, failed tests, missing backup, or unexpected remote state.

## Command plan
1. `git remote add upstream https://github.com/upstream-owner/repo.git 2>/dev/null || git remote set-url upstream https://github.com/upstream-owner/repo.git`
2. `git remote add fork https://github.com/fork-owner/repo.git 2>/dev/null || git remote set-url fork https://github.com/fork-owner/repo.git`
3. `git fetch --prune upstream main`
4. `git fetch --prune fork main`
5. `git rev-list --left-right --count upstream/main...fork/main`
6. `git merge-tree --write-tree --name-only upstream/main fork/main`
7. `git cherry -v upstream/main fork/main`

## Acceptance checklist
- Fetch commands completed for upstream and fork.
- Backup branch was created or verified before history rewrite.
- Merge or rebase was attempted only in prepare or execute mode.
- Conflict files are empty, or the run stopped before push.
- Required tests/build commands were run and passed.
- Final branch status was recorded.
- Push safety was explicitly assessed before any force-with-lease.

## Return log format
```text
Fetched refs:
Backup branch:
Merge/rebase command and result:
Conflict files:
Tests/build commands and results:
Final git status:
Push attempted: yes/no
Safe to push: yes/no, with reason
```

Prompt export

You are maintaining a long-lived GitHub fork.

Upstream: upstream-owner/repo (main)
Fork: fork-owner/repo (main)
Mode: inspect

Rules:
- Create or verify a backup branch before any merge, rebase, or history rewrite.
- Do not push, close PRs, delete branches, or rewrite unrelated files unless explicitly authorized.
- If conflicts appear, list files and stop for human confirmation.
- If tests fail, report the failing command and stop.

Risk summary: not computed.

Commands:
1. git remote add upstream https://github.com/upstream-owner/repo.git 2>/dev/null || git remote set-url upstream https://github.com/upstream-owner/repo.git
2. git remote add fork https://github.com/fork-owner/repo.git 2>/dev/null || git remote set-url fork https://github.com/fork-owner/repo.git
3. git fetch --prune upstream main
4. git fetch --prune fork main
5. git rev-list --left-right --count upstream/main...fork/main
6. git merge-tree --write-tree --name-only upstream/main fork/main
7. git cherry -v upstream/main fork/main

Return a concise execution log with: fetched refs, backup branch, merge/rebase path, conflict files, tests run, final branch status, and whether push is safe.

Conflict dossier

Run local merge/rebase analysis to generate conflict-specific agent instructions.

Patch evidence

Local analysis adds git cherry and range-diff evidence here.

Agent session log review

Start with a downstream repository pair.

Enter an upstream repository and a fork repository. If the PR head fork differs from the branch you track for downstream sync, fill that in too. If GitHub API rate limits block the browser report, run local merge/rebase analysis directly.