{"id":48928383,"url":"https://github.com/fotoetienne/gru","last_synced_at":"2026-04-17T08:06:32.796Z","repository":{"id":347374042,"uuid":"1107315129","full_name":"fotoetienne/gru","owner":"fotoetienne","description":"manage minions like a boss","archived":false,"fork":false,"pushed_at":"2026-04-04T01:42:22.000Z","size":2603,"stargazers_count":2,"open_issues_count":22,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-04T03:29:44.119Z","etag":null,"topics":["claude-code","github-issues","llm"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fotoetienne.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"docs/AGENTS.md","dco":null,"cla":null}},"created_at":"2025-12-01T00:50:05.000Z","updated_at":"2026-04-04T01:42:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fotoetienne/gru","commit_stats":null,"previous_names":["fotoetienne/gru"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/fotoetienne/gru","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fotoetienne%2Fgru","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fotoetienne%2Fgru/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fotoetienne%2Fgru/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fotoetienne%2Fgru/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fotoetienne","download_url":"https://codeload.github.com/fotoetienne/gru/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fotoetienne%2Fgru/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31920524,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T18:22:33.417Z","status":"online","status_checked_at":"2026-04-17T02:00:06.879Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","github-issues","llm"],"created_at":"2026-04-17T08:06:31.860Z","updated_at":"2026-04-17T08:06:32.783Z","avatar_url":"https://github.com/fotoetienne.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gru\n\n[![CI](https://github.com/fotoetienne/gru/actions/workflows/ci.yml/badge.svg)](https://github.com/fotoetienne/gru/actions/workflows/ci.yml)\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n[![Docs](https://img.shields.io/badge/docs-fotoetienne.github.io%2Fgru-blue.svg)](https://fotoetienne.github.io/gru/)\n\n**Gru turns GitHub issues into merged PRs — autonomously, locally, with the AI coding agent of your choice.**\n\nPoint 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.\n\n![Animated terminal demo: running \"gru do \u0026lt;issue\u0026gt;\" — Gru fetches the issue, spawns an agent, and opens a PR autonomously](https://raw.githubusercontent.com/fotoetienne/gru/main/docs/demo.gif)\n\nGru is **agent-agnostic**. It ships with backends for [Claude Code](https://github.com/anthropics/claude-code) and [OpenAI Codex](https://github.com/openai/codex), and its pluggable architecture makes it straightforward to add more.\n\n## Quick Start\n\n```bash\n# Install (macOS Apple Silicon — see Installation for other platforms)\ncurl -fL https://github.com/fotoetienne/gru/releases/latest/download/gru-aarch64-apple-darwin.tar.gz | tar xz\nsudo mv gru /usr/local/bin/\n\n# Initialize a repo\ngru init owner/repo\n\n# Fix an issue — Gru handles the rest\ngru do 42\n```\n\n## Installation\n\n### Prerequisites\n\n- [GitHub CLI](https://cli.github.com/) (`gh`), authenticated\n- At least one agent backend:\n  - [Claude Code](https://github.com/anthropics/claude-code) (default) — `npm install -g @anthropic-ai/claude-code`\n  - [OpenAI Codex](https://github.com/openai/codex) (optional) — `npm install -g @openai/codex`\n\n### Download a Prebuilt Binary\n\nGrab the latest release from [GitHub Releases](https://github.com/fotoetienne/gru/releases/latest):\n\n```bash\n# Set target: aarch64-apple-darwin, x86_64-apple-darwin, or x86_64-unknown-linux-gnu\nTARGET=aarch64-apple-darwin\n\n# Download binary and checksum\ncurl -fLO \"https://github.com/fotoetienne/gru/releases/latest/download/gru-${TARGET}.tar.gz\"\ncurl -fLO \"https://github.com/fotoetienne/gru/releases/latest/download/gru-${TARGET}.tar.gz.sha256\"\n\n# Verify checksum\nsha256sum --check \"gru-${TARGET}.tar.gz.sha256\" 2\u003e/dev/null \\\n  || shasum -a 256 --check \"gru-${TARGET}.tar.gz.sha256\"\n\n# Install\ntar xzf \"gru-${TARGET}.tar.gz\"\nsudo mv gru /usr/local/bin/\n```\n\n### Install from Source\n\nRequires [Rust](https://rustup.rs/) 1.73 or later.\n\n```bash\ngit clone https://github.com/fotoetienne/gru.git\ncd gru\ncargo install --path .\n```\n\nThe `gru` binary is installed to `~/.cargo/bin/gru`. Make sure `~/.cargo/bin` is on your `$PATH`.\n\nFor a detailed walkthrough, see [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md).\n\n## Usage\n\n### Work on Issues\n\n```bash\n# By issue number (from within the repo)\ngru do 42\n\n# By URL (from anywhere)\ngru do https://github.com/owner/repo/issues/42\n\n# With a timeout\ngru do 42 --timeout 30m\n\n# Review the prompt before launching\ngru do 42 --discuss\n\n# Using a different agent backend\ngru do 42 --agent codex\n```\n\nGru 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.\n\n### Review PRs\n\n```bash\ngru review 42\ngru review https://github.com/owner/repo/pull/42\n```\n\n### Interactive Chat\n\n```bash\ngru chat\ngru chat --repo owner/repo\n```\n\n### Product Manager / TPM\n\n```bash\ngru pm                                 # Interactive product manager session\ngru pm \"write a PRD for hooks feature\" # Start with a prompt\ngru tpm                                # Interactive TPM session\ngru tpm \"what's the critical path?\"    # Start with a prompt\n```\n\n### Custom Prompts\n\n```bash\ngru prompt my-prompt --issue 42\ngru prompts                        # List available prompts\n```\n\n### Manage Minions\n\nEach agent session is a \"Minion.\" Track and control them with:\n\n```bash\ngru status              # List all active Minions\ngru status M001         # Details for a specific Minion\ngru logs M001           # View event stream\ngru attach M001         # Attach terminal to a running Minion\ngru stop M001           # Stop a running Minion\ngru resume M001         # Resume a stopped Minion\ngru rebase M001         # Rebase a Minion's branch onto latest base\ngru path M001           # Print the Minion's worktree path\ngru clean               # Remove worktrees for merged/closed PRs\n```\n\n### Multi-Agent Support\n\nGru is not tied to any single AI backend. Use the `--agent` flag to switch:\n\n```bash\ngru do 42                   # Claude Code (default)\ngru do 42 --agent codex     # OpenAI Codex\ngru review 42 --agent codex\ngru prompt my-prompt --agent codex\n```\n\nSet a default in `~/.gru/config.toml`:\n\n```toml\n[agent]\ndefault = \"codex\"\n```\n\n`gru status` shows which agent each Minion is using:\n\n```\nMINION   AGENT    REPO         ISSUE  TASK  PR    BRANCH                MODE                   UPTIME   TOKENS\nM001     claude   owner/repo   #42    do    #43   minion/issue-42-M001  monitoring (PR ready)  5m       1.2M\nM002     codex    owner/repo   #44    do    -     minion/issue-44-M002  working                2m       -\n```\n\nSee [docs/AGENTS.md](docs/AGENTS.md) for setup details and feature comparison.\n\n## Lab Mode\n\nRun Gru as a daemon that continuously polls for `gru:todo` issues and spawns Minions to work on them:\n\n```bash\ngru lab --repos owner/repo\n```\n\nOr configure repos in `~/.gru/config.toml` and run `gru lab` with no arguments:\n\n```toml\n[daemon]\nrepos = [\"owner/frontend\", \"owner/backend\"]\nmax_slots = 4            # default is 2\n```\n\n## MCP Server\n\nGru can act as an MCP (Model Context Protocol) server, giving any Claude session live access to Minion status, logs, and Gru knowledge:\n\n```bash\ngru mcp              # Start stdio MCP server (used by Claude)\ngru mcp install      # Register in ~/.claude.json\ngru mcp uninstall    # Remove from ~/.claude.json\n```\n\nOnce installed, Claude Code sessions can query Minion status and read Gru guides without leaving the conversation.\n\n## Configuration\n\nAll configuration lives in `~/.gru/config.toml`. Everything is optional — Gru works out of the box with sensible defaults.\n\nCopy the annotated example to get started:\n\n```bash\ncp docs/config.example.toml ~/.gru/config.toml\n```\n\nKey options: default agent backend, polling intervals, concurrency slots, merge confidence thresholds, and GitHub Enterprise Server hosts. See [docs/config.example.toml](docs/config.example.toml) for the full reference.\n\n## How It Works\n\n1. `gru init owner/repo` creates a bare git mirror at `~/.gru/repos/`\n2. `gru do 42` creates an isolated worktree under `~/.gru/work/`, spawns the agent, and monitors its progress via streaming JSON\n3. The agent reads the issue, explores the code, makes changes, and runs tests\n4. 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\n5. Gru opens a PR, watches CI, and feeds failures back to the agent for auto-fix (up to 2 attempts before escalating)\n6. Review comments are forwarded to the agent for responses\n7. Labels (`gru:todo` → `gru:in-progress` → `gru:done` / `gru:failed`) track state on GitHub\n\n## Roadmap\n\nV1 is feature-complete: autonomous issue fixing, worktree isolation, lab mode, CI monitoring, PR lifecycle management, multi-agent backends, and Minion management.\n\nFuture plans include multi-Lab coordination (V2), a web UI (V3), issue dependency graphs (V4), and multi-repo orchestration (V5). See [docs/DESIGN.md](docs/DESIGN.md) for the full architecture vision.\n\n## Contributing\n\nContributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup, build commands, testing, and PR workflow.\n\n## License\n\n[Apache License, Version 2.0](LICENSE)\n\n## Related Projects\n\n- [Claude Code](https://github.com/anthropics/claude-code) — CLI for Claude\n- [OpenAI Codex](https://github.com/openai/codex) — CLI for OpenAI models\n- [Emdash](https://github.com/generalaction/emdash) — Orchestration layer supporting 15+ agent CLIs\n- [Code Conductor](https://github.com/ryanmac/code-conductor) — Parallel Claude Code sub-agents with GitHub-native orchestration\n- [Beads](https://github.com/steveyegge/beads) — Git-backed issue tracker with persistent agent memory\n- [Worktree CLI](https://github.com/agenttools/worktree) — Git worktree management for coding agents\n- [Vibe Kanban](https://www.vibekanban.com/) — Local orchestration with kanban-style task management\n- [Cowork](https://support.claude.com/en/articles/13345190-getting-started-with-cowork) — Claude Desktop autonomous task execution\n\n---\n\n\u003cp align=\"center\"\u003emade with love by \u003ca href=\"https://github.com/fotoetienne/gru\"\u003egru\u003c/a\u003e\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffotoetienne%2Fgru","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffotoetienne%2Fgru","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffotoetienne%2Fgru/lists"}