gh-worker

Automated GitHub issue handling with LLM agents. This CLI tool syncs issues from GitHub, generates implementation plans using LLMs, and executes those plans to create pull requests automatically.

Features

Automated Issue Sync: Sync GitHub issues to local files for processing
LLM-Powered Planning: Generate comprehensive implementation plans using AI agents
Automated Implementation: Execute plans and create pull requests automatically
Code Review: Review implementations using LLM agents to ensure quality
Git Worktree Support: Isolated implementation branches using git worktree for parallel development
PR Automation: Automated branch pushing and pull request creation
Parallel Execution: Process multiple issues concurrently with configurable parallelism
Continuous Workflow: Run sync → plan → implement → review cycles continuously or on-demand
Pluggable Agents: Support for multiple LLM agents (Claude Code, Cursor Agent, Mock, OpenCode, Gemini, Codex)
Interactive Setup: Quick configuration with the init command
Agent Override: Switch between agents at runtime for different tasks
Robust Error Handling: Automatic retry logic with exponential backoff for transient failures

Installation

Prerequisites

Python 3.12 or later (latest LTS)
uv package manager
GitHub CLI (gh) authenticated with your GitHub account
Claude Code CLI (for using the default Claude Code agent)

Install gh-worker

# Install with uv
uv tool install https://github.com/tomzxcode/gh-worker.git

After installation, the tool is available as both gh-worker and ghw (shorter alias).

Verify Installation

# Check that gh CLI is authenticated
gh auth status

# Verify gh-worker is installed
ghw --help

Quick Start

Commands

ghw init                         Initialize configuration
ghw repositories add             Add repositories to track
ghw repositories list            List tracked repositories
ghw repositories remove          Remove repositories from tracking
ghw issues sync                  Sync issues from GitHub
ghw issues list                  List synced issues with plan/implementation/review status
ghw issues plan                  Generate implementation plans
ghw plans review                  Review and approve plans
ghw issues review                Review code implementations using LLM agents
ghw issues implement             Implement plans and create PRs
ghw monitor                      Monitor ongoing plan or implementation progress
ghw work                         Run sync → plan → implement workflow
ghw config                       Manage configuration

Global Options

All commands support the following global options:

# Set log level (DEBUG, INFO, WARNING, ERROR)
ghw --log-level DEBUG <command>

# Use custom config file
ghw <command> --config-path /path/to/config.yaml

1. Initialize Configuration

Use the interactive setup:

ghw init

This will guide you through setting up:

Issues storage path
Repository clone path
Parallelism settings
Git worktree options
PR automation preferences
Default agent selection

Or configure manually:

# Set the path where issues will be stored
ghw config issues-path ~/gh-worker/issues

# Set the path where repositories will be cloned
ghw config repository-path ~/gh-worker/repos

# (Optional) Configure parallelism for plan generation
ghw config plan.parallelism 3

# (Optional) Configure parallelism for implementation
ghw config implement.parallelism 2

# (Optional) Enable git worktree for isolated implementations
ghw config implement.use_worktree true

# (Optional) Auto-push branches after implementation
ghw config implement.push_branch true

# (Optional) Auto-create PRs after implementation
ghw config implement.create_pr true

2. Add a Repository

Add a repository to track:

ghw repositories add owner/repo

This creates the necessary directory structure. Use --clone to clone immediately, or the repository will be cloned on-demand when you run ghw issues plan or ghw issues implement.

3. List and Manage Repositories

# List all repositories under management
ghw repositories list

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

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

4. Sync Issues

Sync issues from GitHub:

# Sync all open issues for a repository
ghw issues sync --repo owner/repo

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

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

# Sync all repositories
ghw issues sync --all-repos

5. List Issues

List synced issues with plan and implementation status:

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

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

# Filter by title, author, assignee, plan status, or implementation status
ghw issues list --repo owner/repo --plan approved --implementation none

6. Review and Approve Plans (Optional)

Review plans before implementation and approve them:

# Create worktree with plan symlinked for review
ghw issues review plan --repo owner/repo 42

# Approve a plan
ghw issues review plan --repo owner/repo 42 --approve

7. Generate Plans

Generate implementation plans for synced issues using LLM agents:

# Generate plans for all issues without plans
ghw issues plan --repo owner/repo

# Generate plan for specific issue
ghw issues plan --repo owner/repo --issue-numbers 42

# Use custom parallelism
ghw issues plan --repo owner/repo --parallelism 5

# Regenerate plan even if one exists
ghw issues plan --repo owner/repo --issue-numbers 42 --force

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

8. Review Plans (Optional)

Review and approve plans before implementation:

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

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

9. Implement Plans

Execute plans and create pull requests with git worktree support:

# Implement all planned issues
ghw issues implement --repo owner/repo

# Implement specific issue
ghw issues implement --repo owner/repo --issue-numbers 42

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

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

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

# Implement and keep worktree for debugging
ghw issues implement --repo owner/repo --delete-worktree=false

# Force re-implementation even if already completed
ghw issues implement --repo owner/repo --issue-numbers 42 --force

10. Review Implementations

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

Note: The review outcome is written to review.md in the issue's directory.

11. Monitor Progress

Monitor an ongoing plan or implementation:

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

12. Run Full Workflow

Run the complete sync → plan → implement workflow:

# Run once and exit
ghw work --once --repos owner/repo

# Run continuously (with default frequency)
ghw work --repos owner/repo

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

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

Configuration

Configuration is stored in ~/.config/gh-worker/config.yaml (XDG compliant).

Configuration Options

issues-path: ~/gh-worker/issues  # Where issues are stored
repository-path: ~/gh-worker/repos  # Where repos are cloned

plan:
  parallelism: 3  # Number of parallel plan generations

implement:
  parallelism: 2  # Number of parallel implementations
  use_worktree: true  # Use git worktree for isolated implementations
  push_branch: false  # Auto-push branches after implementation
  create_pr: false  # Auto-create PRs after implementation
  delete_worktree: true  # Delete worktree after completion

agent:
  default: claude-code  # Default LLM agent (claude-code, cursor-agent, mock)
  claude_code_path: null  # Optional custom path to claude-code CLI

sync:
  frequency: 1h  # How often to sync in continuous mode

Managing Configuration

# Initialize interactively
ghw init

# List all configuration values
ghw config --list

# Get a value (omit the second argument)
ghw config issues-path

# Set a value (provide both key and value)
ghw config issues-path /custom/path

# Set nested values using dot notation
ghw config plan.parallelism 5

# Configure worktree and PR automation
ghw config implement.use_worktree true
ghw config implement.push_branch true
ghw config implement.create_pr true

# Change default agent
ghw config agent.default cursor-agent

File Structure

gh-worker uses a file-based storage system:

~/.config/gh-worker/
└── config.yaml                      # Configuration

~/gh-worker/
├── issues/
│   └── owner/
│       └── repo/
│           ├── .updated-at          # Last sync timestamp
│           └── 42/                  # Issue number
│               ├── description.md   # Issue content
│               ├── .updated-at      # Issue update timestamp
│               ├── plan-<timestamp>.md  # Implementation plan
│               ├── .plan-<timestamp>.yaml  # Plan metadata
│               └── review.md        # Review outcome (after review)
└── repos/
    └── owner/
        └── repo/                    # Cloned repository

Agents

gh-worker supports multiple LLM agents through a pluggable architecture:

Available Agents

claude-code (default): Uses the Claude Code CLI tool for comprehensive implementations
cursor-agent: Uses the Cursor Agent CLI for fast code generation
mock: Test agent for development and CI/CD (no external dependencies)
opencode: OpenCode agent (uses opencode run CLI)
gemini: Google Gemini agent (placeholder, not yet implemented)
codex: OpenAI Codex agent (placeholder, not yet implemented)

Configuring Agents

# Set the default agent
ghw config agent.default claude-code

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

# Configure agent-specific settings
ghw config agent.claude_code_path /custom/path/to/claude-code
ghw config agent.opencode_path /custom/path/to/opencode

Agent Requirements

claude-code: Claude Code CLI installed and authenticated
cursor-agent: Cursor Agent CLI (npm install -g @cursor/agent)
mock: No external dependencies (built-in)

Development

Running Tests

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=gh_worker --cov-report=html

