Usage Guide

This guide covers all gh-worker commands and common workflows. New to ghw? Start with the Walkthrough Guide for a step-by-step tutorial.

Global Options

All commands support the following global options:

• --log-level - Set logging level (DEBUG, INFO, WARNING, ERROR). Default: INFO
• --config-path - Path to config file (default: ~/.config/gh-worker/config.yaml)
• --help / -h - Display help for the current command
• --help --all / -h --all - Print help for all commands and subcommands at once

Examples:

# Enable debug logging
ghw --log-level DEBUG issues sync --repo owner/repo

# Use custom config file
ghw issues sync --repo owner/repo --config-path /path/to/config.yaml

# Print help for every command
ghw --help --all

Commands Overview

gh-worker provides the following commands (in help order):

• init - Initialize configuration interactively
• repositories - Manage tracked repositories (add, list, remove)
• issues - Sync, plan, review, implement, and list issues (sync, list, plan, review, implement)
• monitor - Monitor ongoing implementations
• work - Run complete workflow (sync → plan → implement)
• config - Manage configuration

Command Reference

Init Command

Initialize gh-worker configuration interactively.

ghw init

This command guides you through setting up gh-worker by:

1. Prompting for required configuration (issues-path, repository-path)
2. Validating paths and creating directories
3. Setting sensible defaults for parallelism and agents
4. Saving configuration to ~/.config/gh-worker/config.yaml

Examples:

# Initialize with default config location
ghw init

# Initialize with custom config location
ghw init --config-path /path/to/config.yaml

What Gets Configured:

• issues-path - Where to store synced issues
• repository-path - Where to clone repositories
• plan.parallelism - How many plans to generate concurrently (default: 1)
• plan.agent - Agent for planning (overrides agent.default when set)
• plan.model - Model for planning (overrides agent.model when set)
• implement.parallelism - How many implementations to run concurrently (default: 1)
• implement.agent - Agent for implementation (overrides agent.default when set)
• implement.model - Model for implementation (overrides agent.model when set)
• implement.use_worktree - Use git worktree for implementations (default: True)
• implement.push_branch - Auto-push branches after implementation (default: False)
• implement.create_pr - Auto-create PRs after implementation (default: False)
• agent.default - Default LLM agent to use (default: "claude-code")

Config Command

Manage gh-worker configuration.

# List all configuration values
ghw config --list

# Get a value (provide only the key)
ghw config <key>

# Set a value (provide key and value)
ghw config <key> <value>

List All Configuration Values:

# Output all keys and values in key=value format
ghw config --list

Get Configuration Value:

# Get issues path
ghw config issues-path

# Get nested value using dot notation
ghw config plan.parallelism

Set Configuration Value:

# Set issues path
ghw config issues-path ~/gh-worker/issues

# Set nested value
ghw config plan.parallelism 3

# Set boolean values
ghw config implement.use_worktree true

Notes: - The command automatically detects whether you're getting or setting based on the number of arguments - Use dot notation for nested configuration keys (e.g., plan.parallelism) - Boolean values should be specified as true or false (lowercase)

Repositories Commands

Manage tracked repositories with ghw repositories:

ghw repositories add <repo> [<repo2> ...]
ghw repositories list
ghw repositories remove <repo> [<repo2> ...]

add

Add repositories to track.

1. Creates the necessary directory structure
2. Initializes issue storage in issues-path
3. Optionally clones to repository-path with --clone (otherwise cloned on-demand when running ghw issues plan or ghw issues implement)

Examples:

# Add a single repository (no clone by default)
ghw repositories add owner/repo

# Add and clone immediately
ghw repositories add owner/repo --clone

# Add multiple repositories
ghw repositories add owner/repo1 owner/repo2 owner/repo3

list

List all repositories under management (repositories with a directory under issues-path).

Examples:

# List all tracked repositories
ghw repositories list

# Use custom config
ghw repositories list --config-path /path/to/config.yaml

remove

Remove repositories from tracking.

1. Removes the repository directory from issues-path (including all synced issues and plans)
2. By default, keeps the cloned repository in repository-path (use --no-keep-clone to also remove it)

Examples:

# Remove a single repository (keeps clone by default)
ghw repositories remove owner/repo

# Remove multiple repositories
ghw repositories remove owner/repo1 owner/repo2

# Also remove the cloned repository
ghw repositories remove owner/repo --no-keep-clone

Issues Commands

Sync, plan, and implement issues with ghw issues:

ghw issues sync [--repo REPO | --all-repos] [OPTIONS]
ghw issues list [--repo REPO | --all-repos] [OPTIONS]
ghw issues plan [--repo REPO] [OPTIONS]
ghw plans review [--repo REPO] <issue-number> [OPTIONS]
ghw issues review [--repo REPO] [OPTIONS]
ghw issues implement [--repo REPO] [OPTIONS]

