claude-queue

Automated GitHub issue solver & creator. Create well-structured issues from a text dump or interactive interview, then let Claude Code solve them overnight.

claude-queue has two modes:

• Solve (default) — fetches open issues, uses Claude Code to solve each one, and opens a pull request
• Create — decomposes a description into well-structured GitHub issues, either from inline text or via an interactive interview

Prerequisites

• GitHub CLI (gh) — authenticated
• Claude Code (claude) — installed and configured
• git and jq

Install

npm install -g claude-queue

Or run directly with npx:

npx claude-queue

Usage

Solving issues

Run from inside any git repository with GitHub issues:

claude-queue

Solve options

| Flag | Default | Description | |------|---------|-------------| | --max-retries N | 3 | Max retry attempts per issue before marking it failed | | --max-turns N | 50 | Max Claude Code turns per attempt (prevents runaway sessions) | | --label LABEL | all issues | Only process issues that have this label | | --model MODEL | CLI default | Claude model to use (e.g. claude-sonnet-4-5-20250929) | | -h, --help | | Show help |

Solve examples

# Solve all open issues
claude-queue

# Only solve issues labeled "bug"
claude-queue --label bug

# Use a specific model with more retries
claude-queue --max-retries 5 --model claude-sonnet-4-5-20250929

Creating issues

Generate well-structured GitHub issues from a text description or an interactive interview with Claude.

claude-queue create "Add dark mode and fix the login bug"

There are three ways to provide input:

1. Inline text — pass your description as an argument
2. Stdin — run claude-queue create with no arguments, type or paste your text, then press Ctrl+D
3. Interactive — run claude-queue create -i and Claude will ask clarifying questions before generating issues

In all modes, Claude decomposes the input into individual, actionable issues with titles, markdown bodies, and labels (reusing existing repo labels where possible). You get a preview before anything is created.

Create options

| Flag | Default | Description | |------|---------|-------------| | -i, --interactive | off | Interview mode — Claude asks clarifying questions first | | --label LABEL | none | Add this label to every created issue | | --model MODEL | CLI default | Claude model to use | | -h, --help | | Show help for create |

Create examples

# Create issues from a text description
claude-queue create "Add user avatars, implement search, and fix the 404 on /settings"

# Interactive mode — Claude asks questions first
claude-queue create -i

# Paste a longer description via stdin
claude-queue create

# Add a label to all created issues (useful with --label on solve)
claude-queue create --label backlog "Refactor the auth module and add rate limiting"

Workflow: create then solve

The --label flag on both commands lets you create a workflow where create plans the issues and bare claude-queue solves them:

# Plan: create issues tagged "nightshift"
claude-queue create --label nightshift "Add dark mode and fix the login bug"

# Solve: only process those issues
claude-queue --label nightshift

Configuration

Create a .claude-queue file in your repo root to add custom instructions to every issue prompt:

Always run `npm test` after making changes.
Use TypeScript strict mode.
Never modify files in the src/legacy/ directory.

These instructions are appended to the prompt Claude receives for each issue. This is useful for project-specific conventions that aren't captured in CLAUDE.md.

How It Works

1. Preflight

Verifies all dependencies are available (gh, claude, git, jq), checks that gh is authenticated, and ensures the git working tree is clean. Aborts immediately if anything is missing.

2. Label Setup

Creates three labels on the repo (skips if they already exist):

| Label | Color | Meaning | |-------|-------|---------| | claude-queue:in-progress | Yellow | Currently being worked on | | claude-queue:solved | Green | Successfully fixed | | claude-queue:failed | Red | Could not be solved after all retries |

These labels let you see at a glance which issues were handled and what the outcome was.

3. Branch

Creates a single branch claude-queue/YYYY-MM-DD off your default branch. All fixes for the night go into this one branch. If the branch already exists (e.g. from a previous run), a timestamp suffix is added.

4. Issue Processing

For each open issue (up to 200, oldest first):

• Skip check — issues that already have any claude-queue:* label are skipped. Remove the label to re-process.
• Label — marks the issue claude-queue:in-progress
• Solve — launches a fresh Claude Code process (claude -p) with a prompt that tells it to:
  • Read the issue via gh issue view
  • Explore the codebase
  • Implement a fix
  • Run existing tests
• Evaluate — if Claude produced file changes, they are committed. If not, the attempt is retried.
• Retry — on failure, the working tree is reset to the last checkpoint (git reset --hard) and Claude gets a completely fresh context. Up to 3 attempts per issue (configurable with --max-retries).
• Label result — marks the issue claude-queue:solved or claude-queue:failed

Each issue is solved sequentially so later fixes build on top of earlier ones — all in a single branch.

5. Pull Request

Once all issues are processed, the branch is pushed and a PR is opened with:

• Summary table — solved/failed/skipped counts and run duration
• Solved issues — table of all issues that were fixed with links
• Failed issues — table of issues that couldn't be solved
• Chain logs — collapsible per-issue logs showing Claude's full output for each attempt

If no issues were solved, no PR is created.

Interruption Handling

If the script is interrupted (Ctrl+C, SIGTERM), it:

• Removes the claude-queue:in-progress label from the current issue
• Marks it as claude-queue:failed
• Prints where your commits and logs are so nothing is lost

Logs

Full logs for each run are saved to /tmp/claude-queue-DATE-TIMESTAMP/:

/tmp/claude-queue-2025-03-15-220530/
├── issue-42.md             # Combined log for issue #42
├── issue-42-attempt-1.log  # Raw Claude output, attempt 1
├── issue-42-attempt-2.log  # Raw Claude output, attempt 2
├── issue-57.md
├── issue-57-attempt-1.log
└── pr-body.md              # The generated PR description

License

MIT