# Run specific test file
uv run pytest tests/unit/test_agents.py

# Run specific test
uv run pytest tests/unit/test_agents.py::TestAgentRegistry::test_registry_initialization

Linting and Formatting

# Check code
uv run ruff check src/ tests/

# Format code
uv run ruff format src/ tests/

Project Structure

gh-worker/
├── src/gh_worker/
│   ├── cli.py                    # CLI entry point
│   ├── config/                   # Configuration management
│   ├── commands/                 # Command implementations
│   ├── models/                   # Data models
│   ├── storage/                  # File-based storage
│   ├── agents/                   # LLM agent abstraction
│   ├── github/                   # GitHub CLI wrapper
│   ├── executor/                 # Parallel execution
│   └── utils/                    # Utilities
├── tests/                        # Tests
│   ├── unit/                     # Unit tests
│   └── integration/              # Integration tests
├── pyproject.toml                # Project configuration
└── README.md                     # This file

Troubleshooting

GitHub CLI Not Authenticated

gh auth login

Claude Code CLI Not Found

Install the Claude Code CLI from claude.ai/code.

Cursor Agent CLI Not Found

Install the Cursor Agent CLI:

npm install -g @cursor/agent

Verify installation:

cursor-agent --version
# or
agent --version

Permission Denied Errors

Ensure the configured paths are writable:

mkdir -p ~/gh-worker/issues ~/gh-worker/repos
chmod 755 ~/gh-worker

Issues Not Syncing

Check that the repository name is correct and you have access:

gh repo view owner/repo

Plans Not Generated

Verify the agent CLI is working:

# For Claude Code
claude-code --version

# For Cursor Agent
cursor-agent --version

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

Examples

Process New Issues Daily

# In a cron job or systemd timer
ghw work --once --repos owner/repo --since 1d

Continuous Monitoring

# Run continuously, checking every 30 minutes
ghw work --repos owner/repo --frequency 30m

Manual Workflow

# 1. Initialize configuration
ghw init

# 2. Sync recent issues
ghw issues sync --repo owner/repo --since 7d

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

# 4. Review and approve plans
ghw issues review plan --repo owner/repo 42 --approve

# 5. Implement a specific issue with full automation
ghw issues implement --repo owner/repo --issue-numbers 42 --push-branch --create-pr

# 6. (If implement doesn't push/PR) Review implementation
ghw issues review implementation --repo owner/repo 42

# 7. Monitor progress
ghw monitor --repo owner/repo --issue-number 42

Contributing

Contributions are welcome! Please follow these guidelines:

Run tests before submitting: uv run pytest
Format code with ruff: uv run ruff format src/ tests/
Check for linting issues: uv run ruff check src/ tests/
Write tests for new features
Update documentation as needed

License

MIT License - See LICENSE file for details

Support

For issues, questions, or contributions, please visit the GitHub repository.

Name		Name	Last commit message	Last commit date
Latest commit History 52 Commits
.github/workflows		.github/workflows
docs		docs
spec		spec
src/gh_worker		src/gh_worker
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
mkdocs.yml		mkdocs.yml
pyproject.toml		pyproject.toml
uv.lock		uv.lock

License

TomzxCode/gh-worker

Folders and files

Latest commit

History

Repository files navigation

gh-worker

Features

Installation

Prerequisites

Install gh-worker

Verify Installation

Quick Start

Commands

Global Options

1. Initialize Configuration

2. Add a Repository

3. List and Manage Repositories

4. Sync Issues

5. List Issues

6. Review and Approve Plans (Optional)

7. Generate Plans

8. Review Plans (Optional)

9. Implement Plans

10. Review Implementations

11. Monitor Progress

12. Run Full Workflow

Configuration

Configuration Options

Managing Configuration

File Structure

Agents

Available Agents

Configuring Agents

Agent Requirements

Development

Running Tests

Linting and Formatting

Project Structure

Troubleshooting

GitHub CLI Not Authenticated

Claude Code CLI Not Found

Cursor Agent CLI Not Found

Permission Denied Errors

Issues Not Syncing

Plans Not Generated

Examples

Process New Issues Daily

Continuous Monitoring

Manual Workflow

Contributing

License

Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages