cc-taskrunner

GitHub: Stackbilt-dev/cc-taskrunner · Apache-2.0

Part of the Stackbilt ecosystem. Autonomous task queue for Claude Code with safety hooks, branch isolation, and automatic PR creation. Integrates with Charter CLI’s charter blast for blast-radius gating before any change touches code.

Queue tasks. Go to sleep. Wake up to PRs.

$ ./taskrunner.sh add "Write unit tests for the auth middleware"
Added task a1b2c3d4: Write unit tests for the auth middleware

$ ./taskrunner.sh --max 5
[09:15:00] cc-taskrunner starting
[09:15:01] ┌─ Task: Write unit tests for the auth middleware
[09:15:01] │  Branch: auto/a1b2c3d4
[09:15:01] │  Starting Claude Code session...
[09:17:42] │  Pushing 3 commit(s) to auto/a1b2c3d4...
[09:17:44] │  PR created: https://github.com/you/repo/pull/42
[09:17:44] └─ COMPLETED

Why It Exists

Claude Code is powerful in interactive sessions but has no built-in way to:

Queue tasks and run them unattended (overnight, during meetings, in CI)
Isolate changes on branches so autonomous work never touches main
Block dangerous operations when nobody’s watching
Create PRs automatically so you review diffs, not raw commits

cc-taskrunner fills that gap — the execution layer between “Claude can write code” and “Claude can ship code safely.”

Setup

Requirements: bash, python3, gh CLI, claude CLI, git.

git clone https://github.com/Stackbilt-dev/cc-taskrunner.git
cd cc-taskrunner

# Add a task
./taskrunner.sh add "Your task description"

# Run up to 5 tasks
./taskrunner.sh --max 5

# Run in continuous loop mode
./taskrunner.sh --loop

Tasks are stored in a queue.json file. Each task runs on its own auto/{task-id} branch and creates a PR when complete.

Safety Hooks

Pre-flight bash hooks run before Claude Code starts each task. Hooks can inspect the task description and abort before any code is written. Built-in integrations:

charter blast — Charter CLI’s blast-radius gate. Estimates scope of change before dispatch. Blocks tasks that exceed configured risk thresholds.
Operation blocklist — hooks block destructive shell operations (rm -rf, force-push, --no-verify) at the OS level rather than relying on prompt discipline alone.

cc-taskrunner vs. Claude Code Routines

In April 2026 Anthropic shipped Claude Code Routines — saved configurations that run on Anthropic’s cloud infrastructure on a schedule, API trigger, or GitHub event. Both tools have a place:

	cc-taskrunner	Claude Code Routines
Where it runs	Your machine	Anthropic-managed cloud
Trigger	Manual / 1-min polling loop	Schedule (1h min), API, or GitHub event
Local filesystem	Full access	Cloned-repo only
Runs while laptop is closed	No	Yes
Queue management	JSON file, dependencies, FIFO	One prompt per routine
Branch isolation	`auto/{task-id}` per task	`claude/*`-prefixed branches
Pre-flight safety hooks	Bash hooks, blast-radius gate	Permission-mode-less by design
Setup	bash + python3 + `gh` + clone	claude.ai account

Use cc-taskrunner when: you need queue management, sub-hour polling, local filesystem access, or hook-level safety enforcement.

Use Routines when: the work fits a single repeating schedule/event trigger and needs to run while your machine is off.

Honest Disclosure

Stackbilt currently runs taskrunner in paused mode and uses Routines for several scheduled workloads (autonomous heartbeat triage, weekly cross-repo pattern scans) — because those workloads fit the routine substrate better. Both tools are complementary. If you’re starting fresh and your work fits the schedule/event model, try Routines first. If you need queue management, sub-hour polling, or local filesystem access, taskrunner is the right tool.