Why Hankweave?

The problem this exists for#

We make Hankweave because we want people and LLMs to work well together. It is a labor of love, with a practical aim: help us preserve useful work, inspect what happened, and carry what we learn into the next run. This page explains what that aim means in practice, so you can judge whether your work fits it.

Start with a concrete example: a saved quote-unification workflow. Eight suppliers submit quotes for a five-part bill of materials in three digitizer dialects and five native extracts; seven codons – bounded units of work – turn those inputs into checked records and a cited recommendation. Its unified-records.csv contains 40 supplier-part rows across the eight suppliers and five parts. An unknown-format submission is quarantined in an exception ledger rather than added as a ninth supplier. In the award brief, we can inspect each unit price and line extension beside the winning quote's [source_document_id:source_block_id] citation. Canonical supplier envelopes, a validated-records table, the exception ledger, and a receipt.json recording per-codon success, cost, and duration let us inspect the work after the run.

None of that comes from a good answer in one conversation. Long agentic runs can lose their thread: prompts that start crisp become long, qualified, and hard to trust, while tool calls accumulate without being folded back into a usable account of what is now known. The workflow above survives that because its intermediate state is written down, not held in a chat window.

A hank gives work like this a durable shape beyond one coding-agent session. Work left only in a session is tied to that session's context; work frozen into a hank can be resumed, inspected, and improved by a later agent. Use a direct coding-agent chat while you are still discovering the problem and its output shape; move to a hank when the work has a repeatable shape and must survive the session that started it. How a run works explains the execution model.

Why not run it once?#

Once a workflow exists, the natural question is whether rerunning it from scratch is enough. A plain rerun has a defined meaning when execution-directory state exists: it resumes the previous execution. --start-new (or -n) starts a fresh execution and never resumes. That distinction matters when a later attempt should continue from saved work rather than silently begin without it.

Resume works because the runtime records what happened. A checkpoint is a sealed restore point backed by git. checkpointedFiles identifies the files tracked by that checkpoint system, with gitignore rules resolving the tracked set. A rerun can restore files from a prior codon's checkpoint instead of redoing completed work.

Alongside checkpoints, the runtime journals three event classes–server-state, agentic-backbone, and sentinel events–to a file-backed event journal in the execution directory. The journal is drained before shutdown, leaving a durable record for later inspection. That record is bounded to those journaled classes; it is not an exhaustive audit of every model contact or filesystem edit.

Together these give us execution state, restore points, and journaled events to inspect when we return to the work. A small one-off can still be better served by a direct chat.

Why not build this yourself?#

For a small workflow, copying useful patterns into a simpler custom stack can be sensible. Reimplementing the runtime means taking on the reliability work behind checkpointing edge cases, crash recovery, rollback state, and the test suite.

The release history shows what that maintenance looks like in practice:

1. In 0.7.3, transient API errors such as connection drops, server overloads, timeouts, and rate limits were classified as retriable so onFailure: "retry" could apply to them. Under onFailure: "abort", a retriable failure in headless mode now fails and shuts down through a 30-second watchdog instead of hanging.
2. In 0.8.0, the runtime removed the gemini-cli, codex, and opencode subprocess shims and made the Pi harness in-process, leaving exactly two in-process harnesses: the Claude Agent SDK and the embedded Pi coding agent.
3. In 0.10.0, every path a hank author writes into a hank's configuration documents is checked as a portable relative POSIX path (a portable Unix-style path format) that stays inside the hank directory and does not pass through a symlink (a filesystem link to another path) inside it.

Each of these is a boundary case someone had to find, fix, and keep fixed. Owning a long-lived runtime means maintaining these too. Copy the patterns if that is enough for your scope; reimplement the runtime only if you also want to own those reliability boundaries.

Why not another harness, or a meta-harness?#

If you already have a harness you like, the question shifts from reliability to what the runtime adds around model calls. The choice is not only which model to call. Hankweave selects the in-process runtime for each codon at dispatch time. First-party Anthropic models and Anthropic-family models hosted on Amazon Bedrock use the Claude Agent SDK; everything else uses the embedded Pi coding agent.

An explicit pi/<provider>/<model> spelling sets an optional harnessOverride without rewriting the model's real providerId or modelId. A routing fix can therefore apply to a resumed run after an upgrade while the run retains its provider and model identity.

The runtime also exposes a budget contract at hank, loop, and codon level. Each budget object can carry maxDollars, maxTimeSeconds, and onExceeded, so a workflow can bound work at the level where the limit matters.

Finally, the runtime can run a sentinel, a parallel observer that processes the event stream outside the agent's context. In a harness we build ourselves, adding a hook means writing an imperative callback inside that loop's code. With a sentinel, we can keep observation for a separate consumer outside the loop, with its own output contract, text or jsonl.

↗ Enlarge

+-- Hankweave runtime --------------------------------------------------+
|                                                                      |
|                    codon at dispatch time                            |
|                              |                                       |
|                  model and harnessOverride                           |
|             Anthropic       / \      other models,                   |
|             or Bedrock      v   v     or a pi/ override               |
|              Claude Agent SDK   embedded Pi coding agent             |
|                       \           /                                  |
|                        event stream                                  |
|                              :                                       |
|                  outside the agent's context                         |
|                              v                                       |
|                           sentinel                                   |
|                              |                                       |
|                     text or jsonl output                             |
+----------------------------------------------------------------------+

Who this isn't for yet#

The same properties that make a hank durable make it the wrong tool in some situations:

• If you are exploring something for the first time and do not know the output shape, use a coding agent directly.
• If this is a true one-off–run once, read the answer, and never revisit it–talk to the model directly.
• If the work needs a decision every few minutes based on what the agent has produced, keep it interactive rather than building infrastructure.
• If judgment calls are dense and contested even among humans, keep a human in the loop throughout.

For the fuller fit and anti-fit treatment, see Is Hankweave right for you?.