sync

Sync GitHub issues to local files for processing.

Sync a Specific Repository

ghw issues sync --repo <owner/repo>

Examples:

# Sync all issues (open and closed)
ghw issues sync --repo owner/repo

# Sync issues updated in last 7 days
ghw issues sync --repo owner/repo --since 7d

# Sync issues updated in last 2 hours
ghw issues sync --repo owner/repo --since 2h

# Sync specific issues
ghw issues sync --repo owner/repo --issue-numbers 42 43 44

# Filter by assignee (use @me for current user)
ghw issues sync --repo owner/repo --assignee @me

# Force refresh all issues (re-fetch and update description.md)
ghw issues sync --repo owner/repo --force

Sync All Repositories

ghw issues sync --all-repos

This syncs all repositories you've added with the add command.

Sync with Search Query

ghw issues sync --repo owner/repo --search "label:bug is:open"

Uses GitHub's search syntax to filter issues.

Time-Based Sync

The --since flag accepts duration strings:

# Last hour
ghw issues sync --repo owner/repo --since 1h

# Last 30 minutes
ghw issues sync --repo owner/repo --since 30m

# Last 7 days
ghw issues sync --repo owner/repo --since 7d

# Last 2 weeks
ghw issues sync --repo owner/repo --since 14d

list

List synced issues with plan and implementation status in a table.

# List issues for a repository
ghw issues list --repo owner/repo

# List issues from all repositories
ghw issues list --all-repos

# Filter by title (substring match)
ghw issues list --repo owner/repo --title "bug"

# Filter by author (use @me for current user)
ghw issues list --repo owner/repo --author @me

# Filter by assignee (use @me for current user)
ghw issues list --repo owner/repo --assignee @me

# Filter by plan status: none, being generated, waiting for local review, approved
ghw issues list --repo owner/repo --plan approved

# Filter by implementation status: none, being generated, waiting for local review, PR opened, merged, failed
ghw issues list --repo owner/repo --implementation none

plan

Generate implementation plans for synced issues using LLM agents.

Generate Plans for a Repository

ghw issues plan --repo <owner/repo>

This generates plans for all issues in the repository that don't already have plans.

Generate Plans for All Repositories

ghw issues plan --all-repos

This generates plans for all repositories you've added with the add command.

Examples:

# Generate plans with default parallelism
ghw issues plan --repo owner/repo

# Generate plans with custom parallelism
ghw issues plan --repo owner/repo --parallelism 5

Generate Plan for Specific Issues

ghw issues plan --repo owner/repo --issue-numbers 42 43

Use Cases:

• Regenerate a plan after issue updates
• Generate plans for specific high-priority issues
• Test plan generation on a single issue

Parallelism

Control how many issues are planned concurrently:

# Plan 5 issues in parallel
ghw issues plan --repo owner/repo --parallelism 5

The parallelism value overrides the configured default for this execution.

Force Regeneration

Force plan generation even if a plan already exists:

# Regenerate plan for an issue
ghw issues plan --repo owner/repo --issue-numbers 42 --force

Agent Override

Use a different agent for planning:

# Use Cursor agent instead of default
ghw issues plan --repo owner/repo --agent cursor-agent

# Use mock agent for testing
ghw issues plan --repo owner/repo --agent mock

# Filter by assignee (use @me for current user)
ghw issues plan --repo owner/repo --assignee @me

review plan

Review and approve implementation plans before running the implement step.

# Review a plan (creates worktree with plan symlinked for editing)
ghw plans review --repo owner/repo 42

# Approve a plan
ghw plans approve --repo owner/repo 42

# Unapprove a plan (revert to pending)
ghw plans unapprove --repo owner/repo 42

review

Review code implementations using LLM agents to ensure quality.

# Review all implementations
ghw issues review --repo owner/repo

# Review specific issue
ghw issues review --repo owner/repo --issue-numbers 42

# Use custom parallelism
ghw issues review --repo owner/repo --parallelism 2

# Use different agent
ghw issues review --repo owner/repo --agent cursor-agent

# Force re-review even if already reviewed
ghw issues review --repo owner/repo --issue-numbers 42 --force

What Happens During Review:

1. Agent validation checks if required CLI tools are available
2. Creates a git worktree for the PR branch (if needed)
3. Fetches PR information from GitHub (branch name, description)
4. Agent reads the issue and plan (if available)
5. Reviews the code implementation against the plan/issue
6. Writes the review outcome to review.md in the issue's directory
7. Updates plan metadata with review status

Note: A plan does not need to exist for review. If no plan is available, the review uses the PR description from GitHub.

implement

Execute implementation plans and create pull requests using git worktree for isolated development.

Implement Planned Issues for a Repository

