chq

Orchestrate multi-repo tasks with Claude Code in parallel.

chq breaks down a large cross-repository objective into isolated tasks, creates git worktrees for each, and dispatches parallel Claude Code sessions via WezTerm panes — automatically respecting dependency order.

How It Works

chq init my-project          # Create a project
chq plan "Migrate to EKS"    # Plan tasks with Claude Code
chq setup                    # Create worktrees & CLAUDE.md
chq dispatch                 # Launch Claude Code per task
chq watch                    # Auto-dispatch as deps complete
chq status                   # Check progress
chq review                   # Review cross-repo consistency
chq clean                    # Remove worktrees

Workflow

 plan ──► setup ──► dispatch ──► watch ──► review ──► clean
                        │           │
                        ▼           ▼
                   Claude Code   Auto-dispatch
                   (per task)    (on completion)

1. Plan — Claude Code decomposes a goal into repo-scoped, PR-sized tasks with dependency edges
2. Setup — Creates a git worktree per task (topologically sorted), stacking branches for same-repo dependencies
3. Dispatch — Opens a WezTerm pane per ready task, each running Claude Code with a solve prompt
4. Watch — Polls for PR creation, marks tasks done, and dispatches newly unblocked tasks
5. Review — Claude Code reviews all worktrees for cross-repo consistency

Prerequisites

| Tool | Purpose | |------|---------| | Bun | Runtime & build | | git | Worktree operations | | ghq | Local repo path resolution | | gh | PR status checks | | WezTerm | Pane splitting for parallel sessions | | Claude Code | AI coding agent |

Installation

git clone https://github.com/shoppingjaws/chq.git
cd chq
bun install
bun run build
bun link

Quick Start

# 1. Initialize global config (optional)
chq config init

# 2. Create a project
chq init my-migration

# 3. Plan tasks interactively with Claude Code
cd ~/chq/my-migration
chq plan "Migrate authentication from session-based to JWT"

# 4. Create worktrees
chq setup

# 5. Launch all ready tasks
chq dispatch

# 6. Or auto-dispatch on completion
chq watch

Commands

chq init <project-name>

Creates ~/chq/<project-name>/ with an empty chq.json.

chq plan <goal>

Launches an interactive Claude Code session that decomposes the goal into tasks and writes them to chq.json.

chq setup

For each task in chq.json:

• Resolves the local repo path via ghq
• Creates a git worktree at ~/chq/<project>/sub-<task-id>
• Stacks branches for same-repo dependencies (e.g., main <- chq/proj/t1 <- chq/proj/t3)
• Generates a CLAUDE.md with the task overview

chq status

Displays a table with status icons:

Project: my-migration

 ID   Title                  Repo              Blocked By  Status       PR
 t1   Add JWT middleware     org/api-server    -           done         Merged
 t2   Update auth client     org/web-app       -           running      Open
 t3   Migration script       org/api-server    t1          ready        -
 t4   Update docs            org/docs          t1,t2       pending      -

| Icon | Meaning | |------|---------| | pending | Blocked by unfinished dependencies | | ready | All dependencies done, waiting to dispatch | | running | Claude Code session active | | done | PR created | | failed | Dispatch failed |

chq dispatch

Finds tasks that are pending with all blockedBy tasks done, updates them to running, and opens a WezTerm pane for each with Claude Code.

chq watch

Polling loop that:

1. Checks running tasks for PR creation (marks them done)
2. Dispatches newly unblocked tasks
3. Prints status
4. Exits when all tasks are done

Poll interval: CHQ_POLL_INTERVAL env var or pollInterval in global config (default: 30s).

chq review

Launches Claude Code to review all worktrees for cross-repo consistency, API compatibility, and merge-order safety.

chq clean [--force] [--all]

Removes worktrees. --force skips confirmation, --all deletes the project directory entirely.

chq list

Lists all projects under ~/chq/ with done/total counts.

