# Frequently asked questions 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 usual 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. 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 external service can still change, fail or return different results. We need to 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 – can contain hallucinated endpoints, stale APIs, and assumptions not checked against current documentation. We can carry the useful work forward by checking the prompts and logic, extracting the part that belongs in a codon prompt, and freezing it as the codon's `promptFile` with explicit context. That makes it hank code rather than a tool-proprietary macro, so it can survive upgrade cycles as part of the version-controlled program. For context shared by every codon, use the hank-level `globalSystemPromptText` or `globalSystemPromptFile`: these provide a hank-level equivalent of shared skill context without the tool lock-in. ## 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 models on the same artifact, one after another, with fresh context. The value is the chance to catch different mistakes. 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 safe parallelism: it **observes** the primary thread and **fires** its own LLM calls without blocking the main agent. That parallel observation is separate from the sequential codon sequence. > **DeepDive:** Why use three sequential fresh-context model executions instead of asking one model to review itself? Independent reads provide viewpoint diversity; a self-review inside one context does not provide the same separation. ## 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. With checkpoints, resume, and receipts, we can preserve that context and investigate what happened when a later execution breaks. The same hank that needs a frontier model early on can often use a cheaper model later, if checkpoint, rollback, and resume infrastructure lets us compare outputs across model tiers and confirm equivalence. Hankweave's runtime sits underneath the model, so models can make hanks cheaper and faster while deterministic control flow, checkpoints, receipts, and budget enforcement remain 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 we can compare a fresh run with the outputs we previously trusted. Select the model with `--model --start-new`, then inspect the new execution's `agentRoot/` outputs against those saved references. The selected models are recorded in `.hankweave/state.json`. The journal at `.hankweave/events/events.jsonl` records the runtime's state, agentic-backbone and sentinel events; it is not a transcript of every model turn. If we need to return to the last-known-good model, select that model and start a new plan. Resuming or rolling back an existing execution does not make an already-resolved codon adopt a newly edited model. Rollback restores the selected checkpointed file state; it is a different operation from choosing a new model. The [recovery guide](/operate/resume-rollback-and-retry) explains those choices. A pinned model ID can make a model change intentional, but a provider can still retire that ID. A catalog-preflight failure identifies an unavailable model and lists available models for that provider. Recheck the chosen spelling when upgrading. ## Can hanks call other hanks? Yes. A rig command can invoke a child hank as a subprocess before the codon's agent starts, for example `bunx hankweave@ ./child-hank.json ./data`; the child passes results through files like any other rig output. The parent hank's `requirements.env` must list every key the child needs. The rig inherits the parent's process environment plus the codon's `env` block, and the child's own `requirements.env` cannot add a key after launch. The child hank's outputs land in its own execution directory's `agentRoot/`, so the rig script must copy needed results to the parent's `agentRoot/`; output-directory behavior is owned by the [runbook](/operate/runbook). This composition creates a dependency chain: if the child changes, the parent's output may change, so apply the same re-run-and-diff discipline used for model changes. The child's execution plan records its codon's model in `state.json`, while its execution metadata records the Hankweave runtime version. A worked parent-and-child example lives in the [composition guide](/author/patterns/composition). ## Where do secrets go? Keep secrets in system environment variables, not in `hank.json`: the runtime accepts a plain key such as `ANTHROPIC_API_KEY` and its `HANKWEAVE_`-prefixed counterpart, so you can set `HANKWEAVE_ANTHROPIC_API_KEY` in your shell profile. When it passes a `HANKWEAVE_` variable to the agent, it removes the prefix, so the agent sees the plain variable name; `HANKWEAVE_RUNTIME_*` and `HANKWEAVE_SENTINEL_*` are excluded. Unlike a value in versioned hank configuration, a system environment variable is not versioned or checkpointed. Set `HANKWEAVE_SOME_VAR=unset` to delete `SOME_VAR` from the process environment at startup; `unset` is a deletion instruction, not a value to pass to the agent. This blocks a value that would otherwise leak from the parent shell. Sentinel keys use the separate `HANKWEAVE_SENTINEL_` prefix: the runtime checks that name before the direct `` name, so a sentinel using a different provider from the main codon needs one additional environment variable. The `hank.json` `env` field sets variables inside the agent process. Use the system environment with the `HANKWEAVE_` prefix when the value must not persist in versioned or checkpointed files. See the [environment variable reference](/reference/environment-variables) for the complete variable set. > **Pitfall:** Putting a secret in `hank.json`'s `env` exposes it inside the agent process and gives up the non-persistence advantage of system environment variables. Use a `HANKWEAVE_`-prefixed system environment variable instead.