### Repo Updater Installation and Quickstart

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/PLAN_TO_CREATE_UPDATE_REPO_TOOL.md

Demonstrates how to install the repo_updater tool using curl and bash, and then initialize and add repositories for synchronization.

```bash
curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/repo_updater/main/install.sh | bash
```

```bash
ru init
```

```bash
ru add owner/repo1
```

```bash
ru add owner/repo2 --private
```

```bash
ru sync
```

--------------------------------

### Installer Flow Diagram

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/PLAN_TO_CREATE_UPDATE_REPO_TOOL.md

This diagram illustrates the step-by-step process for installing the repo_updater, including version determination, download sources, checksum verification, and final installation steps.

```text
┌─────────────────────────────────────────────────────────────────┐
│                        Installer Flow                            │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
                    ┌─────────────────┐
                    │ Determine       │
                    │ version         │
                    │ (latest release │
                    │ or RU_VERSION)  │
                    └────────┬────────┘
                             │
                    ┌────────┴────────┐
                    │                 │
              RU_UNSAFE_MAIN=1     Normal
                    │                 │
                    ▼                 ▼
           ┌─────────────────┐ ┌─────────────────┐
           │Download from    │ │Download from    │
           │main branch      │ │GitHub Release   │
           │(warn user)      │ │                 │
           └────────┬────────┘ └────────┬────────┘
                    │                   │
                    │                   ▼
                    │          ┌─────────────────┐
                    │          │Download checksum│
                    │          │and verify       │
                    │          └────────┬────────┘
                    │                   │
                    │          ┌────────┴────────┐
                    │          │                 │
                    │        Match           Mismatch
                    │          │                 │
                    │          │                 ▼
                    │          │          ┌─────────────────┐
                    │          │          │ERROR: Checksum  │
                    │          │          │verification     │
                    │          │          │failed. Abort.   │
                    │          │          └─────────────────┘
                    │          │
                    └──────────┴──────────┐
                                          │
                                          ▼
                                 ┌─────────────────┐
                                 │Install to       │
                                 │DEST directory   │
                                 └────────┬────────┘
                                          │
                                          ▼
                                 ┌─────────────────┐
                                 │Add to PATH      │
                                 │if needed        │
                                 └────────┬────────┘
                                          │
                                          ▼
                                 ┌─────────────────┐
                                 │Print success    │
                                 │and next steps   │
                                 └─────────────────┘
```

--------------------------------

### Install Repo Updater (RU)

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/SKILL.md

Install RU using the provided one-liner script from GitHub. After installation, verify the setup using the `ru doctor` command.

```bash
curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/repo_updater/main/install.sh | bash
```

```bash
ru doctor
```

--------------------------------

### Install ntm or add to PATH

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/README.md

If 'ntm is not available', install ntm or ensure it's in your PATH. Verify installation with 'ntm --version'.

```bash
# Install ntm (if available via package manager)
# Or add to PATH if installed elsewhere
export PATH="$HOME/.local/bin:$PATH"

# Verify
ntm --version
```

--------------------------------

### E2E Test Example

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/TESTING.md

Illustrates end-to-end testing of CLI workflows in isolated environments. Uses the E2E framework for setup, assertions, and cleanup.

```bash
#!/usr/bin/env bash
set -uo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "$SCRIPT_DIR/test_e2e_framework.sh"

test_sync_command() {
    e2e_setup "sync_command"

    # Set up isolated XDG environment
    export RU_CONFIG_DIR="$E2E_TEMP_DIR/config/ru"
    export RU_STATE_DIR="$E2E_TEMP_DIR/state/ru"
    mkdir -p "$RU_CONFIG_DIR/repos.d"

    # Create test repo
    local remote_dir
    remote_dir=$(create_test_repo "myrepo")
    echo "https://github.com/test/myrepo" > "$RU_CONFIG_DIR/repos.d/public.txt"

    # Run ru command
    local output exit_code=0
    output=$("$RU_SCRIPT" sync 2>&1) || exit_code=$?

    # Verify
    e2e_assert_success "$exit_code" "sync succeeds"
    e2e_assert_contains "$output" "myrepo" "output mentions repo"

    e2e_cleanup
}

run_e2e_test test_sync_command
e2e_summary

```

--------------------------------

### Parse Quickstart Info

Source: https://context7.com/dicklesworthstone/repo_updater/llms.txt

Use 'jq' to parse specific data from the 'ru robot-docs quickstart' command output.

```bash
ru robot-docs quickstart | jq '.data.content.first_run'
```

--------------------------------

### Manual Installation of ru

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/README.md

Manual installation steps involving downloading the script, making it executable, and adding it to the system's PATH.

```bash
# Download script
curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/repo_updater/main/ru -o ~/.local/bin/ru
chmod +x ~/.local/bin/ru

# Ensure ~/.local/bin is in PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc  # or ~/.bashrc
source ~/.zshrc
```

--------------------------------

### System-wide Installation with Install Script

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/README.md

Installs the repo_updater tool system-wide, requiring superuser privileges.

```bash
# System-wide installation (requires sudo)
RU_SYSTEM=1 curl -fsSL .../install.sh | bash
```

