Skip to content

Usage Guide

This guide covers all gh-worker commands and common workflows.

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)

Examples:

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

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

Commands Overview

gh-worker provides the following commands:

  • init - Initialize configuration interactively
  • config - Manage configuration
  • add - Add repositories to track
  • sync - Sync GitHub issues to local files
  • plan - Generate implementation plans
  • implement - Execute plans and create PRs
  • monitor - Monitor ongoing implementations
  • work - Run complete workflow (sync → plan → implement)

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)
  • implement.parallelism - How many implementations to run concurrently (default: 1)
  • 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.

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

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

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)

Add Command

Add repositories to track with gh-worker.

ghw add <repo> [<repo2> ...]

This command:

  1. Creates the necessary directory structure
  2. Clones the repository to repository-path
  3. Initializes issue storage in issues-path

Examples:

# Add a single repository
ghw add owner/repo

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

Sync Command

Sync GitHub issues to local files for processing.

Sync a Specific Repository

ghw sync --repo <owner/repo>

Examples:

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

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

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

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

Sync All Repositories

ghw sync --all-repos

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

Sync with Search Query

ghw 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 sync --repo owner/repo --since 1h

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

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

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

Plan Command

Generate implementation plans for synced issues using LLM agents.

Generate Plans for a Repository

ghw 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 plan --all-repos

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

Examples:

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

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

Generate Plan for Specific Issues

ghw 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 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 plan --repo owner/repo --issue-numbers 42 --force

Agent Override

Use a different agent for planning:

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

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

Implement Command

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

Implement Planned Issues for a Repository

ghw 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 implement --all-repos

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

Examples:

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

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

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

Implement Specific Issues

ghw 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 implement --repo owner/repo --use-worktree

# Disable worktree (work directly in main repo)
ghw 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 implement --repo owner/repo --push-branch

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

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

Examples:

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

# Manual PR creation: implement and push only
ghw 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 implement --repo owner/repo --issue-numbers 42 --force

Agent Override

Override the default agent for specific implementations:

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

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

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

Monitor Command

Monitor an ongoing LLM agent session 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 implementations
  • Debug implementation issues
  • Understand what the agent is doing

Work Command

Run the complete workflow: sync → plan → implement.

Run Once

Process all pending issues once and exit:

ghw work --once --repos owner/repo

Examples:

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

# Process multiple repositories
ghw work --once --repos owner/repo1 owner/repo2

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

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

Continuous Mode

Run continuously, processing issues at regular intervals:

ghw work --repos owner/repo

Examples:

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

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

# Process multiple repositories
ghw work --repos owner/repo1 owner/repo2 --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 add owner/repo

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

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

# 5. Implement with full automation
ghw 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 --repos owner/repo --since 1d

Schedule with Cron:

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

Continuous Monitoring

Monitor and process issues continuously:

# Check every 30 minutes
ghw work --repos 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 --repos owner/repo --frequency 30m
Restart=on-failure

[Install]
WantedBy=multi-user.target

Batch Processing

Process a batch of specific issues:

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

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

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

Review-Before-Implement Workflow

Generate plans for review before implementation:

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

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

# 3. Review plans manually
ls ~/gh-worker/issues/owner/repo/*/plan-*.md

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

Bug Triage Workflow

Process issues with specific labels:

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

# Generate plans
ghw plan --repo owner/repo

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

High-Parallelism Processing

Process many issues quickly:

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

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

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

Best Practices

Start Small

When starting with a new repository:

  1. Sync a few issues: ghw sync --repo owner/repo --issue-numbers 1 2 3
  2. Generate one plan: ghw plan --repo owner/repo --issue-numbers 1
  3. Review the plan manually
  4. Implement if satisfied: ghw 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

Plans are stored as markdown files. Review them before implementing:

# 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 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 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 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