rally

name: rally description: Guide for using the Rally CLI tool to dispatch AI agents to GitHub issues and PR reviews via git worktrees. Use this when working with Rally dispatches, the dashboard, or managing worktrees.

Rally CLI

Rally is a CLI tool that dispatches AI agents (via GitHub Copilot CLI) to work on GitHub issues and PR reviews. It uses git worktrees to give each dispatch an isolated working copy and tracks all active work in a central state file.

Prerequisites

Node.js ≥ 20
git — for worktree management
gh (GitHub CLI) — for fetching issues/PRs and launching Copilot
gh copilot extension — for AI agent sessions

Install Rally globally:

npm install -g github:jsturtevant/rally#v0.1.0

Or run directly with npx:

npx github:jsturtevant/rally#v0.1.0

First-Time Setup

rally onboard <target>   # Register a repo (auto-creates ~/rally/ on first run)

Setup details

Rally automatically creates its home directory on first use (default ~/rally/, override with RALLY_HOME):

~/rally/projects/ — cloned project repos
~/rally/config.yaml — Rally configuration

Onboarding a project

rally onboard .                          # Current directory
rally onboard /path/to/repo              # Local path
rally onboard owner/repo                 # GitHub shorthand (clones to ~/rally/projects/)
rally onboard https://github.com/o/r     # Full URL
rally onboard owner/repo --fork me/repo  # Fork workflow: origin→fork, upstream→main
rally onboard --team myteam              # Skip interactive team prompt

Onboarding symlinks team files (.squad/, .squad-templates/, .github/agents/) into the project, adds .worktrees/ to .git/info/exclude, and registers the project in projects.yaml.

Removing a project

rally onboard remove [project]   # Interactive picker if project omitted
rally onboard remove myrepo --yes  # Skip confirmation

Dispatching Work

Dispatch to an issue

rally dispatch issue 42                # Dispatch to issue #42
rally dispatch issue 42 --repo o/r     # Specify repo explicitly
rally dispatch issue                   # Interactive picker (choose repo, then issue)
rally dispatch issue 42 --sandbox      # Run in Docker sandbox microVM
rally dispatch issue 42 --trust        # Skip author trust warnings

What happens:

Fetches issue details via gh issue view
Creates branch rally/<number>-<slug> from current HEAD
Creates worktree at <repo>/.worktrees/rally-<number>/
Symlinks .squad/ into the worktree
Writes dispatch-context.md with issue title, body, labels
Launches gh copilot with a prompt to read context and implement a fix
Registers the dispatch in active.yaml

Dispatch to a PR (code review)

rally dispatch pr 15                   # Review PR #15
rally dispatch pr 15 --repo o/r        # Specify repo
rally dispatch pr                      # Interactive picker
rally dispatch pr 15 --prompt review.md  # Custom review prompt file
rally dispatch pr 15 --sandbox         # Docker sandbox

What happens:

Fetches PR details, validates it's open (not merged/closed)
Creates branch rally/pr-<number>-<slug>
Creates worktree at <repo>/.worktrees/rally-pr-<number>/
Fetches the PR head ref and resets the worktree to it
Writes dispatch-context.md with PR title, body, files changed
Launches Copilot with a multi-model review prompt
Review output goes to REVIEW.md in the worktree root

Resume a dispatch

rally dispatch continue 42             # Reconnect to Copilot session for #42
rally dispatch continue 42 -m "focus on tests"  # Send additional instructions
rally dispatch continue 42 --repo o/r

View dispatch logs

rally dispatch log 42                  # View Copilot output log for #42
rally dispatch log 42 -f               # Follow mode (tail)
rally dispatch log 42 --repo o/r

Remove a dispatch

rally dispatch remove 42               # Remove dispatch record for #42
rally dispatch remove 42 --repo o/r

Clean finished dispatches

rally dispatch clean                   # Clean done/reviewing/pushed/cleaned dispatches
rally dispatch clean --all             # Clean ALL dispatches (prompts for confirmation)
rally dispatch clean --all --yes       # Skip confirmation

Cleaning removes the worktree, deletes the local branch, and removes the record from active.yaml.

Refresh statuses

rally dispatch refresh                 # Check if Copilot processes have exited, update statuses

List sessions

rally dispatch sessions                # Show active dispatches with session info

Dashboard

rally dashboard                        # Interactive full-screen TUI
rally dashboard --json                 # JSON output (for scripting)
rally dashboard --project myrepo       # Filter by project name
rally                                  # Default command opens dashboard

Dashboard keyboard shortcuts

Key	Action
`↑` / `↓`	Navigate dispatch list
`Enter`	Open action menu for selected dispatch
`d`	View dispatch details
`v`	Open worktree in VS Code
`o`	Open issue/PR in browser
`a`	Attach to Copilot session (exits dashboard, runs `dispatch continue`)
`c`	Connect IDE — opens VS Code + bridges Copilot session
`l`	View Copilot output log
`n`	New dispatch — browse onboarded projects and pick an issue/PR
`u`	Mark selected dispatch as "upstream"
`x`	Delete selected dispatch
`r`	Refresh dashboard data
`q`	Quit

The dashboard auto-refreshes every 5 seconds.

Status Check

rally status                           # Show config and active dispatches
rally status --json                    # JSON output

Dispatch Status Model

Each dispatch progresses through these statuses:

planning → implementing → reviewing → pushed → done → cleaned

Status	Meaning
`planning`	Issue dispatch created, Copilot is analyzing the issue
`implementing`	Copilot is actively writing code
`reviewing`	PR review dispatch, Copilot is reviewing code
`pushed`	Changes have been pushed (manual status via dashboard `p` key)
`done`	Copilot session has exited
`cleaned`	Worktree and branch removed

Key Concepts

Worktrees

Rally uses git worktrees to isolate each dispatch. Each dispatch gets its own directory under <repo>/.worktrees/:

Issues: .worktrees/rally-<number>/
PRs: .worktrees/rally-pr-<number>/

Worktrees share the same git history as the main repo but have independent working directories and branches.

Configuration directory

Default: ~/rally/ (override with RALLY_HOME env var, legacy ~/.rally/ supported).

Contains:

config.yaml — Rally settings (team dir, projects dir, version)
projects.yaml — registered projects with name, repo, path, team info
active.yaml — all active dispatch records
team/ — shared team configuration (.squad/, templates)
projects/ — cloned repos (when onboarded via URL)

Config settings (`config.yaml` → `settings` key)

Setting	Type	Default	Description
`docker_sandbox`	`always` / `never` / `ask`	`ask`	Docker sandbox usage
`require_trust`	`always` / `never` / `ask`	`ask`	Author/org trust checks
`review_template`	string or null	`null`	Custom review prompt path (relative to config dir)
`deny_tools_copilot`	string[]	DEFAULT_DENY_TOOLS	Tools denied without sandbox
`deny_tools_sandbox`	string[]	DEFAULT_DENY_TOOLS	Tools denied in sandbox

CLI flags (--sandbox, --trust, --prompt) override config settings.

active.yaml

Central state file tracking all dispatches. Each record contains:

id — unique identifier (e.g. myrepo-issue-42)
repo — owner/repo
number — issue or PR number
type — issue or pr
branch — git branch name
worktreePath — absolute path to the worktree
status — current status (see status model above)
session_id — Copilot session ID (or PID, or pending)
pid — Copilot process ID
logPath — path to .copilot-output.log
title — issue/PR title
created — ISO timestamp

projects.yaml

Registry of onboarded projects. Each entry has:

name — repository name
repo — owner/repo
path — absolute local path
team — team type identifier
teamDir — path to team directory
onboarded — ISO timestamp
fork — (optional) fork owner/repo

Read-only dispatch policy

Dispatched Copilot agents run in read-only mode:

CAN: read code, make local edits, run builds/tests, use git locally
CANNOT: git push, run gh CLI commands, use curl/wget/nc/ssh
Remote reads use MCP tools (e.g. github-mcp-server-issue_read)

Repo resolution

When --repo is omitted, Rally resolves the target repo in this order:

--repo owner/repo flag
Current working directory (if inside an onboarded project)
Single-project fallback (if only one project is registered)
Error with list of registered projects

Common Patterns

Full issue workflow

rally onboard owner/repo               # Register the repo (auto-creates ~/rally/ on first run)
rally dispatch issue 42                # Dispatch agent to issue
rally dashboard                        # Monitor progress
rally dispatch log 42                  # Check agent output
rally dispatch continue 42             # Resume if needed
# Review changes in .worktrees/rally-42/
rally dispatch clean                   # Clean up when done

PR review workflow

rally dispatch pr 15                   # Dispatch multi-model review
rally dispatch log 15                  # Check review progress
# Read REVIEW.md in .worktrees/rally-pr-15/
rally dispatch clean                   # Clean up

Multi-project workflow

rally onboard owner/repo-a
rally onboard owner/repo-b
rally dispatch issue 10 --repo owner/repo-a
rally dispatch pr 5 --repo owner/repo-b
rally dashboard                        # See all dispatches across projects

Fork workflow

rally onboard upstream/repo --fork myuser/repo
# origin → myuser/repo (your fork)
# upstream → upstream/repo (main project)
rally dispatch issue 42