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
| Concept |
Rule |
| Git plumbing only |
Never parse human-readable output; use rev-list, status --porcelain, rev-parse |
| Stream separation |
Human-readable → stderr; data → stdout (--json 2>/dev/null | jq) |
No global cd |
All git operations use git -C |
Essential Commands
| Command |
Purpose |
ru sync |
Sync all configured repos (add -j8 for parallel) |
ru sync --dry-run |
Preview what would happen |
ru sync --resume |
Resume interrupted sync |
ru status |
Read-only check of all repos |
ru add owner/repo |
Add repo to sync list |
ru remove owner/repo |
Remove from list |
ru list |
Show configured repos |
ru prune |
Detect orphaned repos |
ru doctor |
System health check |
ru review --plan |
Discover issues/PRs for AI review |
ru review --apply --push |
Apply reviewed changes |
ru agent-sweep |
Process repos with uncommitted changes |
ru agent-sweep -j4 |
Parallel agent processing |
AI Review Priority Scoring
| Factor |
Points |
Logic |
| Type |
0-20 |
PRs: +20, Issues: +10, Draft PRs: -15 |
| Labels |
0-50 |
security/critical: +50, bug/urgent: +30 |
| Age (bugs) |
0-50 |
>60 days: +50, >30 days: +30 |
| Recency |
0-15 |
Updated <3 days: +15, <7 days: +10 |
| Staleness |
-20 |
Recently reviewed: -20 |
Levels: CRITICAL (≥150), HIGH (≥100), NORMAL (≥50), LOW (<50)
Agent Sweep Phases
| Phase |
Default Timeout |
Action |
| 1: Planning |
300s |
Analyze uncommitted changes, generate commit plan |
| 2: Commit |
600s |
Validate plan, stage files, create commit, quality gates |
| 3: Release |
300s (opt-in) |
Determine version bump, create tag/release |
Execution modes: agent (full workflow), plan (phase 1 only), apply (phase 2+3)
Update Strategies
| Strategy |
Behavior |
ff-only |
Fast-forward only; fails if diverged (default) |
rebase |
Rebase local commits on top of remote |
merge |
Create merge commit if needed |
Exit Codes
| Code |
Meaning |
| 0 |
All repos processed successfully |
| 1 |
Some repos failed |
| 2 |
Conflicts or quality gate failures |
| 3 |
System/dependency error |
| 4 |
Invalid arguments |
| 5 |
Interrupted (use --resume) |
Environment Variables
| Variable |
Default |
Description |
RU_PROJECTS_DIR |
/data/projects |
Base directory for repos |
RU_LAYOUT |
flat |
Path layout (flat, owner-repo, full) |
RU_PARALLEL |
1 |
Parallel workers |
RU_TIMEOUT |
30 |
Network timeout (seconds) |
RU_UPDATE_STRATEGY |
ff-only |
Pull strategy |
GH_TOKEN |
(from gh CLI) |
GitHub token |
Common Mistakes
| Mistake |
Correct Pattern |
Parsing human-readable git output (e.g., git status text) |
Use git plumbing: rev-list, status --porcelain, rev-parse |
Using cd to change into repo directories |
Use git -C <path> for all git operations |
| Mixing data and human-readable output on the same stream |
Data goes to stdout, human-readable to stderr (--json 2>/dev/null | jq) |
Running sync without --dry-run first on unfamiliar repos |
Always preview with ru sync --dry-run before executing |
Using service_role key or bypassing auth in agent-sweep scripts |
Follow security guardrails; agent-sweep has preflight checks for a reason |
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
1---2name: repo-updater3description: Repo Updater - Multi-repo synchronization with AI-assisted review orchestration. Parallel sync, agent-sweep for dirty repos, ntm integration, git plumbing. 17K LOC Bash CLI. Use when syncing multiple GitHub repositories, running agent-sweep on uncommitted changes, or orchestrating AI-assisted code review across repos.4license: MIT5---6
7# Repo Updater
8
9Bash CLI for synchronizing dozens or hundreds of GitHub repositories with AI-assisted code review and agent-sweep for uncommitted changes.
10
11## Critical Concepts
12
13| Concept | Rule |
14| ----------------- | ------------------------------------------------------------------------------------ |
15| Git plumbing only | Never parse human-readable output; use `rev-list`, `status --porcelain`, `rev-parse` |
16| Stream separation | Human-readable → stderr; data → stdout (`--json 2>/dev/null \| jq`) |
17| No global `cd` | All git operations use `git -C` |
18
19## Essential Commands
20
21| Command | Purpose |
22| -------------------------- | -------------------------------------------------- |
23| `ru sync` | Sync all configured repos (add `-j8` for parallel) |
24| `ru sync --dry-run` | Preview what would happen |
25| `ru sync --resume` | Resume interrupted sync |
26| `ru status` | Read-only check of all repos |
27| `ru add owner/repo` | Add repo to sync list |
28| `ru remove owner/repo` | Remove from list |
29| `ru list` | Show configured repos |
30| `ru prune` | Detect orphaned repos |
31| `ru doctor` | System health check |
32| `ru review --plan` | Discover issues/PRs for AI review |
33| `ru review --apply --push` | Apply reviewed changes |
34| `ru agent-sweep` | Process repos with uncommitted changes |
35| `ru agent-sweep -j4` | Parallel agent processing |
36
37## AI Review Priority Scoring
38
39| Factor | Points | Logic |
40| ---------- | ------ | --------------------------------------- |
41| Type | 0-20 | PRs: +20, Issues: +10, Draft PRs: -15 |
42| Labels | 0-50 | security/critical: +50, bug/urgent: +30 |
43| Age (bugs) | 0-50 | >60 days: +50, >30 days: +30 |
44| Recency | 0-15 | Updated <3 days: +15, <7 days: +10 |
45| Staleness | -20 | Recently reviewed: -20 |
46
47Levels: CRITICAL (≥150), HIGH (≥100), NORMAL (≥50), LOW (<50)
48
49## Agent Sweep Phases
50
51| Phase | Default Timeout | Action |
52| ----------- | --------------- | -------------------------------------------------------- |
53| 1: Planning | 300s | Analyze uncommitted changes, generate commit plan |
54| 2: Commit | 600s | Validate plan, stage files, create commit, quality gates |
55| 3: Release | 300s (opt-in) | Determine version bump, create tag/release |
56
57Execution modes: `agent` (full workflow), `plan` (phase 1 only), `apply` (phase 2+3)
58
59## Update Strategies
60
61| Strategy | Behavior |
62| --------- | ---------------------------------------------- |
63| `ff-only` | Fast-forward only; fails if diverged (default) |
64| `rebase` | Rebase local commits on top of remote |
65| `merge` | Create merge commit if needed |
66
67## Exit Codes
68
69| Code | Meaning |
70| ---- | ---------------------------------- |
71| 0 | All repos processed successfully |
72| 1 | Some repos failed |
73| 2 | Conflicts or quality gate failures |
74| 3 | System/dependency error |
75| 4 | Invalid arguments |
76| 5 | Interrupted (use `--resume`) |
77
78## Environment Variables
79
80| Variable | Default | Description |
81| -------------------- | ---------------- | ------------------------------------ |
82| `RU_PROJECTS_DIR` | `/data/projects` | Base directory for repos |
83| `RU_LAYOUT` | `flat` | Path layout (flat, owner-repo, full) |
84| `RU_PARALLEL` | `1` | Parallel workers |
85| `RU_TIMEOUT` | `30` | Network timeout (seconds) |
86| `RU_UPDATE_STRATEGY` | `ff-only` | Pull strategy |
87| `GH_TOKEN` | (from gh CLI) | GitHub token |
88
89## Common Mistakes
90
91| Mistake | Correct Pattern |
92| ----------------------------------------------------------------- | -------------------------------------------------------------------------- |
93| Parsing human-readable git output (e.g., `git status` text) | Use git plumbing: `rev-list`, `status --porcelain`, `rev-parse` |
94| Using `cd` to change into repo directories | Use `git -C <path>` for all git operations |
95| Mixing data and human-readable output on the same stream | Data goes to stdout, human-readable to stderr (`--json 2>/dev/null \| jq`) |
96| Running sync without `--dry-run` first on unfamiliar repos | Always preview with `ru sync --dry-run` before executing |
97| Using `service_role` key or bypassing auth in agent-sweep scripts | Follow security guardrails; agent-sweep has preflight checks for a reason |
98
99## Delegation
100
101- **Discover which repos have uncommitted changes or are out of sync**: Use `Explore` agent to run `ru status` and analyze the output
102- **Process dirty repos with agent-sweep across multiple repositories**: Use `Task` agent to run `ru agent-sweep -j4` and handle quality gate failures
103- **Plan a multi-repo sync strategy with review prioritization**: Use `Plan` agent to design sync order, parallelism settings, and review budget allocation
104
105## References
106
107- [Commands](references/commands.md) — sync, status, repo management, diagnostics, output modes, jq examples
108- [Review System](references/review-system.md) — two-phase workflow, session drivers, cost budgets, priority scoring
109- [Agent Sweep](references/agent-sweep.md) — three-phase workflow, preflight checks, security guardrails, execution modes
110- [Configuration](references/configuration.md) — XDG directory structure, repo list format, layout modes, per-repo config
111- [Troubleshooting](references/troubleshooting.md) — common issues, debug mode, preflight failure debugging, integration points
oakoss