Greenkeeper

Local daemon: watch GitHub PRs you care about, and when something actually needs doing (CI red, merge conflicts, review threads still open), it starts an AI agent in a dedicated git worktree. Your main checkout stays untouched. It never merges for you.

Install

brew install RussellBloxwich/tap/greenkeeper

Or from source:

go install github.com/russellbloxwich/greenkeeper/cmd/greenkeeper@latest

git clone https://github.com/RussellBloxwich/greenkeeper.git
cd greenkeeper
go build -o greenkeeper ./cmd/greenkeeper

Prerequisites

Tool	Required	Purpose
Go 1.26+	Build only	Compiling from source
GitHub CLI (gh)	Yes	PR metadata, CI status, GraphQL
At least one AI provider CLI	Yes	Agent backend (see Providers)

---

Why this exists

Most of my time on multi-PR weeks was not writing features. It was rebasing, re-reading the same failing logs, and clearing review threads. Greenkeeper is my attempt to automate that loop on hardware I already own: one binary, config under ~/.config (nothing in the repo), and whatever gh is already logged into.

The trade-off is on purpose. Everything runs locally, you keep merges and judgment calls, and outbound traffic is only what gh and your provider CLI already do. If you want a hosted autopilot, this is the wrong tool.

What it handles

Problem	Detection	Strategy
Merge conflict	mergeable == CONFLICTING	Rebase onto base branch, resolve, push
CI failure	Failing status checks	Fetch logs, fix, push
Review bot comments	Unresolved bot threads	Address valid findings, push
Human review comments	Unresolved reviewer threads	Triage: fix what is real, reply or resolve what is not

Quick start

greenkeeper init
cd ~/code/my-project
greenkeeper repo add
greenkeeper watch 42
greenkeeper daemon start
greenkeeper list
greenkeeper status

By default the daemon polls every five minutes, picks up watched PRs that need work, and starts sessions until the limits you set. You can close the terminal; it keeps running in the background.

How it works

On each tick it walks the watchlist, asks GitHub (through gh) for merge state, CI, and open review threads, and compares that to what you configured as "needs fixing." If a PR qualifies, it creates or reuses a worktree, builds a prompt with your naming rules and the review context, and execs your provider. When the session exits, it checks GitHub again. Clean PR drops off the list and the worktree goes away.

Rough flow: poll, evaluate each watched PR, maybe start an agent in a worktree, reconcile watchlist and disk on exit.

Multi-repo

Register as many repos as you like. Each can set its own provider and concurrency; the daemon still caps total concurrent sessions so the machine stays usable.

Providers

Pluggable backends via subprocess. Built-in adapters:

Provider	CLI	Notes
Claude Code	claude	Default. Uses -p with the assembled prompt
Codex	codex	OpenAI Codex CLI
Generic	Your shell command	Templates: {{prompt}}, {{prompt_file}}, {{repo_name}}, {{worktree}}

Configure during greenkeeper init or in ~/.config/greenkeeper/config.toml:

[providers.claude]
command = "claude"
args_template = "-p {{prompt}} --allowedTools 'Bash,Read,Write,Edit'"

[default]
provider = "claude"

Commands

Command	Description
greenkeeper init	First-time setup
greenkeeper watch <PR>	Watch a PR (accepts number, URL, or owner/repo#N)
greenkeeper unwatch <PR>	Stop watching and clean up
greenkeeper list	Watched PRs with CI and session status
greenkeeper status	Daemon and sessions
greenkeeper daemon start|stop|status	Daemon control
greenkeeper logs [--pr N] [--follow]	Logs
greenkeeper repo add|remove|list	Registered repos
greenkeeper config show|edit|set	Config
greenkeeper clean [--dry-run] [--all] [--repo <name>]	Stale worktrees and logs
greenkeeper stats	Session success rate and per-PR breakdown from daemon logs
greenkeeper doctor	Check prerequisites, auth, config, and providers
greenkeeper completion <bash|zsh|fish>	Generate shell completions
greenkeeper version	Version

Use --json or --no-color on supported commands when you need scripts or plain output.

Configuration

Global file: ~/.config/greenkeeper/config.toml. Per-repo sections are [repos.<name>] only. No project-local greenkeeper config files, by design.

[daemon]
poll_interval = 300
max_concurrent = 2
max_session_runtime = 32400
auto_watch = true

[default]
provider = "claude"
review_bot_usernames = ["cursor"]

[naming]
commit_style = "conventional commits, lowercase, concise"
branch_style = "kebab-case, prefix with fix/ or chore/"

Safety

• No auto-merge. It fixes branches; you merge when you want.
• Worktree isolation. One worktree per PR session.
• Pushes. Uses --force-with-lease after rebases, not blind --force. No amend on published history.
• Scoped changes. Prompts aim at the failure or review, not drive-by refactors.
• Session cap. Long-running sessions stop after max_session_runtime (default nine hours).
• No telemetry in the binary itself. Network is whatever gh and your provider already use.

Automation that can push branches deserves the same respect as any other power tool: read the config, try it on a low-stakes repo first, and do not aim it at production until you are happy with how it behaves.

Disabling co-author attribution (Claude Code)

If you want commits without provider footers:

{
  "attribution": {
    "commit": "",
    "pr": ""
  }
}

Put that in ~/.claude/settings.json (or the path your Claude Code install uses).

Documentation

• SPEC.md Full behaviour and config reference
• CONTRIBUTING.md Hacking on the Go codebase
• RELEASING.md Tags and Homebrew releases
• SECURITY.md Reporting issues responsibly
• CHANGELOG.md Release notes
• LICENSE MIT

License

MIT