chq config

Manage global configuration at ~/.config/chq/.

chq config init          # Scaffold config.json + prompt templates
chq config init --force  # Overwrite existing files
chq config show          # Display current settings
chq config path          # Print config directory path

Configuration

Global Config (~/.config/chq/config.json)

{
  "chqHome": "~/chq",
  "pollInterval": 30
}

| Key | Default | Description | |-----|---------|-------------| | chqHome | ~/chq | Root directory for projects | | pollInterval | 30 | Watch polling interval in seconds |

Custom Prompts (~/.config/chq/prompts/)

Override the built-in prompts by placing Markdown files with {{variable}} placeholders:

| File | Used by | Available variables | |------|---------|-------------------| | solve.md | chq dispatch | {{projectName}}, {{projectDescription}}, {{taskId}}, {{taskTitle}}, {{taskDescription}}, {{taskRepo}}, {{blockedBy}}, {{baseBranch}}, {{branchName}}, {{draftFlag}} | | plan.md | chq plan | {{projectName}}, {{goal}} | | review.md | chq review | (none) |

Run chq config init to scaffold the default templates, then edit them.

Project Config (~/chq/<project>/chq.json)

{
  "name": "my-migration",
  "description": "Migrate auth from session to JWT",
  "createdAt": "2025-01-15T10:00:00.000Z",
  "tasks": [
    {
      "id": "t1",
      "title": "Add JWT middleware",
      "description": "Implement JWT validation middleware in the API server...",
      "repo": "org/api-server",
      "blockedBy": [],
      "status": "pending"
    }
  ]
}

Branch Strategy

chq uses stacked branches for same-repo dependency chains:

main
 └── chq/my-project/t1    (PR base: main)
      └── chq/my-project/t3  (PR base: t1's branch)

When t1's PR is merged, GitHub automatically rebases t3's PR onto main.

Cross-repo dependencies create Draft PRs to signal they depend on external changes.

FAQ

Do I need WezTerm?

Yes. chq dispatch and chq watch use wezterm cli split-pane to open parallel Claude Code sessions. Support for other terminal multiplexers (tmux, Zellij) is not yet implemented.

Can I use this without ghq?

Not currently. chq setup resolves local repository paths using ghq list --full-path. If the repo is not found, it suggests running ghq get <repo>.

What happens if Claude Code fails mid-task?

The task stays in running status. You can:

1. Manually fix the issue in the worktree (~/chq/<project>/sub-<task-id>/)
2. Create the PR yourself, and chq watch will detect it and mark the task done
3. Edit chq.json directly to reset the task to pending and re-dispatch

Can I edit chq.json manually?

Yes. chq.json is the single source of truth. You can add/remove/reorder tasks, change dependencies, or reset statuses manually. Just ensure the JSON is valid.

How does task completion detection work?

Two mechanisms:

1. Primary: The Claude Code solve prompt instructs Claude to update chq.json status to "done" after creating a PR
2. Fallback: chq watch checks for PR existence via gh pr list --head <branch>

Can I run chq dispatch multiple times?

Yes. It only dispatches tasks that are pending with all dependencies done. Already running or done tasks are skipped.

How do I customize what Claude Code does for each task?

Run chq config init to export the default prompt templates to ~/.config/chq/prompts/. Edit solve.md to change the implementation instructions, PR format, or completion behavior.

What if I have a circular dependency?

chq setup runs a topological sort and will error with a clear message:

Error: Circular dependency detected: t1 -> t3 -> t5 -> t1

Can two tasks modify the same repository?

Yes. Each task gets its own git worktree with a unique branch (chq/<project>/<task-id>). If one task depends on another in the same repo, the branch is stacked on top of the dependency's branch.

How do I resume after closing my terminal?

Run chq status to see where things stand, then chq dispatch to launch any pending-and-ready tasks, or chq watch to resume the full automation loop.

License

MIT