--------------------------------

### Install ru using Install Script with PID Cache Busting

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/README.md

Alternative method for the install script that uses a combination of timestamp and Process ID to ensure a fresh download, useful if CDN caching is suspected.

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

--------------------------------

### Install ru with Scoop on Windows

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/README.md

Installation instructions for Windows users using the Scoop package manager. Requires adding the custom bucket first.

```powershell
scoop bucket add dicklesworthstone https://github.com/Dicklesworthstone/scoop-bucket
scoop install dicklesworthstone/ru
```

--------------------------------

### Install ru with Curl-Bash

Source: https://context7.com/dicklesworthstone/repo_updater/llms.txt

Install ru using the recommended curl-bash one-liner with checksum verification. Options are available for specific versions, system-wide installation, or custom directories.

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

```bash
# Install specific version
RU_VERSION=1.2.1 curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/repo_updater/main/install.sh?ru_cb=$(date +%s)" | bash
```

```bash
# System-wide installation (requires sudo)
RU_SYSTEM=1 curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/repo_updater/main/install.sh?ru_cb=$(date +%s)" | bash
```

```bash
# Custom directory
DEST=/opt/bin curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/repo_updater/main/install.sh?ru_cb=$(date +%s)" | bash
```

--------------------------------

### Per-Repo Configuration Example

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/SKILL.md

An example of a per-repository configuration file (.ru-agent.yml). It shows how to enable agent sweeps, set file size limits, provide extra context, define pre/post hooks, and add extra denylist patterns.

```yaml
# ~/.../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/*"
```

--------------------------------

### Initialize ru Configuration

Source: https://context7.com/dicklesworthstone/repo_updater/llms.txt

Create the configuration directory and initial repository list files. Use `--example` to populate with sample repositories.

```bash
# Initialize with empty config
ru init
```

```bash
# Initialize with example repositories
ru init --example
```

--------------------------------

### Install ru Script Flow

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/PLAN_TO_INTEGRATE_NTM_INTO_RU.md

The `install.sh` script flow for installing `ru`. It includes steps for downloading, verifying, and installing `ru`, checking for GitHub CLI and tmux, and optionally enabling ntm integration.

```bash
┌─────────────────────────────────────────────────────────────────────────┐
│                         ru install.sh                                    │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
                          ┌─────────────────┐
                          │  Download ru    │
                          │  Verify SHA256  │
                          │  Install to     │
                          │  ~/.local/bin   │
                          └─────────────────┘
                                    │
                                    ▼
                          ┌─────────────────┐
                          │  Check gh CLI   │───── Missing ────▶ Prompt install
                          └─────────────────┘
                                    │
                                    ▼
                          ┌─────────────────┐
                          │  Check tmux     │───── Missing ────▶ Warn (required for agent-sweep)
                          └─────────────────┘
                                    │
                                    ▼
                    ┌───────────────────────────────┐
                    │  "Enable ntm integration?"    │
                    │                               │
                    │   Enables: ru agent-sweep     │
                    │   Provides: AI commit/release │
                    │                               │
                    │   [Y] Yes (recommended)       │
                    │   [n] No, skip for now        │
                    └───────────────────────────────┘
                                    │
                    ┌───────────────┴───────────────┐
                    ▼                               ▼
            Yes / Auto                              No
                    │                               │
                    ▼                               ▼
          ┌─────────────────┐              ┌─────────────────┐
          │  Check ntm      │              │  Skip ntm       │
          │  installed?     │              │  (can install   │
          └─────────────────┘              │   later)        │
                    │                      └─────────────────┘
          ┌─────────┴─────────┐
          ▼                   ▼
      Installed          Not Installed
          │                   │
          ▼                   ▼
    ┌──────────┐        ┌──────────────┐
    │  Verify  │        │  curl -fsSL  │
    │  version │        │  .../ntm...  │
    │          │        │  | bash      │
    └──────────┘        └──────────────┘
                                    │
                                    ▼
                          ┌─────────────────┐
                          │  Installation   │
                          │  complete!      │
                          └─────────────────┘
```

--------------------------------

### Prompted Installation Logic

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/README.md

Handles cases where dependencies are missing by prompting the user for installation in interactive mode or failing clearly in non-interactive mode.

```bash
# Interactive mode: ask first
if gum_confirm "GitHub CLI (gh) not found. Install now?"; then
    install_gh
fi

# Non-interactive mode: fail clearly
log_error "gh not installed. Run with --install-deps or install manually."
exit 3
```

--------------------------------

### Custom Install Directory with Install Script

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/README.md

Installs the repo_updater tool to a custom directory using the DEST environment variable.

```bash
# Custom install directory
DEST=/opt/bin curl -fsSL .../install.sh | bash
```

--------------------------------

### Per-Repo Override Example - User-Level Settings

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/PLAN_TO_INTEGRATE_NTM_INTO_RU.md

Example of a user-local per-repo configuration file overriding phase timeouts and release strategy for a specific repository.

```bash
# User-level override for specific repo
AGENT_SWEEP_PHASE1_TIMEOUT=120
AGENT_SWEEP_RELEASE_STRATEGY=gh-release
```

