claude-queue 1.5.0 → 1.5.2

package/README.md

@@ -1,10 +1,10 @@
 # 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.
+A CLI tool that solves GitHub issues using [Claude Code](https://docs.anthropic.com/en/docs/claude-code). It picks up open issues from your repo, solves them one by one, and opens a pull request with all the fixes. It can also create well-structured GitHub issues from a text description or interactive interview.
 
-claude-queue has two modes:
-- **Solve** (default) — fetches open issues, uses [Claude Code](https://docs.anthropic.com/en/docs/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
+The typical workflow is: open issues for whatever you need done, run `claude-queue`, and come back to a pull request with everything solved. I usually do this at night and review the PR in the morning.
+
+Issues don't have to be code changes — they can be investigative tasks like "figure out why the API is slow and document what you find" or "audit the codebase for accessibility issues". Claude will research, document findings, and commit whatever it produces.
 
 ## Prerequisites
 
@@ -18,7 +18,7 @@ claude-queue has two modes:
 npm install -g claude-queue
 ```
 
-Or run directly with npx:
+Or run directly:
 
 ```bash
 npx claude-queue
@@ -34,32 +34,40 @@ Run from inside any git repository with GitHub issues:
 claude-queue
 ```
 
-#### Solve options
-
 | Flag | Default | Description |
 |------|---------|-------------|
+| `--issue ID` | all issues | Solve specific issue(s) by ID, URL, or comma-separated IDs |
 | `--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 |
+| `--max-turns N` | `50` | Max Claude Code turns per attempt |
+| `--label LABEL` | all issues | Only process issues with this label (can be repeated) |
 | `--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
 
+# Solve a specific issue by number
+claude-queue --issue 42
+
+# Solve a specific issue by URL
+claude-queue --issue https://github.com/owner/repo/issues/42
+
+# Solve multiple specific issues
+claude-queue --issue 1,2,3
+
 # Only solve issues labeled "bug"
 claude-queue --label bug
 
+# Filter by multiple labels
+claude-queue --label bug --label urgent
+
 # 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.
+Generate GitHub issues from a text description or an interactive interview with Claude.
 
 ```bash
 claude-queue create "Add dark mode and fix the login bug"
@@ -71,42 +79,31 @@ There are three ways to provide input:
 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
+Claude decomposes the input into individual issues with titles, markdown bodies, and labels (reusing existing repo labels where possible). You get a preview before anything is created.
 
 | 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
+# Interactive mode
 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)
+# Add a label to all created issues
 claude-queue create --label backlog "Refactor the auth module and add rate limiting"
 ```
 
-### Workflow: create then solve
+### Create then solve workflow
 
-The `--label` flag on both commands lets you create a workflow where `create` plans the issues and bare `claude-queue` solves them:
+The `--label` flag on both commands lets you create a pipeline where `create` plans the issues and `claude-queue` solves them:
 
 ```bash
-# Plan: create issues tagged "nightshift"
+# Plan
 claude-queue create --label nightshift "Add dark mode and fix the login bug"
 
-# Solve: only process those issues
+# Solve
 claude-queue --label nightshift
 ```
 
@@ -120,64 +117,58 @@ 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`.
+These instructions are appended to the prompt Claude receives for each issue. Useful for project-specific conventions that aren't in `CLAUDE.md`.
 
 ## How It Works
 
-### 1. Preflight
+### 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.
+Verifies all dependencies (`gh`, `claude`, `git`, `jq`), checks that `gh` is authenticated, and ensures the working tree is clean.
 
-### 2. Label Setup
+### 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 |
+| Label | Meaning |
+|-------|---------|
+| `claude-queue:in-progress` | Currently being worked on |
+| `claude-queue:solved` | Successfully fixed |
+| `claude-queue:failed` | Could not be solved after all retries |
+
+### Branching
 
-These labels let you see at a glance which issues were handled and what the outcome was.
+Creates a branch `claude-queue/YYYY-MM-DD` off your default branch. All fixes go into this one branch. If the branch already exists, a timestamp suffix is added.
 
-### 3. Branch
+### Issue processing
 
-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.
+For each open issue (up to 200, oldest first), or for the specific issues passed via `--issue`:
 
-### 4. Issue Processing
+1. **Skip** — issues with any `claude-queue:*` label are skipped (unless targeted via `--issue`). Remove the label to re-process.
+2. **Label** — marks the issue `claude-queue:in-progress`.
+3. **Solve** — launches Claude Code with a prompt to read the issue, explore the codebase, implement a fix, and run tests.
+4. **Evaluate** — if Claude produced file changes, they are committed. If not, the attempt is retried.
+5. **Retry** — on failure, the working tree is reset and Claude gets a fresh context. Up to 3 attempts (configurable with `--max-retries`).
+6. **Result** — marks the issue `claude-queue:solved` or `claude-queue:failed`.
 
-For each open issue (up to 200, oldest first):
+Issues are solved sequentially so later fixes build on earlier ones within a single branch.
 
-- **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`
+### Review pass
 
-Each issue is solved sequentially so later fixes build on top of earlier ones — all in a single branch.
+After all issues are processed, Claude does a second pass reviewing all committed changes for bugs, incomplete implementations, and style issues — fixing anything it finds.
 
-### 5. Pull Request
+### Pull request
 
-Once all issues are processed, the branch is pushed and a PR is opened with:
+Once done, 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
+- Summary table with solved/failed/skipped counts and run duration
+- Tables of solved and failed issues with links
+- Collapsible per-issue logs showing Claude's full output
 
-If no issues were solved, no PR is created.
+No PR is created if nothing was solved.
 
-### Interruption Handling
+### 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
+If interrupted (Ctrl+C, SIGTERM), the script removes the `claude-queue:in-progress` label from the current issue, marks it as failed, and prints where your commits and logs are.
 
 ## Logs
 
@@ -190,7 +181,7 @@ Full logs for each run are saved to `/tmp/claude-queue-DATE-TIMESTAMP/`:
 ├── 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
+└── pr-body.md              # Generated PR description
 ```
 
 ## License

package/claude-queue.sh

@@ -7,9 +7,10 @@
 #   claude-queue create [options]  Create issues from text or interactively
 #
 # Solve options:
+#   --issue ID         Solve specific issue(s) by ID, URL, or comma-separated IDs
 #   --max-retries N    Max retries per issue (default: 3)
 #   --max-turns N      Max Claude turns per attempt (default: 50)
-#   --label LABEL      Only process issues with this label
+#   --label LABEL      Only process issues with this label (can be repeated)
 #   --model MODEL      Claude model to use
 #   -v, --version      Show version
 #   -h, --help         Show this help message
@@ -26,7 +27,8 @@ VERSION=$(node -p "require('$(dirname "$0")/package.json').version" 2>/dev/null
 
 MAX_RETRIES=3
 MAX_TURNS=50
-ISSUE_FILTER=""
+declare -a ISSUE_FILTERS=()
+ISSUE_IDS=""
 MODEL_FLAG=""
 DATE=$(date +%Y-%m-%d)
 TIMESTAMP=$(date +%H%M%S)
@@ -49,6 +51,7 @@ declare -a SOLVED_ISSUES=()
 declare -a FAILED_ISSUES=()
 declare -a SKIPPED_ISSUES=()
 CURRENT_ISSUE=""
+CHILD_PID=""
 START_TIME=$(date +%s)
 
 show_help() {
@@ -59,9 +62,10 @@ show_help() {
     echo "  claude-queue create [options] [text] Create issues from text or interactively"
     echo ""
     echo "Solve options:"
+    echo "  --issue ID         Solve specific issue(s) by ID, URL, or comma-separated IDs"
     echo "  --max-retries N    Max retries per issue (default: 3)"
     echo "  --max-turns N      Max Claude turns per attempt (default: 50)"
-    echo "  --label LABEL      Only process issues with this label"
+    echo "  --label LABEL      Only process issues with this label (can be repeated)"
     echo "  --model MODEL      Claude model to use"
     echo "  -v, --version      Show version"
     echo "  -h, --help         Show this help message"
@@ -108,6 +112,17 @@ cleanup() {
         log "Logs saved to: ${LOG_DIR}"
     fi
 }
+
+handle_interrupt() {
+    if [ -n "$CHILD_PID" ] && kill -0 "$CHILD_PID" 2>/dev/null; then
+        kill -TERM "$CHILD_PID" 2>/dev/null || true
+        wait "$CHILD_PID" 2>/dev/null || true
+    fi
+    CHILD_PID=""
+    exit 130
+}
+
+trap handle_interrupt INT TERM
 trap cleanup EXIT
 
 preflight() {
@@ -181,15 +196,61 @@ setup_branch() {
 }
 
 fetch_issues() {
-    local args=(--state open --json "number,title,body,labels" --limit 200)
+    local args=(--state open --json "number,title,body,labels" --limit 200 --sort created --direction asc)
 
-    if [ -n "$ISSUE_FILTER" ]; then
-        args+=(--label "$ISSUE_FILTER")
-    fi
+    for filter in "${ISSUE_FILTERS[@]}"; do
+        args+=(--label "$filter")
+    done
 
     gh issue list "${args[@]}"
 }
 
+parse_issue_number() {
+    local input="$1"
+
+    local num
+    num=$(echo "$input" | grep -oE '[0-9]+$' || echo "")
+
+    if [ -z "$num" ]; then
+        log_error "Invalid issue identifier: $input"
+        return 1
+    fi
+
+    echo "$num"
+}
+
+fetch_specific_issues() {
+    local ids_str="$1"
+    local result="["
+    local first=true
+
+    IFS=',' read -ra id_array <<< "$ids_str"
+    for id in "${id_array[@]}"; do
+        id=$(echo "$id" | xargs)
+
+        local num
+        if ! num=$(parse_issue_number "$id"); then
+            continue
+        fi
+
+        local issue_json
+        issue_json=$(gh issue view "$num" --json "number,title,body,labels" 2>/dev/null) || {
+            log_error "Could not fetch issue #${num}"
+            continue
+        }
+
+        if [ "$first" = true ]; then
+            first=false
+        else
+            result+=","
+        fi
+        result+="$issue_json"
+    done
+
+    result+="]"
+    echo "$result"
+}
+
 process_issue() {
     local issue_number=$1
     local issue_title="$2"
@@ -267,7 +328,10 @@ description of what you changed and why."
             --dangerously-skip-permissions \
             --max-turns "$MAX_TURNS" \
             $MODEL_FLAG \
-            > "$attempt_log" 2>&1 || claude_exit=$?
+            > "$attempt_log" 2>&1 &
+        CHILD_PID=$!
+        wait "$CHILD_PID" || claude_exit=$?
+        CHILD_PID=""
 
         if [ "$claude_exit" -ne 0 ]; then
             log_warn "Claude exited with code ${claude_exit}"
@@ -377,7 +441,10 @@ When you are done, output a line that says CLAUDE_QUEUE_REVIEW followed by a bri
         --dangerously-skip-permissions \
         --max-turns "$MAX_TURNS" \
         $MODEL_FLAG \
-        > "$review_log" 2>&1 || true
+        > "$review_log" 2>&1 &
+    CHILD_PID=$!
+    wait "$CHILD_PID" 2>/dev/null || true
+    CHILD_PID=""
 
     local changed_files
     changed_files=$(git diff --name-only 2>/dev/null; git ls-files --others --exclude-standard 2>/dev/null)
@@ -516,7 +583,12 @@ main() {
     log_header "Fetching Issues"
 
     local issues
-    issues=$(fetch_issues)
+    if [ -n "$ISSUE_IDS" ]; then
+        log "Fetching specific issue(s): ${ISSUE_IDS}"
+        issues=$(fetch_specific_issues "$ISSUE_IDS")
+    else
+        issues=$(fetch_issues)
+    fi
     local total
     total=$(echo "$issues" | jq length)
 
@@ -533,7 +605,7 @@ main() {
         title=$(echo "$issues" | jq -r ".[$i].title")
         labels=$(echo "$issues" | jq -r "[.[$i].labels[].name] | join(\",\")" 2>/dev/null || echo "")
 
-        if echo "$labels" | grep -q "claude-queue:"; then
+        if [ -z "$ISSUE_IDS" ] && echo "$labels" | grep -q "claude-queue:"; then
             log "Skipping #${number} (already has a claude-queue label)"
             SKIPPED_ISSUES+=("${number}|${title}")
             continue
@@ -931,9 +1003,10 @@ case "$SUBCOMMAND" in
     "")
         while [[ $# -gt 0 ]]; do
             case $1 in
+                --issue)       ISSUE_IDS="$2"; shift 2 ;;
                 --max-retries) MAX_RETRIES="$2"; shift 2 ;;
                 --max-turns)   MAX_TURNS="$2";   shift 2 ;;
-                --label)       ISSUE_FILTER="$2"; shift 2 ;;
+                --label)       ISSUE_FILTERS+=("$2"); shift 2 ;;
                 --model)       MODEL_FLAG="--model $2"; shift 2 ;;
                 -v|--version)  echo "claude-queue v${VERSION}"; exit 0 ;;
                 -h|--help)     show_help; exit 0 ;;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-queue",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "description": "Automated GitHub issue solver powered by Claude Code",
   "bin": {
     "claude-queue": "./claude-queue.sh"