Hankweave

A runtime for reliable, brownfield AI engineering.

Hankweave freezes ephemeral agentic behaviors into hanks—declarative, reproducible AI programs that execute deterministically. When your agent fails on run #47, you don't debug "emergent behavior." You trace the exact sequence of events, roll back to a checkpoint, and fix it.

How It Works

A hank is a JSON file that defines your agentic workflow. It's made of codons—atomic units of work, each with a prompt, a model, and tracked files. The runtime executes this workflow, creating checkpoints and detailed event logs along the way.

┌──────────────────────────────────────────────────────────────────────────────┐
│  HANK: data-codebook                                                         │
├──────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐    │
│  │ Observe  │──▶│  Schema  │──▶│  Enrich  │──▶│ Annotate │──▶│ Diagrams │    │
│  │ (gemini) │   │ (sonnet) │   │ (gemini) │   │ (sonnet) │   │ (sonnet) │    │
│  └──────────┘   └──────────┘   └──────────┘   └──────────┘   └──────────┘    │
│       │              │              │              │              │          │
│       ▼              ▼              ▼              ▼              ▼          │
│  observations   zod schemas    enriched      annotated     visualizations    │
│  + questions                    context       schemas                        │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘

Each codon runs in isolation with a fresh context window. Between codons, context can be passed forward or firewalled. When something fails, you debug that specific codon at that specific point—not "the agent."

Key features:

• Checkpoints — Every codon completion creates a git commit. Roll back to any point.
• Rigs — Deterministic setup scaffolding (copy files, run commands) that runs before each codon.
• Loops — Iterate until a condition is met or context is exhausted.
• Sentinels — Parallel agents that watch the event stream and intervene.
• Failure Policies — Configure how codons handle failures: abort, retry, or ignore.
• Extensions — Let codons continue until context is exhausted for unbounded exploration.
• Multi-Model — Orchestrate Claude, Gemini, and OpenAI models in the same workflow.

Why Hankweave

Greenfield AI is easy. Brownfield AI—keeping it working six months later—is hard.

Agentic systems rely on "emergent behavior," which means you don't know exactly what happens next time. Hankweave provides structure that makes complexity linear instead of exponential:

• Codon boundaries act like circuit breakers—problems in codon 3 don't leak into codon 7.
• Checkpoints let you roll back and try different approaches.
• Event logs show exactly what happened, tool call by tool call.
• Sentinels catch issues in real time before they cascade.

When something breaks on run #101 that worked 100 times before, you have the tools to find and fix it.

Getting Started

For new users, we recommend this path to build foundational knowledge before diving into advanced topics.

Documentation

Pick the track that fits your role.

For Operators: Running Hanks

Execute existing hanks, monitor progress, and debug when things go wrong.

• Getting Started — Installation, first run, and basic workflow
• Debugging — Troubleshoot failures and trace issues
• CLI Reference — All commands, flags, and exit codes
• Files and Directories — Where everything lives on disk
• Docker Deployment — Containerized and air-gapped setups

For Authors: Writing Hanks

Design and build your own declarative AI programs.

• Codons — The atomic unit of agentic work
• Hanks — How codons compose into programs
• Loops — Iteration with termination conditions
• Sentinels — Parallel observation and intervention
• Building a Hank — Complete tutorial from scratch
• Testing Hanks — Validate before spending tokens
• Advanced Patterns — Multi-model orchestration and error recovery
• Use Cases — Real-world patterns from production
• Configuration Reference — Complete hank.json schema
• API Keys and Models — Provider setup

For Integrators: Building on Hankweave

Integrate Hankweave into larger systems and build custom tooling.

• WebSocket Protocol — Complete API specification
• Client Libraries — Build custom clients
• Event Journal — Persistent event stream
• Harnesses and Shims — Agent integration layer

For Contributors: Contributing to Hankweave

Understand internals to contribute effectively.

• Execution Flow — Complete lifecycle walkthrough
• State Machine — Formal model of execution states
• Execution Thread — History reconstruction across runs
• State File — Understanding state.json

Further Reading

From the Southbridge blog:

• CCEPL-Driven Development (opens in a new tab) — The workflow for building hanks
• Antibrittle Agents (opens in a new tab) — The philosophy behind reliable long-horizon agents

Technical deep dives:

• Execution Flow — How the runtime orchestrates everything
• State Machine — The formal model underlying execution
• WebSocket Protocol — Complete API specification
• Performance — Cost tracking and optimization

Brought to you by Southbridge (opens in a new tab). By using Hankweave, you agree to our Terms of Service (opens in a new tab). Fun fact: this documentation was built by Hankweave.