--------------------------------

### Install Script Flow

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/PLAN_TO_INTEGRATE_NTM_INTO_RU.md

The installation script 'install.sh' automates the download, verification, and installation of the 'ru' tool, along with checks for dependencies like gh CLI and tmux. It also provides an option to enable 'ntm' integration for AI-powered commit and release features.

```APIDOC
## Install Script Flow

This section outlines the steps involved in the `install.sh` script.

1. **Download `ru`**: Fetches the necessary files.
2. **Verify SHA256**: Ensures the integrity of the downloaded files.
3. **Install to `~/.local/bin`**: Places the executable in the user's local bin directory.
4. **Check `gh` CLI**: Verifies if the GitHub CLI is installed; prompts for installation if missing.
5. **Check `tmux`**: Verifies if `tmux` is installed; warns if missing (required for `agent-sweep`).
6. **NTM Integration Prompt**: Asks the user if they want to enable NTM integration for AI commit/release features. Options are 'Yes' (recommended) or 'No'.
   - If 'Yes' or auto-detected, it proceeds to check and install NTM.
   - If 'No', NTM installation is skipped, but can be installed later.
7. **NTM Installation**: If NTM is not installed, it will be installed using `curl -fsSL ... | bash`.
8. **Completion**: Indicates that the installation is complete.
```

--------------------------------

### jq Example: Get Cloned Repo Paths

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/SKILL.md

Uses jq to filter the JSON output of 'ru sync' and extract the paths of all repositories that were cloned.

```bash
ru sync --json 2>/dev/null | jq -r '.repos[] | select(.action=="clone") | .path'
```

--------------------------------

### Configure NTM Installation via Environment Variables

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/PLAN_TO_INTEGRATE_NTM_INTO_RU.md

Control the installation of ntm during the `ru` script execution using environment variables. `RU_INSTALL_NTM` can be set to 'yes' to auto-install or 'no' to skip. `RU_NON_INTERACTIVE` forces all installations without prompting.

```bash
# Auto-install ntm without prompting
RU_INSTALL_NTM=yes curl -fsSL .../install.sh | bash
```

```bash
# Skip ntm installation
RU_INSTALL_NTM=no curl -fsSL .../install.sh | bash
```

```bash
# Non-interactive (installs everything including ntm)
RU_NON_INTERACTIVE=1 curl -fsSL .../install.sh | bash
```

--------------------------------

### Install ru via curl

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/README.md

Installs the repo updater using a curl command. The cache-buster `?ru_cb=$(date +%s)` can be omitted after the initial installation.

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

--------------------------------

### Environment Variables for Installation

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/PLAN_TO_INTEGRATE_NTM_INTO_RU.md

Control the behavior of the `install.sh` script using environment variables.

```APIDOC
## Environment Variables for Installation

These environment variables can be used to customize the `install.sh` script execution.

### `RU_INSTALL_NTM`

- **`yes`**: Automatically installs NTM without prompting.
  ```bash
  RU_INSTALL_NTM=yes curl -fsSL .../install.sh | bash
  ```
- **`no`**: Skips NTM installation.
  ```bash
  RU_INSTALL_NTM=no curl -fsSL .../install.sh | bash
  ```

### `RU_NON_INTERACTIVE`

- **`1`**: Runs the installation in non-interactive mode, automatically installing all components including NTM.
  ```bash
  RU_NON_INTERACTIVE=1 curl -fsSL .../install.sh | bash
  ```
```

--------------------------------

### JSON Output Example

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/SKILL.md

Example of the JSON output format for the 'ru sync' command. This includes version, timestamp, a summary of operations, and repository details.

```bash
ru sync --json 2>/dev/null
```

--------------------------------

### Install ru via Homebrew

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/README.md

Installs the repo updater on macOS or Linux using the Homebrew package manager.

```bash
brew install dicklesworthstone/tap/ru
```

--------------------------------

### Install GitHub CLI

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/README.md

Install the GitHub CLI on macOS or Ubuntu/Debian. Ensure you authenticate afterwards using 'gh auth login'.

```bash
# macOS
brew install gh

# Ubuntu/Debian
sudo apt install gh

# Then authenticate
gh auth login
```

--------------------------------

### Per-Repo Override Example - Monorepo Timeouts and Denylist

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/PLAN_TO_INTEGRATE_NTM_INTO_RU.md

Example of a per-repo configuration file overriding default timeouts for phases and extending the denylist pattern for sensitive files.

```bash
# Override for monorepo - needs longer timeouts
AGENT_SWEEP_PHASE1_TIMEOUT=300
AGENT_SWEEP_PHASE2_TIMEOUT=600

# Disable releases for this repo
AGENT_SWEEP_RELEASE_STRATEGY=never

# Custom denylist (extend default)
AGENT_SWEEP_DENYLIST_PATTERNS=".env *.pem id_rsa node_modules dist build vendor"

# Custom prompt file (optional)
AGENT_SWEEP_PHASE2_PROMPT_FILE="$REPO_PATH/.ru/commit-prompt.txt"
```

--------------------------------

### Show Ready Issues with br

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/AGENTS.md

