Skillget

gru

skill
Security Audit
Warn
Health Warn
  • License — License: Apache-2.0
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 5 GitHub stars
Code Pass
  • Code scan — Scanned 7 files during light audit, no dangerous patterns found
Permissions Pass
  • Permissions — No dangerous permissions requested
Purpose

This tool autonomously turns GitHub issues into merged pull requests. It uses an isolated git worktree and integrates with AI coding agents (like Claude Code or OpenAI Codex) to handle the implementation, review, and CI fixing processes.

Security Assessment

Overall Risk: Medium. The light code audit found no hardcoded secrets, dangerous patterns, or requests for overly broad permissions. However, by design, this tool inherently requires significant system access. It reads and writes to local git repositories, heavily executes shell commands to orchestrate AI agents and GitHub CLI operations, and makes external network requests to GitHub and third-party AI APIs. While it operates inside an isolated git worktree to protect your active directory, trusting this tool means trusting the prompt outputs and commands executed by the integrated AI models.

Quality Assessment

The project is licensed under the permissive Apache-2.0 license and includes automated CI testing. The repository is highly active, with its most recent push occurring today. The primary drawback is its extremely low community visibility; having only 5 GitHub stars means it has not been widely peer-reviewed or battle-tested by a large user base.

Verdict

Use with caution. The code itself appears safe and well-structured, but users must implicitly trust the external AI models it orchestrates and the commands they generate.
SUMMARY

manage minions like a boss

README.md

Gru

CI
License: Apache 2.0

Gru turns GitHub issues into merged PRs — autonomously, locally, with the AI coding agent of your choice.

Point it at an issue and it handles the rest: implementation, PR, code review, CI fixes, rebases — all in an isolated worktree that never touches your working directory.

Gru is agent-agnostic. It ships with backends for Claude Code and OpenAI Codex, and its pluggable architecture makes it straightforward to add more.

Quick Start

# Install (macOS Apple Silicon — see Installation for other platforms)
curl -fL https://github.com/fotoetienne/gru/releases/latest/download/gru-aarch64-apple-darwin.tar.gz | tar xz
sudo mv gru /usr/local/bin/

# Initialize a repo
gru init owner/repo

# Fix an issue — Gru handles the rest
gru do 42

Installation

Prerequisites

  • GitHub CLI (gh), authenticated
  • At least one agent backend:
    • Claude Code (default) — npm install -g @anthropic-ai/claude-code
    • OpenAI Codex (optional) — npm install -g @openai/codex

Download a Prebuilt Binary

Grab the latest release from GitHub Releases:

# Set target: aarch64-apple-darwin, x86_64-apple-darwin, or x86_64-unknown-linux-gnu
TARGET=aarch64-apple-darwin

# Download binary and checksum
curl -fLO "https://github.com/fotoetienne/gru/releases/latest/download/gru-${TARGET}.tar.gz"
curl -fLO "https://github.com/fotoetienne/gru/releases/latest/download/gru-${TARGET}.tar.gz.sha256"

# Verify checksum
sha256sum --check "gru-${TARGET}.tar.gz.sha256" 2>/dev/null \
  || shasum -a 256 --check "gru-${TARGET}.tar.gz.sha256"

# Install
tar xzf "gru-${TARGET}.tar.gz"
sudo mv gru /usr/local/bin/

Install from Source

Requires Rust 1.73 or later.

git clone https://github.com/fotoetienne/gru.git
cd gru
cargo install --path .

The gru binary is installed to ~/.cargo/bin/gru. Make sure ~/.cargo/bin is on your $PATH.

For a detailed walkthrough, see docs/GETTING_STARTED.md.

Usage

Work on Issues

# By issue number (from within the repo)
gru do 42

# By URL (from anywhere)
gru do https://github.com/owner/repo/issues/42

# With a timeout
gru do 42 --timeout 30m

# Review the prompt before launching
gru do 42 --discuss

# Using a different agent backend
gru do 42 --agent codex

Gru creates an isolated git worktree, spawns the agent, streams progress to your terminal, opens a PR when ready, then monitors CI and reviews — fixing failures and responding to feedback automatically.

Review PRs

gru review 42
gru review https://github.com/owner/repo/pull/42

