Execution Flow

Running a hank involves a complex sequence of events: state machines transition, processes spawn, files are watched, and checkpoints are created. This guide explains the entire execution flow, helping you debug problems, design better hanks, and know what to expect at each stage.

The Big Picture

Execution flows through four phases: Server Startup, Execution Planning, Codon Execution, and Completion. Each codon goes through its own lifecycle within the broader run.

Server Startup

When you run hankweave run, the runtime initializes through a sequence of steps. Each one must succeed before the first codon can execute.

Initialization Sequence

1. Lock File Check — Prevents multiple instances from running on the same project.
2. Checkpoint System — Initializes git-based checkpointing in .hankweave/.
3. State Manager — Loads or creates state.json for run tracking.
4. Event Journal — Opens event storage for WebSocket replay.
5. Sentinel Manager — Prepares the parallel observer system.
6. WebSocket Server — Starts listening for client connections.

Crash Recovery

Sometimes things go wrong. The process gets killed, the machine reboots, or your cat walks across the keyboard. When Hankweave detects a crashed run (a stale lock file or dead process), it marks the run as crashed and offers recovery options:

• Rollback to last success — Restore files to the last good checkpoint.
• Continue from crash point — Pick up where things left off. If a codon was mid-execution, it may need manual intervention.

Execution Planning

Before any codon runs, Hankweave builds an execution plan—a flattened sequence of every codon that will execute, including any loop expansions. Think of it as a flight plan: the runtime needs to know where it's going before it takes off.

Plan Building

The execution planner reads your hank.json and produces a concrete sequence:

Regular codons map directly to the plan. Loops are expanded with iteration suffixes (#0, #1, #2) to give each execution a unique ID for logging, checkpointing, and rollbacks.

Lazy Loop Expansion

Here's a subtlety: loops don't expand all at once. Hankweave expands one iteration at a time.

1. The first iteration (#0) is added to the plan.
2. After it completes, the runtime checks the loop's termination conditions.
3. If the loop hasn't terminated, the next iteration (#1) is added to the plan.
4. This repeats until the termination condition is met.

This is important for contextExceeded termination, as it allows the loop to stop mid-stream if an agent hits its context limit. It also keeps the plan manageable for loops that might run for dozens of iterations.

Codon Execution Lifecycle

Each codon progresses through a state machine with well-defined transitions. Understanding these states is key to debugging when a run gets stuck or fails unexpectedly.

State Machine

State Descriptions

What Happens in Each State

Preparing

This is the rig setup phase. If your codon has rigSetup operations, they run here:

{
  "rigSetup": [
    {
      "type": "command",
      "command": { "run": "mkdir -p src/schema", "workingDirectory": "project" }
    },
    {
      "type": "copy",
      "copy": { "from": "./templates", "to": "src" }
    }
  ]
}

Commands execute in order. If any fails, the codon transitions to failed with a clear error message.

Starting

Hankweave spawns the agent process. For Claude Code, this means running the claude command with the appropriate flags:

• --model — The model to use
• --resume — The session ID, if continuing a previous session
• --append-system-prompt — Any additions to the system prompt
• Environment variables from the env field

Initializing

The agent process is running but has not yet reported its session ID. Hankweave watches the agent's log file for this initialization message, which usually appears within a few seconds.

Running

The agent is executing your prompt. During this state:

• Events stream via WebSocket (assistant actions, tool results, file updates).
• Sentinels observe the event stream in parallel.
• File changes are tracked and reported.
• Costs accumulate as tokens are consumed.

Completing Sentinels

After the agent's main work is done, Hankweave waits for any pending sentinel tasks to complete. This includes:

• Draining sentinel event queues
• Finishing final LLM calls
• Writing any output files

Terminal States

Once a codon reaches completed, failed, or skipped, it is finished and will not transition further.

• completed: A checkpoint is created, files are committed, and costs are finalized.
• failed: Error information is stored, and partial costs are tracked.
• skipped: The user chose to skip; a skip checkpoint is created to record this.

Checkpointing

Every successful codon creates a git checkpoint—a commit capturing the exact file state. This is your time machine.

Checkpoint Types

Checkpoint Flow

What Gets Checkpointed

Files matching your checkpointedFiles patterns are committed. See Checkpointed Files in Codons for the complete reference on glob patterns and tracking behavior.

Event System

During execution, Hankweave emits events over a WebSocket connection. These events power the UI, enable custom integrations, and provide the raw data for sentinels.

Event Categories

Events fall into four categories:

Server State, Agentic Backbone, and Sentinel events are journaled (saved to disk) and broadcast to all connected clients. Connection events are ephemeral and exist only for the current session.

Event Flow

Key Events

codon.started — A codon began execution.

{
  "type": "codon.started",
  "data": {
    "codonId": "generate-schema",
    "codonName": "Generate Schema",
    "sessionId": "abc-123",
    "startTime": "2024-01-15T10:30:00Z"
  }
}

assistant.action — The agent performed an action.

{
  "type": "assistant.action",
  "data": {
    "codonId": "generate-schema",
    "action": "tool_use",
    "toolName": "Write",
    "content": "Writing schema file..."
  }
}

codon.completed — A codon finished.

{
  "type": "codon.completed",
  "data": {
    "codonId": "generate-schema",
    "success": true,
    "cost": 0.0234,
    "duration": 45000
  }
}

Run Lifecycle

A run is the top-level container for a sequence of codon executions. A new run is created each time you start hankweave run.

Run Types

Run States

A run is running while its codons execute. It transitions to completed if all codons finish successfully, failed if a codon fails, or crashed if a crash is detected during recovery.

Continuation Runs

When you roll back to a previous checkpoint and restart, Hankweave creates a continuation run. This lets you fix a problem and try again without losing your history.

In this example, Run 2 starts from the checkpoint created after codon-2 in Run 1. It re-executes codon-3 and then proceeds to codon-4.

Autostart and Manual Mode

Hankweave can run codons automatically in sequence or wait for your command.

Autostart Mode (Default)

With autostart: true, Hankweave automatically starts the next codon as soon as the previous one completes.

Manual Mode

With autostart: false, Hankweave idles after each codon and waits for an explicit codon.next command from a client. This is useful for debugging, step-through execution, or inspecting results between codons.

Cost Tracking

Hankweave tracks LLM costs throughout execution, so you always know what you're spending.

Cost Accumulation

Costs are tracked at multiple levels:

• Per codon — currentCost while running, finalCost when complete.
• Per run — The sum of all codon costs in the run.
• All time — The sum of costs across all runs.

Cost Events

Cost updates stream via WebSocket as tokens are used.

{
  "type": "token.usage",
  "data": {
    "codonId": "generate-schema",
    "inputTokens": 1500,
    "outputTokens": 800,
    "totalCost": 0.0234
  }
}

Common Issues

Codon Stuck in "initializing"

The agent process started but never sent a session ID, which usually means it crashed during startup.

Causes:

• The agent crashed immediately after launch.
• Authentication issues (e.g., an invalid or missing API key).
• Network problems preventing the agent from initializing.

Debug:

• Check the agent's log file (.hankweave/runs/<run-id>/<codon>-claude.log).
• Verify that API keys are set correctly.
• Try running the agent's command manually with the same parameters.

Lock File Errors

You see a "Server already running" error when you know it isn't.

Cause: A previous run crashed without cleaning up the lock file.

Fix: The lock file is located at .hankweave/server.lock. Hankweave should detect stale locks automatically (via its heartbeat mechanism), but if it fails to, you can remove this file manually.

Checkpoint Failures

The codon completes, but the git checkpoint fails.

Causes:

• The git repository in .hankweave/ is missing or corrupt.
• Uncommitted changes in tracked files are causing merge conflicts.
• Disk space issues.

Debug:

• Check that .hankweave/ exists and contains a valid .git directory.
• Run git status in the execution directory to check for conflicts.
• Check your available disk space.

Related Pages

• Codons — The atomic unit of work
• Hanks — How codons sequence into programs
• Checkpoints — Git-based time travel
• State File Reference — Complete state.json documentation
• WebSocket Protocol — Event schemas and API specification

Next Steps

Now that you understand the execution flow:

• Getting Started — Run your first hank.
• Debugging — Learn what to do when things go wrong.
• WebSocket Protocol — Build custom integrations on the event stream.