Displays issues that are ready to be worked on, meaning they have no outstanding blockers. This is the recommended command to start work.

```bash
br ready
```

--------------------------------

### Example State File Structure

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/PLAN_TO_INTEGRATE_NTM_INTO_RU.md

Illustrates the structure of the agent sweep state file, including run ID, status, and repository progress.

```json
{
  "run_id": "20260106-153000-12345",
  "status": "in_progress",
  "started_at": "2026-01-06T15:30:00Z",
  "config_hash": "abc123...",
  "with_release": false,
  "repos_total": 5,
  "repos_completed": ["repo1", "repo2"],
  "repos_pending": ["repo3", "repo4", "repo5"],
  "current_repo": "repo3",
  "current_phase": 2
}
```

--------------------------------

### Configure Layout Mode

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/SKILL.md

Sets the directory layout for repositories. 'owner-repo' is an example of a specific layout mode.

```bash
ru config --set LAYOUT=owner-repo
```

--------------------------------

### Parse JSON Output with jq

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/README.md

Examples demonstrating how to use 'jq' to parse the JSON output from repo_updater commands for specific data extraction.

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

```bash
# Get count of failures
ru sync --json 2>/dev/null | jq '.data.summary.failed'
```

```bash
# Get all dirty repos from status
ru status --json 2>/dev/null | jq -r '.data.repos[] | select(.dirty) | .repo'
```

--------------------------------

### Repo Updater Configuration File

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/EXTENDING_RU_FOR_AUTOMATED_REVIEWS_OF_ISSUES_AND_PRS_USING_CLAUDE_CODE.md

This is an example configuration file for the repo updater. It allows setting the default review mode, such as 'auto', 'ntm', or 'basic'.

```bash
# ~/.config/ru/config

#==============================================================================
# Review Settings
#==============================================================================

# Orchestration mode: auto, ntm, basic
REVIEW_MODE="auto"
```

--------------------------------

### Get Machine-Readable Documentation

Source: https://context7.com/dicklesworthstone/repo_updater/llms.txt

Retrieve CLI documentation in a structured JSON format, suitable for automation and tooling. The 'all' argument fetches all documentation topics.

```bash
ru robot-docs
```

```bash
ru robot-docs all
```

--------------------------------

### Sample Session: Initializing Repo Updater

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/PLAN_TO_CREATE_UPDATE_REPO_TOOL.md

Demonstrates the initialization process of the repo_updater tool, including creation of configuration files and next steps.

```bash
$ ru init
╭──────────────────────────────────────╮
│  ⅣⅠ ru v1.0.0                        │
│  Repo Updater                        │
╰──────────────────────────────────────╯

✓ Created ~/.config/ru/config
✓ Created ~/.config/ru/repos.d/public.txt
✓ Created ~/.config/ru/repos.d/private.txt

Next steps:
  1. Add repos: ru add owner/repo
  2. Sync:      ru sync

```

--------------------------------

### Sample Session: Synchronizing Repositories

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/PLAN_TO_CREATE_UPDATE_REPO_TOOL.md

Illustrates the synchronization process, including cloning a missing repository and providing a summary of the sync operation.

```bash
$ ru sync
→ Processing 1/1: mcp_agent_mail
  ├─ Path: /data/projects/mcp_agent_mail
  ├─ Status: missing
  ├─ Action: gh repo clone
  └─ Result: ✓ Cloned (12s)

╭─────────────────────────────────────────────────────────────╮
│                    📊 Sync Summary                          │
├─────────────────────────────────────────────────────────────┤
│  ✅ Cloned:  1 repo                                         │
│  Total: 1 repo processed in 12s                             │
╰─────────────────────────────────────────────────────────────╯

```

--------------------------------

### Sample Session: Adding a Repository

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/PLAN_TO_CREATE_UPDATE_REPO_TOOL.md

Shows how to add a repository to the updater's list, confirming its addition.

```bash
$ ru add Dicklesworthstone/mcp_agent_mail
✓ Added to public list: Dicklesworthstone/mcp_agent_mail

```

--------------------------------

### Filter Repositories for Agent Sweep

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/README.md

Specify a subset of repositories to process during the agent sweep using a wildcard pattern. This example targets repositories starting with 'myproject'.

```bash
ru agent-sweep --repos="myproject*"
```

--------------------------------

### Repo Updater Installation Script

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/PLAN_TO_CREATE_UPDATE_REPO_TOOL.md

Bash script for downloading and installing the Repo Updater (ru) tool. Supports custom installation paths, system-wide installation, specific version selection, and unsafe installation from the main branch.

```bash
#!/usr/bin/env bash
#
# ru installer
# Downloads and installs ru (Repo Updater) to your system
#
# DEFAULT: Downloads from GitHub Release with checksum verification
#
# Usage:
#   curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/repo_updater/main/install.sh | bash
#
# Options (via environment variables):
#   DEST=/path/to/dir      Install directory (default: ~/.local/bin)
#   RU_SYSTEM=1            Install to /usr/local/bin (requires sudo)
#   RU_VERSION=x.y.z       Install specific version (default: latest release)
#   RU_UNSAFE_MAIN=1       Install from main branch (NOT RECOMMENDED)
#
```

