Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/bradygaster/squad/llms.txt

Use this file to discover all available pages before exploring further.

Ralph is Squad’s automated triage and execution loop. It runs as a background process, polls your GitHub repository for issues, builds a rich context snapshot for each work item, and hands off to agents — keeping the human team responsive without requiring manual triage every time a new issue arrives. With --execute, Ralph goes further: it dispatches live Copilot sessions to work on actionable issues and monitors their progress.

​
Quick Start

# Triage mode only — scan and label issues, no execution
npx @bradygaster/squad-cli watch

# Auto-execute against actionable issues, poll every 5 minutes
npx @bradygaster/squad-cli watch --execute --interval 5

# Custom agent runner with extra Copilot flags
npx @bradygaster/squad-cli watch --execute \
  --agent-cmd "agency copilot" \
  --copilot-flags "--yolo --autopilot --mcp mail --agent squad" \
  --auth-user myaccount

# Run with full diagnostics logged to file
npx @bradygaster/squad-cli watch --execute --log-file ./watch.log --verbose

# Check the health of a running watch process
npx @bradygaster/squad-cli watch --health

​
All Flags

FlagTypeDescription
--executebooleanEnable agent execution — spawn Copilot sessions for actionable issues
--interval <N>numberPoll every N minutes (default: 10)
--agent-cmdstringCustom agent command (default: gh copilot)
--copilot-flagsstringFlags forwarded to the agent runner (e.g. --yolo --autopilot)
--auth-userstringGitHub or Azure DevOps account to use for agent auth
--log-file <path>stringMirror all output to a file with timestamps for later review
--verbosebooleanShow extra diagnostic output (auth probes, callbacks, git pulls)
--healthbooleanPrint running watch status (PID, uptime, next poll) and exit
--max-concurrent <N>numberMaximum number of issues being worked in parallel (default: 1)
--timeout <N>numberMaximum minutes to spend on a single issue before giving up (default: 30)
--dispatch-modestringExecution strategy: task, fleet, or hybrid
--overnight-start HH:MMstringPause watch at this time each day (e.g. 18:00)
--overnight-end HH:MMstringResume watch at this time (e.g. 08:00)
--notify-levelstringOutput verbosity: all, important, or none (default: important)
--state-backendstringPersistence strategy: local, orphan, two-layer, or external (default: in-memory)

​
How Ralph Decides What to Execute

Ralph uses an agent-delegated selection pattern. Rather than choosing which issue to work on itself, Ralph provides a fully assembled context snapshot to the agent and lets the agent decide under the team’s routing rules, review gates, and escalation policy.
1
Scan for triage-eligible issues
2
Ralph calls the GitHub API to find issues that are unassigned, carry the right labels, and haven’t been recently touched. It filters against your team’s routing rules in .squad/routing.md.
3
Build a context snapshot
4
Ralph assembles a structured work context document: the prioritized issue list, relevant squad state from .squad/, recent decisions from decisions.md, and any blocking signals from prior rounds.
5
Write context to a temp file
6
The snapshot is written to a temporary file. Ralph invokes the agent with the path to that file using the -p <path> flag:
7
gh copilot -p /tmp/ralph-context-42.md
8
Agent decides which issue to tackle
9
The agent reads the context, evaluates all available issues against the squad’s rules, and selects the one to work on — along with how to approach it. The agent is aware of escalation criteria and can decline to execute if something is too risky.
10
Ralph monitors execution and updates state
11
Ralph tracks the running agent session, logs results, updates issue labels or comments as appropriate, and records the round outcome in its state backend for the next poll cycle.

​
Issue Selection Scaffold

Ralph provides agents with a structured work context prompt. Here is the scaffold Ralph sends: 
## Work Context

### Available Issues (prioritized)
- #42 Urgent bug in auth (P0)
- #89 Performance review pending (P1)
- #123 Docs update (P2)

### Why These Issues Matter
...context from decision archive...

### Success Criteria
- Tests pass
- Changes match team conventions
- PR linked to issue