Interactive Chat

gru chat
gru chat --repo owner/repo

Product Manager / TPM

gru pm                                 # Interactive product manager session
gru pm "write a PRD for hooks feature" # Start with a prompt
gru tpm                                # Interactive TPM session
gru tpm "what's the critical path?"    # Start with a prompt

Custom Prompts

gru prompt my-prompt --issue 42
gru prompts                        # List available prompts

Manage Minions

Each agent session is a "Minion." Track and control them with:

gru status              # List all active Minions
gru status M001         # Details for a specific Minion
gru logs M001           # View event stream
gru attach M001         # Attach terminal to a running Minion
gru stop M001           # Stop a running Minion
gru resume M001         # Resume a stopped Minion
gru rebase M001         # Rebase a Minion's branch onto latest base
gru path M001           # Print the Minion's worktree path
gru clean               # Remove worktrees for merged/closed PRs

Multi-Agent Support

Gru is not tied to any single AI backend. Use the --agent flag to switch:

gru do 42                   # Claude Code (default)
gru do 42 --agent codex     # OpenAI Codex
gru review 42 --agent codex
gru prompt my-prompt --agent codex

Set a default in ~/.gru/config.toml:

[agent]
default = "codex"

gru status shows which agent each Minion is using:

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

See docs/AGENTS.md for setup details and feature comparison.

Lab Mode

Run Gru as a daemon that continuously polls for gru:todo issues and spawns Minions to work on them:

gru lab --repos owner/repo

Or configure repos in ~/.gru/config.toml and run gru lab with no arguments:

[daemon]
repos = ["owner/frontend", "owner/backend"]
max_slots = 4            # default is 2

MCP Server

Gru can act as an MCP (Model Context Protocol) server, giving any Claude session live access to Minion status, logs, and Gru knowledge:

gru mcp              # Start stdio MCP server (used by Claude)
gru mcp install      # Register in ~/.claude.json
gru mcp uninstall    # Remove from ~/.claude.json

Once installed, Claude Code sessions can query Minion status and read Gru guides without leaving the conversation.

Configuration

All configuration lives in ~/.gru/config.toml. Everything is optional — Gru works out of the box with sensible defaults.

Copy the annotated example to get started:

cp docs/config.example.toml ~/.gru/config.toml

Key options: default agent backend, polling intervals, concurrency slots, merge confidence thresholds, and GitHub Enterprise Server hosts. See docs/config.example.toml for the full reference.

How It Works

  1. gru init owner/repo creates a bare git mirror at ~/.gru/repos/
  2. gru do 42 creates an isolated worktree under ~/.gru/work/, spawns the agent, and monitors its progress via streaming JSON
  3. The agent reads the issue, explores the code, makes changes, and runs tests
  4. After committing, the agent spawns a code-reviewer subagent to review changes for correctness, security, conventions, and test coverage — issues found are addressed before the PR is created
  5. Gru opens a PR, watches CI, and feeds failures back to the agent for auto-fix (up to 2 attempts before escalating)
  6. Review comments are forwarded to the agent for responses
  7. Labels (gru:todo → gru:in-progress → gru:done / gru:failed) track state on GitHub

Roadmap

V1 is feature-complete: autonomous issue fixing, worktree isolation, lab mode, CI monitoring, PR lifecycle management, multi-agent backends, and Minion management.

Future plans include multi-Lab coordination (V2), a web UI (V3), issue dependency graphs (V4), and multi-repo orchestration (V5). See docs/DESIGN.md for the full architecture vision.

Contributing

Contributions are welcome! See CONTRIBUTING.md for dev setup, build commands, testing, and PR workflow.

License

Apache License, Version 2.0

Related Projects

  • Claude Code — CLI for Claude
  • OpenAI Codex — CLI for OpenAI models
  • Emdash — Orchestration layer supporting 15+ agent CLIs
  • Code Conductor — Parallel Claude Code sub-agents with GitHub-native orchestration
  • Beads — Git-backed issue tracker with persistent agent memory
  • Worktree CLI — Git worktree management for coding agents
  • Vibe Kanban — Local orchestration with kanban-style task management
  • Cowork — Claude Desktop autonomous task execution

made with love by gru

Reviews (0)

No results found