--------------------------------

### Prompt GitHub CLI Installation Logic

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/PLAN_TO_CREATE_UPDATE_REPO_TOOL.md

Shell script function to check if GitHub CLI (gh) is installed and prompt the user for installation if necessary. It detects the OS and suggests appropriate installation commands.

```bash
prompt_install_gh() {
    if ! can_prompt; then
        log_error "GitHub CLI (gh) is required but not installed."
        log_error "Install it manually: https://cli.github.com/"
        log_error "Or run with --install-deps to auto-install."
        return 1
    fi

    log_warn "GitHub CLI (gh) is not installed."

    local install_cmd=""
    case "$(detect_os)" in
        macos)
            if command -v brew &>/dev/null;
 then
                install_cmd="brew install gh"
            fi
            ;; 
        linux)
            if command -v apt-get &>/dev/null;
 then
                install_cmd="(instructions for apt)"
            elif command -v dnf &>/dev/null;
 then
                install_cmd="sudo dnf install gh"
            fi
            ;; 
    esac

    if [[ -n "$install_cmd" ]]; then
        if gum_confirm "Install GitHub CLI now?"; then
            log_step "Installing gh..."
            # Execute install
        else
            log_error "gh is required. Please install manually."
            return 1
        fi
    fi
}
```

--------------------------------

### Install Specific Version with Install Script

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/README.md

Installs a specific version of the repo_updater tool using the RU_VERSION environment variable.

```bash
# Install specific version
RU_VERSION=1.0.0 curl -fsSL .../install.sh | bash
```

--------------------------------

### Unit Test Example

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/TESTING.md

Demonstrates how to write unit tests using the test framework. Source functions from 'ru' and stub logging functions. Assertions like assert_equals are used to verify results.

```bash
#!/usr/bin/env bash
set -uo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "$SCRIPT_DIR/test_framework.sh"

# Source specific functions from ru
source_ru_function "parse_repo_url"
source_ru_function "normalize_url"

# Stub logging (these functions are often called by sourced code)
log_warn() { :; }
log_error() { :; }

test_parse_github_url() {
    log_test_start "parse_repo_url handles github.com"

    local host owner repo
    parse_repo_url "https://github.com/user/repo" host owner repo

    assert_equals "github.com" "$host" "host"
    assert_equals "user" "$owner" "owner"
    assert_equals "repo" "$repo" "repo"

    log_test_pass "parse_repo_url handles github.com"
}

run_test test_parse_github_url
print_results
exit "$(get_exit_code)"
```

--------------------------------

### ru Configuration Structure Example

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/EXTENDING_RU_FOR_AUTOMATED_REVIEWS_OF_ISSUES_AND_PRS_USING_CLAUDE_CODE.md

Illustrates the directory structure and configuration file locations for the ru (Repo Updater) tool, including main configuration, repository lists, and state files.

```bash
~/.config/ru/
├── config                 # Main configuration (PROJECTS_DIR, LAYOUT, etc.)
└── repos.d/
    ├── repos.txt          # Primary repository list
    ├── work.txt           # Work repositories
    └── personal.txt       # Personal projects

~/.local/state/ru/
├── sync-state.json        # Resume state for interrupted syncs
├── review-state.json      # Review tracking (NEW)
└── logs/                  # Operation logs
```

--------------------------------

### Manage Repositories

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/SKILL.md

Commands for initializing RU configuration, adding, removing, listing, and pruning repositories from the sync list.

```bash
# Initialize configuration
ru init

# Add repos to sync list
ru add owner/repo
ru add https://github.com/owner/repo
ru add owner/repo@branch as custom-name

# Remove from list
ru remove owner/repo

# List configured repos
ru list

# Detect orphaned repos (in projects dir but not in list)
ru prune           # Preview
ru prune --delete  # Actually remove
ru prune --archive # Move to archive directory
```

--------------------------------

### Verify tmux Installation

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/README.md

Confirm that tmux, the terminal multiplexer, is installed by checking its version.

```bash
tmux -V
```

--------------------------------

### Integration Test Example

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/TESTING.md

Shows how to test git operations using local repositories. Utilizes git harness helpers like create_real_git_repo_with_remote to set up test environments.

```bash
#!/usr/bin/env bash
set -uo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "$SCRIPT_DIR/test_framework.sh"

test_clone_and_pull() {
    log_test_start "clone and pull workflow"

    # Create test environment with local repos
    local info repo_dir remote_dir dev_dir
    info=$(create_real_git_repo_with_remote "test-repo" 3)
    repo_dir="${info%|*}"
    remote_dir="${info#*|}"

    # Create a "dev" clone to simulate another developer pushing
    # (Can't commit directly to bare repo - must push from a working copy)
    dev_dir=$(mktemp -d)
    git clone "$remote_dir" "$dev_dir" >/dev/null 2>&1
    git -C "$dev_dir" config user.name "Other Dev"
    git -C "$dev_dir" config user.email "dev@test.local"
    git -C "$dev_dir" commit --allow-empty -m "Remote commit"
    git -C "$dev_dir" push >/dev/null 2>&1

    # Test ru function
    source_ru_function "do_pull"
    local pull_exit=0
    do_pull "$repo_dir" "ff-only" "false" || pull_exit=$?

    # Verify
    assert_equals "0" "$pull_exit" "pull succeeds"

    log_test_pass "clone and pull workflow"
}

```

--------------------------------

### Git Harness Setup and Repository Creation

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/README.md

Use the git harness to set up test repositories with specific states. The `git_harness_create_repo` function allows for various configurations like commits ahead/behind, dirty working directories, shallow clones, and detached HEAD states. Remember to clean up temporary directories with `git_harness_cleanup`.

```bash
git_harness_setup
repo=$(git_harness_create_repo "myrepo" --ahead=2)
# $repo now contains a working directory with 2 unpushed commits

repo=$(git_harness_create_repo "diverged" --ahead=1 --behind=3)

repo=$(git_harness_create_repo "dirty" --dirty)
repo=$(git_harness_create_repo "shallow" --shallow=5)
repo=$(git_harness_create_repo "detached" --detached)
repo=$(git_harness_create_repo "nobranch" --no-remote)

git_harness_cleanup  # Removes all temp directories
```

--------------------------------

### Setup NTM Mock Script

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/PLAN_TO_INTEGRATE_NTM_INTO_RU.md

Creates a mock 'ntm' executable script for testing. It simulates different scenarios by responding to specific command-line arguments and setting environment variables like NTM_MOCK_SCENARIO.

```bash
#!/bin/bash
scenario="${NTM_MOCK_SCENARIO:-ok}"

case "$1" in
    --robot-status) 
        echo '{"success":true,"sessions":[]}'
        ;;
    --robot-spawn=*) 
        if [[ "$scenario" == "resource_busy" ]]; then
            echo '{"success":false,"error_code":"RESOURCE_BUSY","error":"session already exists"}'
            exit 1
        fi
        if [[ "$scenario" == "spawn_fail" ]]; then
            echo '{"success":false,"error_code":"INTERNAL_ERROR","error":"spawn failed"}'
            exit 1
        fi
        echo '{"success":true,"session":"test","agents":[{"pane":"0.1","ready":true}]}'
        ;;
    --robot-send=*) 
        echo '{"success":true,"delivered":1}'
        ;;
    --robot-wait=*) 
        if [[ "$scenario" == "timeout" ]]; then
            echo '{"success":false,"error_code":"TIMEOUT","error":"Timeout waiting for condition"}'
            exit 1
        fi
        if [[ "$scenario" == "agent_error" ]]; then
            echo '{"success":false,"error_code":"INTERNAL_ERROR","error":"Agent crashed"}'
            exit 3
        fi
        sleep 0.5  # Simulate work (faster for tests)
        echo '{"success":true,"condition":"idle","waited_seconds":1}'
        ;;
    --robot-activity=*) 
        if [[ "$scenario" == "rate_limited" ]]; then
            echo '{"success":true,"agents":[{"state":"WAITING","rate_limited":true}]}'
        else
            echo '{"success":true,"agents":[{"state":"WAITING","rate_limited":false}]}'
        fi
        ;;
    kill) 
        echo "killed"
        ;;
esac

```

--------------------------------

### Install ntm Script

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/PLAN_TO_INTEGRATE_NTM_INTO_RU.md

A one-liner command to install the ntm tool using curl and bash.

```bash
curl -fsSL .../install.sh | bash
```

--------------------------------

### List Configured Repositories with ru

Source: https://context7.com/dicklesworthstone/repo_updater/llms.txt

Display all repositories in your configuration, with options to show local paths, filter by public/private, or output as JSON.

```bash
# List all configured repos
ru list
```

```bash
# Show local paths instead of URLs
ru list --paths
```

```bash
# Show only public repos
ru list --public
```

```bash
# Show only private repos
ru list --private
```

```bash
# JSON output
ru list --json
```

--------------------------------

### Disable Installer Self-Refresh

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/README.md

Disables the automatic self-refresh mechanism of the installer script, suitable for airgapped environments.

```bash
RU_INSTALLER_NO_SELF_REFRESH=1 bash install.sh
```

--------------------------------

### Verify Claude Code Installation

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/README.md

Ensure the Claude Code AI agent is installed and available by checking its version.

```bash
claude --version
```

--------------------------------

### Bash Script: ru --help usage text

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/RESEARCH_FINDINGS.md

Example of how the `--help` output might be structured, including usage text and flag tables. This needs to be updated to reflect TOON format options.

```bash
Usage: ru [OPTIONS] COMMAND

Options:
  --format <json|toon>  Output format for structured data. Defaults to json.
  --json                Shortcut for --format json.
  -h, --help            Show this message and exit.

Commands:
  sync      Synchronize repositories
  status    Check repository status
  review    Review repository changes
  # ... other commands
```

--------------------------------

### Verify ntm Installation

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/README.md

Check if the Named Tmux Manager (ntm) is installed and accessible by running its version command.

```bash
ntm --version
```

--------------------------------

### Cass Memory System Onboarding

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/AGENTS.md

Use the `cm` command to onboard and manage the Cass Memory System. Commands include checking status, sampling sessions for analysis, and reading sessions with rich context.

