hankweave — Summary

hankweave is a JavaScript/TypeScript runtime (npm: hankweave, binary: hankweave) for long-horizon headless agent execution, developed at Southbridge AI. It orchestrates existing AI harnesses (Claude Code, Codex, Gemini CLI, Pi, OpenCode) rather than reimplementing an agent loop, letting those tools do the actual model calls while hankweave handles the execution scaffolding. Programs are called "hanks" — JSON configuration files defining sequences of "codons" (sealed agentic blocks) with "rigs" (deterministic setup scripts), "sentinels" (parallel real-time monitors), and "budgets" (cost/time/token limits). The runtime provides checkpointing + rollbacks at every codon boundary, a structured event journal tracing all tool calls, preflight validation, and a WebSocket event stream for external consumers. The single-agentic-thread constraint is explicit by design: "Much like time travel in stories, parallel systems make it incredibly hard to reason about behavior."

Compared to seeds, hankweave is unlike all 11 seeds. Seeds are developer-productivity harnesses; hankweave is a production operations runtime for running frozen, previously-developed agentic programs (hanks) reliably for hours or days — the "deploy" half of the development lifecycle, not the "build" half.

hankweave — Overview

Origin

Developed at Southbridge AI (SouthBridgeAI), used internally for production AI workloads: platform migrations, research compilation, codebook generation, planning. The FAQ states: "Claude Code is where you develop. Hankweave is where you ship."

Core Philosophy

From the README:

"Past a certain complexity — or task horizon — agentic systems become impossible to maintain and very hard to debug. The ultimate bottleneck isn't the model. It's the human being able to understand and reason about the behavior of an agent."

"Hankweave is not a coding agent. It lacks the interactivity and emergent flow-states where machine and minds fuse together. It trades some of the fun of developing something new to make repairing and maintaining systems easier. Hanks are harder to write, but far more reliable in execution, and orders of magnitude easier to debug."

"Hankweave is not a framework. It makes some opinionated choices to make longer and longer hanks easier to reason about and control, but the runtime remains highly configurable."

Opinionated Choices

• Single agentic thread: one agent executing at any time — "Much like time travel in stories, parallel systems make it incredibly hard to reason about behavior."
• Simple tools, used well: file edits, scripting, shell commands. No MCPs, no skill trees.
• Non-interactive: no chat, no back-and-forth. Managed agentically or programmatically.

Brownfield Engineering

The philosophy is "brownfield AI engineering" — systems you can maintain, improve, and hand to someone else without "it works but you'll need me" attached. Hanks accumulate wisdom: edge cases become fixes, fixes become knowledge.

Unusual Terminology

The README explains: "We believe that the future consumers of hanks will be AI models that edit, modify, and reweave them. Distinct names reduce hallucinations from models assuming they know what something is without looking it up."

hankweave — Architecture

Distribution

• Type: npm package (hankweave on npm)
• Version analyzed: 0.6.2
• Branch: release/alpha (not main)
• Install: bunx hankweave (no global install required); bun install -g hankweave
• Binary name: hankweave
• Required runtime: Bun (primary), Node.js compatibility
• Target harnesses: Claude Code, Codex CLI, Gemini CLI, Pi, OpenCode (all external)

Repository Layout

server/                         # Main TypeScript runtime
├── archive-manifest.ts         # Archive/snapshot management
├── checkpoint-git.ts           # Git checkpointing at codon boundaries
├── claude-agent-sdk-manager.ts # Claude Code harness driver
├── codex-runtime-extractor.ts  # Codex CLI harness driver
├── codon-runner.ts             # Core: execute a single codon
├── event-journal.ts            # Structured event log
├── execution-planner.ts        # Hank execution planning
├── execution-thread.ts         # Single-threaded execution engine
├── hankweave-runtime.ts        # Main runtime entry
├── sentinels/                  # Sentinel monitoring system
├── state-manager.ts            # State machine management
├── storage/                    # Storage backends
├── telemetry/                  # Usage telemetry
├── wizard/                     # `hankweave init` wizard
├── prompt-builder.ts           # Prompt assembly from .md files
├── prompt-frontmatter.ts       # YAML frontmatter parser for prompts
└── llm/                        # LLM proxy (for sentinel calls)

schemas/
├── hank.schema.json            # JSON Schema for hank.json files
├── hankweave.schema.json       # Runtime config schema
└── sentinel.schema.json        # Sentinel definition schema

learning/
├── hank-basics.md              # Getting started guide
└── examples/                   # Annotated production hanks
    ├── clausetta/              # Auto-generates shims for changing harnesses
    └── plan-gen-v2-general/    # Production planning workflow