ghw issues implement --repo <owner/repo>

This implements all issues in the repository that have plans but haven't been implemented yet.

Implement Plans for All Repositories

ghw issues implement --all-repos

This implements planned issues for all repositories you've added with the add command.

Examples:

# Implement with default parallelism
ghw issues implement --repo owner/repo

# Implement with custom parallelism
ghw issues implement --repo owner/repo --parallelism 2

# Use different agent
ghw issues implement --repo owner/repo --agent cursor-agent

Implement Specific Issues

ghw issues implement --repo owner/repo --issue-numbers 42

Use Cases:

• Implement a specific high-priority issue
• Re-implement after manual changes
• Test implementation on a single issue

Git Worktree Support

By default, gh-worker uses git worktree to create isolated workspaces for each implementation:

# Use worktree (default behavior)
ghw issues implement --repo owner/repo --use-worktree

# Disable worktree (work directly in main repo)
ghw issues implement --repo owner/repo --use-worktree=false

Benefits of Worktree:

• Parallel implementations don't conflict
• Main repository stays clean
• Easy to switch between implementations
• Automatic cleanup after completion

PR Automation

Control whether branches are pushed and PRs are created automatically:

# Push branch but don't create PR
ghw issues implement --repo owner/repo --push-branch

# Push branch and create PR automatically
ghw issues implement --repo owner/repo --push-branch --create-pr

# Keep worktree after implementation (for debugging)
ghw issues implement --repo owner/repo --delete-worktree=false

Examples:

# Full automation: worktree, push, and create PR
ghw issues implement --repo owner/repo --use-worktree --push-branch --create-pr

# Manual PR creation: implement and push only
ghw issues implement --repo owner/repo --push-branch

What Happens During Implementation

1. Agent validation checks if required CLI tools are available
2. Creates a git worktree for isolated development (if enabled)
3. Agent reads the issue and plan
4. Creates a new branch (e.g., issue-42-fix-login-bug)
5. Makes code changes according to the plan
6. Agent generates and creates a commit with descriptive message
7. Pushes the branch to GitHub (if --push-branch enabled)
8. Creates a pull request with implementation details (if --create-pr enabled)
9. Deletes the worktree (if --delete-worktree enabled, default)

Force Re-implementation

Force implementation even if the issue was already completed:

# Re-implement an issue
ghw issues implement --repo owner/repo --issue-numbers 42 --force

Agent Override

Override the default agent for specific implementations:

# Use Claude Code agent
ghw issues implement --repo owner/repo --agent claude-code

# Use Cursor agent
ghw issues implement --repo owner/repo --agent cursor-agent

# Use mock agent (for testing)
ghw issues implement --repo owner/repo --agent mock

# Filter by assignee (use @me for current user)
ghw issues implement --repo owner/repo --assignee @me

Monitor Command

Monitor an ongoing LLM agent session (plan or implementation) in real-time.

ghw monitor --repo <owner/repo> --issue-number <number>

Examples:

# Monitor issue #42
ghw monitor --repo owner/repo --issue-number 42

What You'll See:

• Agent status updates
• Tool usage (file reads, edits, command execution)
• Progress indicators
• Error messages
• Completion status

Use Cases:

• Watch long-running plan generation or implementations
• Debug implementation issues
• Understand what the agent is doing

Note: Monitor requires a session ID in the plan metadata. It works for implementations; support for monitoring plan generation depends on the agent.

Work Command

Run the complete workflow: sync → plan → implement.

Run Once

Process all pending issues once and exit:

ghw work --once --repo owner/repo

Examples:

# Process one repository
ghw work --once --repo owner/repo

# Process all repositories (omit --repo)
ghw work --once

# Process recent issues only
ghw work --once --repo owner/repo --since 1d

# Process specific issues
ghw work --once --repo owner/repo --issue-numbers 42 43

Continuous Mode

Run continuously, processing issues at regular intervals:

ghw work --repo owner/repo

Examples:

# Use default frequency (from config)
ghw work --repo owner/repo

# Use custom frequency
ghw work --repo owner/repo --frequency 30m

# Run across all repositories
ghw work --frequency 15m

In continuous mode, gh-worker will:

1. Sync issues
2. Generate plans for new issues
3. Implement planned issues
4. Wait for the specified frequency
5. Repeat

Stop Continuous Mode: Press Ctrl+C to gracefully stop.

Common Workflows

Quick Start Workflow

Set up and process a repository:

# 1. Initialize configuration (interactive)
ghw init

# OR configure manually
ghw config issues-path ~/gh-worker/issues
ghw config repository-path ~/gh-worker/repos

# 2. Add repository
ghw repositories add owner/repo

# 3. Sync issues
ghw issues sync --repo owner/repo

# 4. Generate plans
ghw issues plan --repo owner/repo

