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

``bash
npm install -g claude-queue
`

Or run directly with npx:

`bash
npx claude-queue
`

Usage

$3

Run from inside any git repository with GitHub issues:

`bash
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

`bash


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
`

$3

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

`bash
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

`bash


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"
`

$3

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

`bash


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

$3

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.

$3

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

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.

$3

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.

$3

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.

$3

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