Getting Started with Gru

This guide walks you from zero to your first autonomous PR in about 10 minutes.

Prerequisites

Before you start, you need:

  1. Rust (1.73 or later)

    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustc --version  # should print 1.73+

  2. GitHub CLI (gh) — authenticated

    brew install gh       # or see https://cli.github.com/
gh auth login         # follow the prompts
gh auth status        # confirm: "Logged in to github.com"

  3. Claude Code (default agent backend)

    npm install -g @anthropic-ai/claude-code
claude --version      # confirm it's installed

    Using OpenAI Codex instead? See AGENTS.md.

Install Gru

git clone https://github.com/fotoetienne/gru.git
cd gru
cargo install --path .
gru --version   # confirm: prints version number

The gru binary is now at ~/.cargo/bin/gru. Make sure ~/.cargo/bin is on your $PATH.

Initialize a Repo

Tell Gru about the repo you want to automate:

gru init owner/repo

This creates a bare git mirror at ~/.gru/repos/owner/repo.git/. Gru uses bare repos so Minions can work in isolated worktrees without interfering with each other or your own working directory.

You only need to run gru init once per repo.

Label an Issue

Gru picks up issues labeled gru:todo. Find a small, well-scoped issue in your repo and add the label:

gh issue edit 42 --add-label "gru:todo" --repo owner/repo

Note: gru init automatically creates all required gru:* labels when you initialize a repo, so you normally don't need to create them manually.

Tip: Start with a small bug fix or docs update. A focused issue with clear acceptance criteria gives Gru the best chance of getting it right on the first try.

Run gru do

Now kick off the agent:

# From inside the repo
gru do 42

# Or from anywhere with a full URL
gru do https://github.com/owner/repo/issues/42

Here's what happens:

  1. Worktree created — Gru creates an isolated git checkout at ~/.gru/work/owner/repo/minion/issue-42-M001/checkout/. Your working directory is untouched.
  2. Agent spawned — Claude Code starts in that worktree with the issue as its task. It has full tool access: reading/writing files, running tests, calling the GitHub API.
  3. PR created — When the agent is satisfied, it opens a draft PR and continues monitoring.
  4. CI and reviews handled — Gru watches for CI failures and review comments, feeding them back to the agent for fixes.

The terminal shows a live progress stream. You'll see tool calls, test runs, and status updates as they happen.

Monitor Progress

You can check in on running Minions at any time:

gru status          # list all active Minions

Output looks like:

MINION   AGENT    REPO        ISSUE    TASK  PR    BRANCH                MODE                   UPTIME   TOKENS
M001     claude   owner/repo  #42      -     #43   minion/issue-42-M001  monitoring (PR ready)  5m       1.2M

Attach to a running Minion to see the live stream:

gru attach M001

Press Ctrl-C to exit the interactive session — the Minion is paused. Run gru resume M001 to let it continue working autonomously.

If you need to pause:

gru stop M001       # stop the Minion
gru resume M001     # pick up where it left off

See the Result

Once the agent finishes its work, you'll have a PR open against your repo. Gru marks it ready for review when CI passes and any requested changes are addressed.

gh pr view 43 --repo owner/repo --web   # open in browser

The PR description includes a summary of what changed and a test plan generated by the agent. Review it, request changes if needed — Gru will handle the responses.

When the PR is merged, the worktree is cleaned up automatically. Or clean up manually:

gru clean   # removes worktrees for merged/closed PRs

Next Steps

  • GitHub Enterprise Server — Using GHES instead of github.com? See docs/GHES_SETUP.md for a step-by-step walkthrough.
  • Configure defaults — ~/.gru/config.toml lets you set a default agent backend, polling intervals, merge thresholds, and more. Copy docs/config.example.toml to ~/.gru/config.toml and uncomment the sections you need. The example file includes annotated explanations of every option.
  • Lab mode — Run gru lab to let Gru continuously pick up gru:todo issues and work on them unattended. Useful for letting it run overnight.
  • Multiple backends — Use gru do 42 --agent codex to use OpenAI Codex instead of Claude. See docs/AGENTS.md for setup.
  • Architecture — Curious how it all fits together? docs/DESIGN.md covers the full system design.