Config Files

• hank.json — main workflow definition (JSON, validated against hank.schema.json)
• Runtime config: API keys, model settings, data directory (separate from hank)
• hankweave.schema.json — runtime configuration schema

Supported Harnesses

The runtime orchestrates external processes:

• Claude Code (via claude-agent-sdk-manager.ts)
• Codex CLI (via codex-runtime-extractor.ts)
• Gemini CLI
• Pi
• OpenCode
• Custom shims (via Clausetta example)

hankweave — Components

Core Primitives

Hank (the program)

A hank.json file defining the complete agentic workflow:

{
  "$schema": "https://unpkg.com/hankweave@latest/schemas/hank.schema.json",
  "meta": { "name": "My Workflow", "version": "1.0.0" },
  "overrides": {
    "model": "sonnet",
    "budget": { "maxDollars": 10.0, "maxTimeSeconds": 3600 }
  },
  "codons": [...],
  "sentinels": [...]
}

Codon (agentic block)

Sealed unit of agentic work:

• id, name — identifier
• promptFile — path to markdown prompt file (with YAML frontmatter)
• model — model override for this codon
• continuationMode — "fresh" (new context) or "continue" (append to previous)
• checkpointedFiles — glob patterns for files tracked by this codon

Rig (deterministic setup)

Deterministic code that runs before a codon to prepare its environment. Shell scripts or TypeScript.

Sentinel (real-time monitor)

Runs in parallel to the main agent thread, tapping the event stream:

• Trigger: event pattern or LLM condition
• Action: deterministic code, LLM evaluation, or both
• Use cases: guardrails, cost tracking, drift detection, live documentation

Budget

Enforced independently per codon + globally per hank:

• maxDollars — cost budget in USD
• maxTimeSeconds — wall-clock time limit
• allocation — "shared", "proportional", "proportional-strict"

CLI Subcommands

Event Journal

Structured log of all tool calls, file writes, and decisions. Used for debugging 18+ hour runs. WebSocket stream for external consumers (CI systems, custom UIs, data pipelines).

Checkpointing

Git snapshots at every codon boundary. Rollback to any previous codon: hankweave replay.

No Skills, No Hooks, No Slash Commands

hankweave ships no Claude Code hooks, no .claude/ files, and no slash-command markdown. It is a standalone execution runtime.

hankweave — Uniqueness

Differs from Seeds

hankweave is unlike all 11 seeds. Seeds are developer-productivity harnesses for interactive AI coding sessions. hankweave is a production operations runtime for executing frozen agentic programs reliably. The closest analogy is claude-flow in providing a runtime with checkpointing, but claude-flow augments the agent loop; hankweave replaces the developer's interaction with a frozen, version-controlled execution plan. The single-agentic-thread constraint is the clearest differentiator from every other framework in this batch and all seeds: while others add parallelism, hankweave explicitly removes it for maintainability reasons.

Distinctive Position

1. Only framework that explicitly prohibits parallel agents — single agentic thread as a first-class design constraint
2. Only framework that orchestrates OTHER agent harnesses rather than implementing its own — Claude Code, Codex, Gemini CLI are subprocess drivers
3. Git checkpointing at every codon boundary — not just session checkpointing; full git snapshot for rollback
4. Sentinels — the most sophisticated monitoring primitive in this batch: parallel LLM-powered observers that tap the event stream without interrupting execution
5. Brownfield engineering philosophy — explicitly targets the "maintain and hand to someone else" problem rather than the "build new features" problem
6. CCEPL-driven development — a named methodology for freezing interactive work into reproducible hanks
7. Clausetta — a production hank that auto-generates harness shims when AI tool APIs change, using hankweave to maintain itself

Explicit Anti-Patterns

From the README:

• Parallel agentic systems ("make it incredibly hard to reason about behavior")
• Interactive chat (non-interactive by design)
• MCPs, skill trees, "latest cool thing" (simple tools only)
• Using hankweave for "greenfield ease" when brownfield maintainability isn't needed

Observable Failure Modes

• release/alpha branch as default: not production-stable semver
• Stars (123) suggest niche/early audience
• Bun dependency: limits environments where Bun isn't available
• No human-in-the-loop: hanks must be self-healing via sentinels + retry logic or fail entirely
• Harness-specific runtime extractors: adding a new harness requires writing a new extractor

Inspired By

"Antibrittle Agents" blog post by Southbridge, CCEPL-driven development methodology.