This page collects the questions that come up once you start designing real hanks: why Hankweave makes the choices it does, how to carry existing work into it, and what happens when the world around your hank changes. Each answer stands alone, but they share a theme – Hankweave trades convenience for inspectability, and most of the answers below show where that trade lands. Where an answer depends on mechanics covered elsewhere, it links to the guide that owns those details.
Why doesn't Hankweave support MCP servers?#
“MCP” means Model Context Protocol. Hankweave does not bundle an MCP client; its documented integration path is an explicit, versioned rig command. When a task is deterministic, we can put it in a script, test it with known inputs, and keep it beside the hank. That gives us something inspectable to maintain; it does not mean every shell command is deterministic.
An MCP server is a runtime dependency outside the hank's version control: the server can change, go down, or return different results across runs. The supported preference is explicit, inspectable, minimal capability. If we need an MCP-backed capability, a rig can invoke its client, pin the dependency and save the response for a codon to read. The rig makes the invocation explicit; it does not remove the external service's failures or nondeterministic responses, so we handle and check that behavior rather than assume the rig makes it repeatable.
Why can't I import my Claude Code skills?#
A carefully curated skill is worth keeping, but inspect it before importing it wholesale. Skills – prompt bundles managed by a coding agent's own tool – are often model-generated and never verified against current documentation, so they can contain hallucinated endpoints, stale APIs, and assumptions that were never checked. The recommended pattern is inspect-and-extract: examine the skill's prompts and logic, extract the part that belongs in a codon prompt, and freeze it as the codon's promptFile with explicit context. That makes it hank code rather than a tool-proprietary macro, so it survives upgrade cycles as part of the version-controlled program.
For context shared by every codon, the hank-level globalSystemPromptText or globalSystemPromptFile fields provide an equivalent of shared skill context without the tool lock-in: one file, version-controlled, applied to every codon.
Why no parallel agents?#
Hankweave keeps one primary agent thread: codons run sequentially, never concurrently. Coordinating sibling agents adds communication among every pair, and that load – with its failure modes – can multiply faster than throughput. We can still seek different views by running separate fresh-context model reviews on the same artifact, one after another. Different views may catch different errors; that is the method to use. It is not a measured success probability, and fresh context alone does not establish independent failures.
A sentinel – an observer of the event stream – provides parallelism where it is safe: it observes the primary thread and fires its own LLM calls without blocking the main agent. That parallel observation adds no coordination surface to the sequential codon sequence.
Why the unusual names?#
The names take some learning. We choose terms such as codon deliberately: when an agent sees an unfamiliar word, it is more likely to recognize that it needs a specific definition and ask, while familiar words such as “task” or “pipeline stage” can activate associations that do not match Hankweave's semantics.
The vocabulary also maps to a biological metaphor: a codon is a sealed unit of genetic code; a hank – the whole program, “a hank of DNA” – contains the codons; and the runtime expresses codons in sequence. The metaphor is a teaching aid, not a hidden implementation constraint.
Won't better models make Hankweave obsolete?#
Better models make greenfield work – building something new from scratch – easier. They do not by themselves preserve the local history, regression cases, and organizational intent we accumulate in long-lived brownfield work. Checkpoints, resume, and receipts preserve that context and answer “what happened” when a later execution breaks, regardless of how smart the model was.
The same hank that needs a frontier model on run 1 can often run on a cheaper model by run 100 – but that downshift requires the checkpoint, rollback, and resume infrastructure to safely compare outputs across model tiers and confirm equivalence. Hankweave the runtime sits underneath the model: as models improve, hanks get cheaper and faster, while the runtime's value – deterministic control flow, checkpoints, receipts, budget enforcement – is model-independent infrastructure.
What if model behavior changes overnight?#
Provider updates can change model behavior without changing our prompt: structured JSON on one run may become narrative prose on another. Hankweave cannot prevent that change, but it gives us the tools to detect it and recover. To compare a new model, build a fresh plan in a new execution directory with --model <new> --start-new, then compare the new execution's agentRoot/ outputs with the reference outputs we previously trusted. The resolved models are recorded in .hankweave/state.json; while a run is live, .hankweave/events/events.jsonl journals server-state, agentic-backbone and sentinel events – it is not a transcript of every model turn.
Model selection is tied to the plan, not the invocation. Every entry in a persisted execution plan keeps the model it was planned with: a resume (managed or with -e <dir>, without --start-new) restores the plan verbatim and runs each entry – failed or not yet started – on its persisted model, whatever a startup --model override prints. To change or compare a model, build a fresh plan with --start-new in a new execution directory. Rollback restores checkpointed file state; it is not a model-selection operation. The recovery guide explains those choices.
A pinned model ID makes a model choice intentional, but it does not guarantee the model still exists. The startup self-test's catalog check looks the ID up in Pi's static vendored catalog – it never asks the provider – so a provider-retired ID passes startup and surfaces as a provider error when the codon calls the model, after earlier codons have run. (Models on Claude Agent SDK routes get no catalog check at all.) Recheck the chosen spelling when upgrading; the details are owned by the model-resolution reference.
Can hanks call other hanks?#
Yes. A rig command operation can invoke a child hank as a subprocess before the codon's agent starts, and the child passes results through files like any other rig output. The command's run string is an ordinary shell invocation in its working directory, with the parent's process environment plus the codon's env block; the load-time path constraints that apply to copy operations do not sandbox a command's side effects. The child's outputs land in its own execution directory's agentRoot/, so the rig script must copy the needed results back into the parent's agentRoot/; output-directory behavior is owned by the runbook.
On environment variables: requirements.env only checks that the keys it names are set – it does not forward or filter what a rig-launched child receives. A child inherits every key the parent's shell has, listed or not; listing the child's keys in the parent's requirements.env is still useful as an optional fail-fast check, because the parent fails at load if one is missing.
Composition creates a dependency chain: a changed child can change the parent's output, so compare the resulting artifacts the way we would across a model change. A child's .hankweave/state.json records its resolved codon models, while its .hankweave/execution-meta.json records the Hankweave version separately. The worked parent-and-child example, including the exact rig command and its captured run, lives in the composition guide.
Where do secrets go?#
Keep provider credentials in the provider's own system variable – ANTHROPIC_API_KEY, GEMINI_API_KEY, and so on – not in hank.json. A HANKWEAVE_-prefixed variable is a different mechanism: the runtime copies it into the agent's environment with the prefix stripped (the agent sees the plain variable name), and it is accepted in requirements.env in place of <VAR>. It is not a substitute for the provider's own credential on the default Anthropic route – the startup self-test reads the plain ANTHROPIC_API_KEY and fails before any codon when only the prefixed copy is set. HANKWEAVE_RUNTIME_* and HANKWEAVE_SENTINEL_* are excluded from the pass-through – but that exclusion is a Claude Agent SDK child-environment detail, because that child's environment is built from a fixed pass-through list. A Pi-harness codon's shell commands spawn with a copy of the server's whole process environment plus Hankweave's overlay, so they still see HANKWEAVE_RUNTIME_* and HANKWEAVE_SENTINEL_* under their own names. Unlike a value in versioned hank configuration, a system environment variable is not versioned or checkpointed.
Two more mechanisms round out the picture. Setting HANKWEAVE_SOME_VAR=unset deletes SOME_VAR from the process environment at startup and removes it from the agent's effective environment – useful for blocking a variable that would otherwise leak from the parent shell (unset is a deletion instruction, not a value). And sentinel keys use the separate HANKWEAVE_SENTINEL_<VAR> prefix, checked before the direct <VAR> name, so a sentinel using a different provider from the main codon needs only one extra environment variable. The environment variable reference owns the complete precedence table, including the per-variable pass-through, exclusion and shell-spawn rules for each harness.