```bash
# 1. Check status and see recommendations
cm onboard status

# 2. Get sessions to analyze (filtered by gaps in your playbook)
cm onboard sample --fill-gaps

# 3. Read a session with rich context
cm onboard read /path/to/session.jsonl --template
```

--------------------------------

### Normal Mode Output Example

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/PLAN_TO_INTEGRATE_NTM_INTO_RU.md

This is an example of the standard output when agent-sweep runs in normal mode, displaying progress and results to stderr.

```text
→ Checking ntm availability... ok
→ Found 5 repositories with uncommitted changes

→ Processing: mcp_agent_mail
  ├─ Spawning Claude Code session...
  ├─ Phase 1: Deep codebase understanding... done (45s)
  ├─ Phase 2: Intelligent commits... done (78s)
  └─ ✓ Completed (123s)

→ Processing: beads_viewer
  ├─ Spawning Claude Code session...
  ├─ Phase 1: Deep codebase understanding... done (32s)
  ├─ Phase 2: Intelligent commits... done (56s)
  └─ ✓ Completed (88s)

→ Processing: repo_updater
  ├─ Spawning Claude Code session...
  ├─ Phase 1: Deep codebase understanding... done (61s)
  ├─ Phase 2: Intelligent commits... done (124s)
  ├─ Phase 3: GitHub release... done (89s)
  └─ ✓ Completed with release v1.2.0 (274s)

╭─────────────────────────────────────────────────────────────╮
│                   Agent Sweep Complete                       │
│                                                             │
│  Processed: 5 repos                                         │
│  Succeeded: 5                                               │
│  Failed: 0                                                  │
│  Total time: 8m 23s                                         │
╰─────────────────────────────────────────────────────────────╯
```

--------------------------------

### ntm Robot Mode Command: Get Session Activity

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/PLAN_TO_INTEGRATE_NTM_INTO_RU.md

Get the current state and activity of a specific session, including velocity-based metrics.

```bash
--robot-activity=SESSION
```

--------------------------------

### Initialize Repo Updater Configuration

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/README.md

Initializes the configuration directory and files for the repo_updater. This is typically the first step before adding repositories.

```bash
ru init
```

--------------------------------

### Claude Code Result Event Example

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/README.md

Example of the JSON output for a 'result' event from a Claude Code session, indicating success, duration, and cost.

```json
{"type":"result","status":"success","duration_ms":45000,"cost_usd":0.0234}
```

--------------------------------

### Gum Progress Display

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/PLAN_TO_CREATE_UPDATE_REPO_TOOL.md

This example shows how to use 'gum' to display detailed progress for individual repository updates, including path, status, action, and result.

```text
→ Processing 12/47: coding_agent_session_search
  ├─ Path: /data/projects/coding_agent_session_search
  ├─ Status: behind (0 ahead, 3 behind)
  ├─ Action: git pull --ff-only
  └─ Result: ✓ Updated (2s)

→ Processing 13/47: mcp_agent_mail
  ├─ Path: /data/projects/mcp_agent_mail
  ├─ Status: dirty (3 files modified)
  ├─ Action: Skipped
  └─ Result: ⚠️ Conflict (dirty working tree)
```

--------------------------------

### Install Repo Updater from Main Branch

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/README.md

Installs the repo_updater script directly from the main branch. This method is not recommended for production environments due to potential instability.

```bash
RU_UNSAFE_MAIN=1 curl -fsSL .../install.sh | bash
```

--------------------------------

### Project Structure Overview

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/PLAN_TO_CREATE_UPDATE_REPO_TOOL.md

Illustrates the directory and file layout of the repo_updater project.

```bash
repo_updater/
├── ru                                    # Main script (~800-1000 LOC)
├── install.sh                            # Curl-bash installer (~250 LOC)
├── README.md                             # Comprehensive documentation
├── VERSION                               # Semver version file (e.g., "1.0.0")
├── LICENSE                               # MIT License
├── .gitignore                            # Ignore runtime artifacts
├── .github/
│   └── workflows/
│       ├── ci.yml                        # ShellCheck, syntax, behavioral tests
│       └── release.yml                   # GitHub releases with checksums
├── scripts/
│   ├── test_local_git.sh                 # Integration tests with local git repos
│   ├── test_parsing.sh                   # URL parsing tests
│   └── test_json_output.sh               # JSON schema validation
└── examples/
    ├── public.txt                        # Example public repos list
    └── private.template.txt              # Empty template for private repos
```

--------------------------------

### API Usage Metrics Example

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/EXTENDING_RU_FOR_AUTOMATED_REVIEWS_OF_ISSUES_AND_PRS_USING_CLAUDE_CODE.md

An example JSON structure for storing API usage metrics, including review statistics, timing, decision breakdowns, and error counts.

