Issue-driven Claude Code orchestrator that automates the work loop from GitHub issue to working code.

Pleb watches a GitHub repository for issues with specific labels. When it finds one:

1. Creates a git worktree for the issue
2. Spins up a tmux session
3. Invokes Claude Code with the issue as the prompt
4. Updates GitHub labels to reflect state (provisioning → waiting → working → done)

You can attach to any session anytime to watch or interact with Claude.

Build and install pleb to your PATH:

cargo install --path .

This installs the binary to ~/.cargo/bin/pleb.

If developing: You may wish to symlink instead so changes are immediately available:

cargo build --release
ln -sf $(pwd)/target/release/pleb ~/.local/bin/pleb

Copy the example config and edit:

./target/release/pleb config init
# Edit pleb.toml with your repo details

[github]
owner = "your-username"
repo = "your-repo"
token_env = "GITHUB_TOKEN"  # env var containing your PAT

[labels]
ready = "pleb:ready"
provisioning = "pleb:provisioning"
waiting = "pleb:waiting"
working = "pleb:working"
done = "pleb:done"

[claude]
command = "claude"
args = ["--dangerously-skip-permissions"]
planning_mode = true

[paths]
worktree_base = "./worktrees"

# Initialize config from example
pleb config init

# Show current config
pleb config show

# Start watching for issues (not yet implemented)
pleb watch

# List active sessions (not yet implemented)
pleb list

# Attach to a session (not yet implemented)
pleb attach <session-name>

Create these labels in your repository:

• pleb:ready - Issue is ready for Pleb to pick up
• pleb:provisioning - Pleb is setting up the environment
• pleb:waiting - Claude is waiting for human input
• pleb:working - Claude is actively working
• pleb:done - Work complete

• GITHUB_TOKEN (or whatever token_env is set to in pleb.toml) - GitHub Personal Access Token

Pleb uses a GitHub Personal Access Token (classic or fine-grained) to interact with the GitHub API. The token must be available in the environment variable specified by token_env in your pleb.toml.

Fine-grained token (recommended) — scope to the target repository:

Classic token — requires the repo scope.

You can verify your token works with:

curl -s -H "Authorization: Bearer $GITHUB_TOKEN" https://api.github.com/user | jq .login

If using Lima for VM-based isolation, install these packages:

sudo apt install qemu-utils qemu-system-x86

To any agents reading this file, if you have been told to "study" this file then also study everything in .planning/