Hank

Autonomous AI development loop for Claude Code with intelligent orchestration

Hank (Based on Ralph) wraps Claude Code in a persistent outer loop that runs autonomously until your project is done. It manages rate limits, detects stalls, preserves session context, and coordinates work across planning and building phases — so you can walk away and come back to committed code.

Based on Geoffrey Huntley's technique for continuous Claude Code execution.

What Makes This Fork Different

This fork adds some capabilities on top of the core Hank engine:

Playbook-Style Prompts

Two-mode prompt system (--mode plan and --mode build) with specialized instructions for each phase:

• Plan mode: Research specs, audit existing code, produce an IMPLEMENTATION_PLAN.md
• Build mode: Execute the plan with a structured subagent hierarchy — up to 500 parallel Sonnet subagents for reads/searches, 1 Sonnet subagent for writes, Opus subagents for complex reasoning
• Lean AGENTS.md kept operational-only
• IMPLEMENTATION_PLAN.md as the single source of truth for task state

Agent Teams Support

Run hank --teams to enable Agent Teams for genuinely parallel multi-agent work (experimental, off by default):

• Plan mode: Spawns a specs researcher + code auditor team for parallel analysis
• Build mode: Uses teams when 2+ independent items touch different files/layers (e.g., frontend + backend)
• Falls back to subagents when items touch the same files or work is sequential
• Adds team tools (TeamCreate, SendMessage, TaskCreate, etc.) and exports CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

GitHub Issues as Task Source

Run hank --source github to use GitHub Issues as your task manager instead of a static plan file:

• Issues labeled hank are synced to IMPLEMENTATION_PLAN.md before each loop
• Priority labels (hank:next, hank:p1, hank:p2) control execution order
• Hank comments on issues with progress and closes them on completion
• Labels track state: hank:in-progress, hank:blocked
• Create issues from your phone, Hank picks them up on the next iteration

Cost Tracking

Hank tracks API costs and token usage for every loop iteration:

• Per-loop logging — Each iteration records cost, tokens (input/output/cache), duration, and session ID to .hank/cost_log.jsonl
• Session summaries — Running totals displayed at the end of each session (plan, build, or dry-run)
• Per-issue breakdown — When using --source github, costs are attributed to individual issues
• Historical reports — Run hank --cost-summary to see a full cost report across all sessions

Live Web Dashboard

hank-dash is a companion web dashboard that visualizes Hank runs in real time. It watches the .hank/ directory for changes and streams updates to a browser UI via Server-Sent Events.

• Cost & token charts — Per-loop and cumulative cost, token breakdown, cache hit rates, cost velocity
• Circuit breaker monitor — Live state gauge with transition history
• Stall detection — Warns on no-progress loops, repeated errors, cost spikes
• Implementation plan progress — Tracks task completion from IMPLEMENTATION_PLAN.md
• Process monitor — Shows running tmux sessions, hank loops, Claude CLI instances, and flags orphaned processes
• Multi-project support — Watch multiple Hank projects from a single dashboard
• Zero dependencies — Pure Node.js, no npm packages required

# Install and run
git clone https://github.com/jacklenzotti/hank-dash.git
cd hank-dash
node bin/hank-dash.js ~/my-project   # Opens dashboard at http://localhost:3274

# Watch multiple projects
node bin/hank-dash.js ~/project-a ~/project-b

Quick Start

Install

git clone https://github.com/jacklenzotti/hank.git
cd hank
./install.sh

This adds hank, hank-setup, hank-import, hank-enable, and hank-enable-ci to your PATH.

Enable in an Existing Project

cd my-project
hank-enable              # Interactive wizard — detects project type, imports tasks
hank --monitor           # Start the autonomous loop with tmux dashboard

Or Import a PRD

hank-import requirements.md my-project
cd my-project
hank --monitor

Or Create from Scratch

hank-setup my-project
cd my-project
# Edit .hank/PROMPT.md and .hank/specs/
hank --monitor

GitHub Issues Workflow

cd my-project
hank-enable --from github    # Sets up labels and syncs issues
hank --source github         # Pulls issues each loop, reports back

How It Works

Hank operates a simple cycle:

1. Sync tasks — From IMPLEMENTATION_PLAN.md or GitHub Issues
2. Execute Claude Code — With the current prompt and context
3. Analyze response — Parse the HANK_STATUS block for progress signals
4. Evaluate exit — Dual-condition gate: completion indicators AND explicit EXIT_SIGNAL: true
5. Repeat — Until done, rate-limited, or circuit breaker trips

Exit Detection

Exit requires both conditions:

• completion_indicators >= 2 (heuristic from natural language patterns)
• Claude's explicit EXIT_SIGNAL: true in the HANK_STATUS block

This prevents premature exits during productive iterations where Claude says "phase complete" but has more work to do.

Circuit Breaker

Automatically detects and halts:

• 3 loops with no file changes (stagnation)
• 5 loops with the same error (stuck)
• Output declining by >70% (degradation)
• Recovers gradually with half-open monitoring

Rate Limiting

• Default: 100 calls/hour with automatic countdown
• 5-hour API limit detection with wait/exit prompt
• Configurable via --calls flag or .hankrc

hank --cost-summary   # Show cost report from all sessions

The cost log persists across sessions (only session totals are reset between runs), giving you a complete spend history for the project.

Retry & Error Recovery

Hank automatically classifies errors (rate limits, test failures, build errors, etc.) and applies the appropriate retry strategy with exponential backoff. Rate limit errors wait and retry, test/build failures retry with a context hint, and permission denials halt immediately. Configure via .hankrc (RETRY_MAX_ATTEMPTS, RETRY_BACKOFF_INITIAL_SEC, RETRY_BACKOFF_MAX_SEC, RETRY_BACKOFF_MULTIPLIER).

hank --error-catalog              # Show all classified errors
hank --error-catalog rate_limit   # Filter by category

Audit Log & Session Replay

Every major operation (loop start/complete, errors, retries, circuit breaker changes) is recorded to .hank/audit_log.jsonl. Session replay reconstructs a timeline from these logs for debugging.

hank --audit                      # Show recent events (default: 20)
hank --audit --type error_detected --since 2h
hank --replay --list              # List all recorded sessions
hank --replay <session_id>        # Replay session timeline
hank --replay <id> --json         # JSON output format

Multi-Repo Orchestration

Execute Hank across multiple repositories in dependency order. Requires a .hank/.repos.json config file defining repos, paths, and dependencies. Hank resolves execution order via topological sort and tracks per-repo status and costs.

hank --orchestrate                # Run across repos in dependency order
hank --repos                      # Show orchestration status

Configuration

Project Config (.hankrc)

PROJECT_NAME="my-project"
PROJECT_TYPE="typescript"
MAX_CALLS_PER_HOUR=100
CLAUDE_TIMEOUT_MINUTES=15
CLAUDE_OUTPUT_FORMAT="json"
ALLOWED_TOOLS="Write,Read,Edit,Bash(git *),Bash(npm *),Bash(pytest)"
SESSION_CONTINUITY=true
SESSION_EXPIRY_HOURS=24
RETRY_MAX_ATTEMPTS=3
RETRY_BACKOFF_INITIAL_SEC=30
RETRY_BACKOFF_MAX_SEC=300
RETRY_BACKOFF_MULTIPLIER=2

Project Structure

my-project/
├── .hank/
│   ├── PROMPT.md              # Instructions for Claude Code
│   ├── IMPLEMENTATION_PLAN.md # Task state (or synced from GitHub Issues)
│   ├── AGENTS.md              # Build/test commands (auto-maintained)
│   ├── cost_log.jsonl         # Per-loop cost/token data (persistent)
│   ├── specs/                 # Detailed requirements
│   └── logs/                  # Execution logs
├── .hankrc                    # Project settings
└── src/                       # Your code

Session Management

Sessions persist context across loop iterations:

hank --monitor             # Uses session continuity (default)
hank --no-continue         # Fresh context each loop
hank --stop                # Stop all running Hank sessions
hank --reset-session       # Clear session manually
hank --resume <id>         # Resume a specific session

Sessions auto-reset on circuit breaker trip, manual interrupt, or expiration (default: 24 hours).

Command Reference

# Installation
./install.sh                    # Install globally
./uninstall.sh                  # Remove from system

# Project setup
hank-setup <name>               # New project from scratch
hank-enable                     # Enable in existing project (interactive)
hank-enable-ci                  # Enable in existing project (non-interactive)
hank-import <file> [name]       # Convert PRD/specs to Hank project

# Running
hank [OPTIONS]
  --monitor                     # tmux dashboard (recommended)
  --live                        # Stream Claude Code output in real-time
  --source github               # Pull tasks from GitHub Issues
  --mode plan|build             # Set prompt mode
  --calls NUM                   # Max API calls per hour
  --timeout MIN                 # Execution timeout (1-120 minutes)
  --prompt FILE                 # Custom prompt file
  --verbose                     # Detailed progress output
  --output-format json|text     # Response format
  --teams                       # Enable Agent Teams (experimental)
  --no-continue                 # Disable session continuity
  --stop                        # Stop all running Hank sessions
  --reset-session               # Clear session state
  --reset-circuit               # Reset circuit breaker
  --cost-summary                # Show cost report from all sessions
  --dry-run                     # Read-only analysis (no file changes)
  --orchestrate                 # Multi-repo mode (requires .repos.json)
  --repos                       # Show orchestration status
  --replay --list               # List recorded sessions
  --replay <id>                 # Replay a session timeline
  --audit                       # Query audit log
  --error-catalog               # Show classified errors
  --clean                       # Remove transient session files
  --status                      # Show current status
  --help                        # Show help

# Monitoring
tmux list-sessions              # View active Hank sessions
tmux attach -t <name>           # Reattach to session

System Requirements

• Bash 4.0+
• Claude Code CLI — npm install -g @anthropic-ai/claude-code
• tmux — For integrated monitoring
• jq — JSON processing
• Git
• GNU coreutils — macOS: brew install coreutils

Testing

npm install
npm test    # Runs all BATS tests

Acknowledgments

• Geoffrey Huntley — Original technique
• Claude Code by Anthropic
• frankbria/ralph-claude-code — Upstream project

License

MIT — see LICENSE.