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