Repo Updater

Repo Updater

Bash CLI for synchronizing dozens or hundreds of GitHub repositories with AI-assisted code review and agent-sweep for uncommitted changes.

Critical Concepts

Essential Commands

AI Review Priority Scoring

Levels: CRITICAL (≥150), HIGH (≥100), NORMAL (≥50), LOW (<50)

Agent Sweep Phases

Execution modes: agent (full workflow), plan (phase 1 only), apply (phase 2+3)

Update Strategies

Exit Codes

Environment Variables

Common Mistakes

Delegation

• Discover which repos have uncommitted changes or are out of sync: Use Explore agent to run ru status and analyze the output
• Process dirty repos with agent-sweep across multiple repositories: Use Task agent to run ru agent-sweep -j4 and handle quality gate failures
• Plan a multi-repo sync strategy with review prioritization: Use Plan agent to design sync order, parallelism settings, and review budget allocation

References

• Commands — sync, status, repo management, diagnostics, output modes, jq examples
• Review System — two-phase workflow, session drivers, cost budgets, priority scoring
• Agent Sweep — three-phase workflow, preflight checks, security guardrails, execution modes
• Configuration — XDG directory structure, repo list format, layout modes, per-repo config
• Troubleshooting — common issues, debug mode, preflight failure debugging, integration points

Agent Sweep

Orchestrate AI coding agents to automatically process repositories with uncommitted changes.

Basic Usage

ru agent-sweep                    # Process all dirty repos
ru agent-sweep --dry-run          # Preview what would be processed
ru agent-sweep -j4                # 4 repos in parallel
ru agent-sweep --repos="myproject*"  # Filter to specific repos
ru agent-sweep --with-release     # Include release step
ru agent-sweep --resume           # Resume interrupted sweep
ru agent-sweep --restart          # Start fresh

Three-Phase Workflow

Phase 1: Planning (--phase1-timeout, default 300s)

• Claude Code analyzes uncommitted changes
• Determines which files should be staged (respecting denylist)
• Generates structured commit message

Phase 2: Commit (--phase2-timeout, default 600s)

• Validates the plan (file existence, denylist compliance)
• Stages approved files, creates commit
• Runs quality gates
• Optionally pushes to remote

Phase 3: Release (--phase3-timeout, default 300s, requires --with-release)

• Analyzes commit history since last tag
• Determines version bump (patch/minor/major)
• Creates git tag and optionally GitHub release

Execution Modes

--execution-mode=agent  # Full AI-driven workflow (default)
--execution-mode=plan   # Phase 1 only: generate plan, stop
--execution-mode=apply  # Phase 2+3: execute existing plan

Preflight Checks

Each repo is validated before spawning an agent:

Security Guardrails

File Denylist

Never committed regardless of agent output:

Secret Scanning

--secret-scan=none   # Disable
--secret-scan=warn   # Warn but continue (default)
--secret-scan=block  # Block push on detection

Exit Codes

Commands

Sync (Primary Use Case)

ru sync              # Sync all configured repos
ru sync -j8          # Parallel sync (much faster)
ru sync --dry-run    # See what would happen
ru sync --resume     # Resume interrupted sync
ru sync --json 2>/dev/null | jq '.summary'  # JSON output

Status (Read-Only Check)

ru status            # Check all repos without modifying
ru status --json     # JSON output

Repo Management

ru init                            # Initialize configuration
ru add owner/repo                  # Add repo
ru add https://github.com/owner/repo
ru add owner/repo@branch as custom-name
ru remove owner/repo               # Remove from list
ru list                            # List configured repos
ru prune                           # Preview orphaned repos
ru prune --delete                  # Remove orphans
ru prune --archive                 # Archive orphans

Diagnostics

ru doctor      # System health check
ru self-update # Update ru itself

JSON Output Mode

ru sync --json 2>/dev/null

{
  "version": "1.2.0",
  "timestamp": "2025-01-03T14:30:00Z",
  "summary": {
    "total": 47,
    "cloned": 8,
    "updated": 34,
    "current": 3,
    "conflicts": 2
  },
  "repos": []
}