### When to Escalate
If blocker detected → pause, log, notify humans
Agents see full context and can make intelligent decisions rather than blindly executing random work.

​
4-Tier Error Recovery

Watch includes a tiered remediation strategy that prevents Ralph from repeatedly hammering the same failure. When an execution fails, Ralph escalates through the tiers in order:
1
Tier 1 — Circuit Breaker Reset
2
Clear the execution state for the affected issue and retry from scratch. Most transient failures (network blips, rate limits) resolve here.
3
Tier 2 — Auth Reprobe
4
Re-verify GitHub credentials before continuing. If the auth token has expired or the account has been de-authorized, this tier surfaces it with a clear message.
5
Tier 3 — Git Pull
6
Pull the latest remote state and retry. Useful when the local repo has fallen behind origin/main and the agent is making decisions on stale context.
7
Tier 4 — Pause 30 Minutes
8
Back off for 30 minutes and log the failure for human review. This tier fires when nothing else has worked and prevents Watch from entering an infinite failure loop. Ralph writes a detailed failure summary so a human can diagnose the issue at their convenience.

​
State Backends

By default, Ralph keeps its state in memory — cheap and simple, but lost on restart. For long-running overnight automation, choose a durable backend: 
# Default: in-memory (state is lost if the process restarts)
squad watch --execute

# Persist state locally in .squad/ (survives restarts, no new branches)
squad watch --execute --state-backend local

# Persist to an orphan branch (isolated history, easy to prune or inspect)
squad watch --execute --state-backend orphan

# Two-layer: local + orphan branch for redundancy
squad watch --execute --state-backend two-layer
BackendDurabilityBranching impactBest for
In-memory (default)Lost on restartNoneShort sessions, CI
localSurvives restartsNoneOvernight automation
orphanSurvives restartsCreates a dedicated state branchAudit trails
two-layerSurvives restartsCreates a dedicated state branchRedundancy
See State Backends for in-depth configuration, migration instructions, and guidance on choosing the right backend for your team.

​
Graceful Shutdown

To stop a running watch process cleanly — letting it finish the current round before exiting — create a sentinel file: 
touch .squad/ralph-stop
Ralph checks for this file at the start of each round. When found, it finishes any in-flight work, logs final state, cleans up scratch directories, and exits with code 0. This is preferable to Ctrl+C when execution is running, because it avoids leaving orphaned agent processes.

​
Monitoring a Running Instance

Check on a running watch process without interrupting it: 
squad watch --health
Sample output: 
Ralph Watch Status

PID: 12345
Uptime: 2h 15m
Last Poll: 2 minutes ago

Auth: Ready (account: myaccount@github.com)
Capabilities: Issue triage, PR review, ADO sync

Next Poll: 14:35 (in 3 minutes)
Round: 42 / 1200
The --health flag reads the persisted state from disk and exits immediately — it does not connect to a running process via IPC.

​
Overnight Scheduling

Run Watch unattended during business hours and pause it automatically overnight: 
squad watch --execute \
  --overnight-start 18:00 \
  --overnight-end 08:00 \
  --state-backend local
When the clock reaches --overnight-start, Ralph finishes the current round, logs that it is entering the overnight pause window, and sleeps. When --overnight-end arrives, Ralph resumes the polling loop automatically without any human intervention.
Times are interpreted in the system’s local timezone. For servers running in UTC, adjust your HH:MM values accordingly.

​
Automatic Cleanup

Ralph prunes stale artifacts automatically during each round:
  • Scratch directories older than 7 days are deleted
  • Log files older than 30 days are archived and removed
  • Orphaned orchestration state (from sessions that never completed) is pruned
This keeps your .squad/ directory lean even after weeks of continuous operation. Use --dry-run on squad nap to preview what cleanup would remove across your entire squad state.
Start with squad watch (no --execute) to validate that Ralph is picking up the right issues and generating sensible context. Once you’re satisfied with the triage output, add --execute to enable automatic dispatching.

Build docs developers (and LLMs) love

Get started for freeTalk to us