```json
// ~/.local/state/ru/metrics/2025-01.json
{
  "period": "2025-01",
  "reviews": {
    "total": 45,
    "repos_reviewed": 23,
    "issues_processed": 89,
    "prs_processed": 12,
    "issues_resolved": 67,
    "prs_closed": 8,
    "questions_asked": 34,
    "questions_answered": 32,
    "questions_skipped": 2
  },
  "timing": {
    "total_duration_minutes": 340,
    "avg_per_repo_minutes": 14.8,
    "avg_question_response_seconds": 45
  },
  "decisions": {
    "by_type": {
      "quick_fix": 23,
      "full_refactor": 8,
      "skip": 12,
      "implement_feature": 5
    },
    "by_repo": {
      "project-alpha": {"quick_fix": 5, "skip": 2},
      "project-beta": {"full_refactor": 3}
    }
  },
  "errors": {
    "rate_limits": 2,
    "session_crashes": 1,
    "network_failures": 3
  }
}
```

--------------------------------

### Calculate Initial Parallelism

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/EXTENDING_RU_FOR_AUTOMATED_REVIEWS_OF_ISSUES_AND_PRS_USING_CLAUDE_CODE.md

Calculates an initial optimal parallelism value based on the total number of repositories, considering system resources and attention quality. This serves as a starting point before the governor takes over.

```bash
calculate_optimal_parallelism() {
    local total_repos="$1"

    # The real source of truth is the rate-limit governor (see 10.2.1)
    # This provides a starting point

    # Factors:
    # - API rate limits (read from gh api rate_limit, not guessed)
    # - Claude rate limits (detected via 429 responses)
    # - System resources (memory, CPU)
    # - Context quality (too many sessions = divided attention)

    local max_by_resources=8        # Based on typical system
    local max_by_quality=6          # Optimal for attention

    local optimal=$((total_repos < max_by_quality ? total_repos : max_by_quality))
    optimal=$((optimal < max_by_resources ? optimal : max_by_resources))

    echo "$optimal"
}
```

--------------------------------

### NDJSON Results Logging Examples

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/README.md

Examples of NDJSON formatted logs used by repo_updater to track per-repo results. This format is suitable for parsing by CI systems and other tools.

```json
{"repo":"mcp_agent_mail","path":"/data/projects/mcp_agent_mail","action":"pull","status":"updated","duration":2,"message":"","timestamp":"2025-01-03T14:30:00Z"}
{"repo":"beads_viewer","path":"/data/projects/beads_viewer","action":"clone","status":"cloned","duration":5,"message":"","timestamp":"2025-01-03T14:30:05Z"}
{"repo":"repo_updater","path":"/data/projects/repo_updater","action":"skip","status":"current","duration":0,"message":"Already up to date","timestamp":"2025-01-03T14:30:05Z"}
```

--------------------------------

### Configurable Path Layouts

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/PLAN_TO_CREATE_UPDATE_REPO_TOOL.md

Details different strategies for organizing synchronized repositories locally, including flat, owner-repo, and full path layouts.

```markdown
| Layout | Path | Use Case |
|--------|------|----------|
| `flat` (default) | `$PROJECTS_DIR/repo` | Simple, matches existing setup |
| `owner-repo` | `$PROJECTS_DIR/owner/repo` | Avoids most collisions |
| `full` | `$PROJECTS_DIR/github.com/owner/repo` | Multi-host, enterprise |
```

--------------------------------

### AI-Generated Commit Example

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/PLAN_TO_INTEGRATE_NTM_INTO_RU.md

An example of a detailed, AI-generated commit message following best practices for summary, body, and co-authorship. This format is used for logically grouped changes.

```gitcommit
feat(auth): implement OAuth2 PKCE flow for mobile clients

This commit adds PKCE (Proof Key for Code Exchange) support to the
OAuth2 authentication flow, addressing security requirements for
public clients (mobile apps) that cannot securely store client secrets.

Changes:
- Add code_verifier and code_challenge generation in auth/pkce.py
- Update /authorize endpoint to accept code_challenge parameter
- Modify /token endpoint to verify code_verifier against stored challenge
- Add PKCE-specific tests covering S256 and plain methods

The implementation follows RFC 7636 and is required for App Store
compliance with OAuth 2.0 best practices for native apps.

🤖 Generated with Claude Code (https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
```

--------------------------------

### Temporary Directory Creation and Cleanup for E2E Tests

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/AGENTS.md

Demonstrates the correct pattern for E2E tests by creating a temporary directory for the projects, running tests, and then cleaning up the directory. This prevents clutter in the main projects directory.

```bash
TEMP_DIR=$(mktemp -d)
export RU_PROJECTS_DIR="$TEMP_DIR/projects"
# ... run tests ...
rm -rf "$TEMP_DIR"  # cleanup
```

--------------------------------

### Repo Updater Doctor Example Output

Source: https://github.com/dicklesworthstone/repo_updater/blob/main/README.md

Example output from the 'ru doctor' command, showing the status of various checks including git, GitHub CLI, configuration, and project directories.

```bash
╭─────────────────────────────────────────────────────────────╮
│                    🔍 ru doctor                              │
╰─────────────────────────────────────────────────────────────╯

✓ git: 2.43.0
✓ gh: 2.40.1 (authenticated as yourname)
✓ Config: ~/.config/ru/ (47 repos configured)
✓ Projects: /data/projects (writable)
✓ gum: 0.13.0 (optional)

All checks passed!
```