NDJSON Results Logging

{"repo":"mcp_agent_mail","action":"pull","status":"updated","duration":2}
{"repo":"beads_viewer","action":"clone","status":"cloned","duration":5}

jq Examples

# Get paths of all cloned repos
ru sync --json 2>/dev/null | jq -r '.repos[] | select(.action=="clone") | .path'

# Count by status
cat ~/.local/state/ru/logs/latest/results.ndjson | jq -s 'group_by(.status) | map({status: .[0].status, count: length})'

Configuration

XDG-Compliant Directory Structure

~/.config/ru/
├── config               # Main config file
└── repos.d/
    ├── public.list      # Public repos (one per line)
    └── private.list     # Private repos (gitignored)

~/.local/state/ru/
├── logs/
│   └── YYYY-MM-DD/
├── agent-sweep/
│   ├── state.json
│   └── results.ndjson
└── review/
    ├── digests/
    └── results/

Repo List Format

# ~/.config/ru/repos.d/public.list
owner/repo
another-owner/another-repo@develop
private-org/repo@main as local-name
https://github.com/owner/repo.git

Layout Modes

ru config --set LAYOUT=owner-repo

Per-Repo Configuration

# ~/.../your-repo/.ru-agent.yml
agent_sweep:
  enabled: true
  max_file_size: 5242880 # 5MB
  extra_context: 'This is a Python project using FastAPI'
  pre_hook: 'make lint'
  post_hook: 'make test'
  denylist_extra:
    - '*.backup'
    - 'internal/*'

Update Strategies

ru sync                        # Default: ff-only (safest)
ru sync --rebase               # Rebase local commits
ru sync --autostash            # Auto-stash before pull
ru sync --force                # Force update (use with caution)

Quality Gates

Auto-detection by project type:

Rate Limiting

Adaptive parallelism governor:

Review System

Two-Phase Review Workflow

Phase 1: Discovery (--plan)

• Queries GitHub for open issues and PRs across all repos
• Scores items by priority using label analysis and age
• Creates isolated git worktrees for safe review
• Spawns Claude Code sessions in terminal multiplexer

Phase 2: Application (--apply)

• Reviews proposed changes from discovery phase
• Runs quality gates (ShellCheck, tests, lint)
• Optionally pushes approved changes (--push)

ru review --plan                # Discover and plan reviews
ru review --apply --push        # After reviewing AI suggestions

Priority Scoring Algorithm

Priority levels: CRITICAL (≥150), HIGH (≥100), NORMAL (≥50), LOW (<50)

Session Drivers

ru review --mode=ntm --plan
ru review -j 4 --plan           # Parallel sessions

Cost Budgets

ru review --max-repos=10 --plan
ru review --max-runtime=30 --plan    # Minutes
ru review --skip-days=14 --plan      # Skip recently reviewed
ru review --analytics                # View past review stats

Troubleshooting

Common Issues

Debug Mode

# View latest run log
cat ~/.local/state/ru/logs/latest/run.log

# View specific repo log
cat ~/.local/state/ru/logs/latest/repos/mcp_agent_mail.log

# Run with verbose output
ru agent-sweep --verbose --debug

Preflight Failure Debugging

# View why repos were skipped
ru agent-sweep --json 2>/dev/null | jq '.repos[] | select(.status == "skipped")'

ntm Integration

When ntm (Named Tmux Manager) is available, RU uses its robot mode API:

Flywheel Integration

Architecture Notes

• ~17,700 LOC pure Bash, no external dependencies beyond git, curl, gh
• Work-stealing queue for parallel sync with atomic dequeue
• Portable locking via mkdir (works on all POSIX systems)
• Path security validation prevents traversal attacks
• Retry with exponential backoff for network operations

Installation

brew install dicklesworthstone/tap/ru
ru doctor

Alternative (curl):

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/repo_updater/main/install.sh?ru_cb=$(date +%s)" | bash
ru doctor