# 5. (Optional) Review and approve plans
ghw plans approve --repo owner/repo 42

# 6. Implement with full automation
ghw issues implement --repo owner/repo --push-branch --create-pr

Daily Issue Processing

Process new issues from the last day:

# Sync, plan, and implement recent issues
ghw work --once --repo owner/repo --since 1d

Schedule with Cron:

# Add to crontab (run daily at 9 AM)
0 9 * * * /path/to/ghw work --once --repo owner/repo --since 1d

Continuous Monitoring

Monitor and process issues continuously:

# Check every 30 minutes
ghw work --repo owner/repo --frequency 30m

Run as a Service (systemd example):

# /etc/systemd/system/gh-worker.service
[Unit]
Description=gh-worker continuous mode
After=network.target

[Service]
Type=simple
User=youruser
ExecStart=/path/to/ghw work --repo owner/repo --frequency 30m
Restart=on-failure

[Install]
WantedBy=multi-user.target

Batch Processing

Process a batch of specific issues:

# Sync specific issues
ghw issues sync --repo owner/repo --issue-numbers 42 43 44 45 46

# Generate plans in parallel
ghw issues plan --repo owner/repo --issue-numbers 42 43 44 45 46 --parallelism 3

# Implement sequentially (safer for complex changes)
ghw issues implement --repo owner/repo --issue-numbers 42 43 44 45 46 --parallelism 1

Review-Before-Implement Workflow

Generate plans, review and approve them, then implement:

# 1. Sync issues
ghw issues sync --repo owner/repo

# 2. Generate plans
ghw issues plan --repo owner/repo

# 3. Review and approve plans
ghw plans approve --repo owner/repo 42
ghw plans approve --repo owner/repo 43

# 4. Implement approved issues
ghw issues implement --repo owner/repo --issue-numbers 42 43

Bug Triage Workflow

Process issues with specific labels:

# Sync bugs only
ghw issues sync --repo owner/repo --search "label:bug is:open"

# Generate plans
ghw issues plan --repo owner/repo

# Review and implement selectively
ghw issues implement --repo owner/repo --issue-numbers 42

High-Parallelism Processing

Process many issues quickly:

# Sync all issues
ghw issues sync --repo owner/repo

# Generate plans with high parallelism
ghw issues plan --repo owner/repo --parallelism 5

# Implement with moderate parallelism
ghw issues implement --repo owner/repo --parallelism 2

Best Practices

Start Small

When starting with a new repository:

1. Sync a few issues: ghw issues sync --repo owner/repo --issue-numbers 1 2 3
2. Generate one plan: ghw issues plan --repo owner/repo --issue-numbers 1
3. Review the plan manually
4. Implement if satisfied: ghw issues implement --repo owner/repo --issue-numbers 1

Use Appropriate Parallelism

• Planning: Can be parallelized more aggressively (3-5)
• Implementation: Keep lower to avoid conflicts (1-2)

Review Plans Before Implementation

Use the review command to approve plans before implementing:

# Review and approve a plan
ghw plans approve --repo owner/repo 42

Or inspect plans manually:

# View a plan
cat ~/gh-worker/issues/owner/repo/42/plan-*.md

Monitor Long-Running Implementations

For complex issues, monitor progress:

# In one terminal: implement
ghw issues implement --repo owner/repo --issue-numbers 42

# In another terminal: monitor
ghw monitor --repo owner/repo --issue-number 42

Use Time-Based Sync

Instead of syncing all issues, sync recent ones:

# Last week's issues
ghw issues sync --repo owner/repo --since 7d

Organize by Repository

Keep separate issue and repository paths for different projects:

# Project 1
ghw config issues-path ~/gh-worker/project1/issues
ghw config repository-path ~/gh-worker/project1/repos

# Project 2
ghw config issues-path ~/gh-worker/project2/issues
ghw config repository-path ~/gh-worker/project2/repos

Troubleshooting

No Issues Synced

Check that you have access to the repository:

gh repo view owner/repo

Plans Not Generated

Verify the agent is working:

# For Claude Code
claude-code --version

# For Cursor agent
cursor-agent --version

# Check agent configuration
ghw config agent.default

# Try using a different agent
ghw issues plan --repo owner/repo --agent cursor-agent

Implementation Fails

Check the agent output:

# Monitor the implementation
ghw monitor --repo owner/repo --issue-number 42

Review logs in the issue directory:

ls -la ~/gh-worker/issues/owner/repo/42/

Rate Limiting

If you hit GitHub API rate limits:

1. Reduce parallelism
2. Increase sync frequency
3. Use --since to sync fewer issues

Next Steps

• Configuration - Configure gh-worker
• Agents - Understand the agent system
• Architecture - Technical deep dive
• Troubleshooting - Solve common issues