claude-queue: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

A task queue system for batching Claude Code tasks with automatic retry and rate-limit handling. Users queue tasks with priorities and dependencies, then run them unattended while the worker monitors Claude Plan usage limits (5-hour session and 7-day weekly quotas).

Execution Model

This is a clone-and-run script, not an installable package. It is invoked either by the user or by Claude Code directly via Bash — never installed as a system command.

Two usage paths:

1. Via the queue-task skill — the skill has allowed-tools: Write, Read only. It cannot run Bash. Its job is to write tasks.yaml and provide a one-liner the user (or Claude Code main agent) can execute:

queue-task skill → writes tasks.yaml → Claude Code / user runs ./claude-queue.py

2. Directly — Claude Code (main agent with Bash access) or the user runs ./claude-queue.py commands directly from the repo root.

pip install -e ".[dev]" is only used to get pytest/ruff onto PATH for development. There is no package to install.

Commands

# Install all dependencies (creates .venv, installs from uv.lock)
uv sync --extra dev

# Run all tests
uv run pytest tests/ -v

# Run a single test file
uv run pytest tests/test_queue.py -v

# Run a single test
uv run pytest tests/test_queue.py::TestTaskQueue::test_add_task -v

# Run with coverage
uv run pytest tests/ --cov --cov-report=html

# Type check
uv run mypy claude-queue.py

# Lint
uv run ruff check .

# Format
uv run ruff format .

# Update lockfile after changing dependencies
uv lock

# Install pre-commit hooks (one-time setup)
uv run pre-commit install

# Run pre-commit manually on all files
uv run pre-commit run --all-files

Architecture

Everything lives in a single monolithic file: claude-queue.py (1384 lines). This is intentional — the tool is cloned and run directly, so a single file is simpler to use and share.