Hankweave - Get help and file useful bugs

When a run fails, the fastest path to a fix is a report we can act on without a second round of questions. This page covers what to gather, where to send it, and what to check first so that many problems never need a report at all.

What to include in a bug report#

A useful report lets us follow the run with you. Gather these items:

Attach hank.json, the hank – the workflow definition – with env, requirements.env, and embedded keys redacted, so the exact codon, model and rig configuration is reproducible.
Include the execution directory path. A managed run (one without -e/--execution) creates it under ~/.hankweave-executions/<id>/ and prints New execution: <id>; with -e <dir> the runtime uses exactly the path you named. The help's Tier 1 line, "Cannot use ~/.hankweave-executions/ directly", means only that a new execution cannot be created there – an existing managed execution can be passed to -e and resumed.
Include the contents of <execution-dir>/.hankweave/state.json. It records codon progress – one sealed agent task in the sequence – along with budget state and failure information. Its full schema belongs to the state-file reference.
Include the exact error text from the console or log, whether the run was interactive (a TUI, or terminal interface) or headless (without the TUI, for CI/CD and scripts), and the version output.

Preserve the surrounding evidence too. The execution directory contains the agent workspace (agentRoot/), the agent log, checkpoints (.hankweave/checkpoints/), the event journal, and the runtime lock file (.hankweave/runtime.lock, present while the run is live and removed at clean shutdown). The exact agent-log path is recorded as claudeLogPath in state.json; follow the log-inspection procedure in observe and debug.

The event journal has two finished forms. While a run is live, the journal is .hankweave/events/events.jsonl. At shutdown a finished run's journal is usually compressed to events.jsonl.zst with a journal.meta.json sidecar; when that diet was off, skipped or failed, the plain events.jsonl and its events.meta.json sidecar remain. Read a dieted journal after bunx hankweave@0.11.0 --restore-journal <exec>, or through the runtime. The full procedure belongs to the event journal and observe and debug.

Authentication failures are a common first-run problem, and they show why the exact error text matters. For the default direct-Anthropic Claude route, the startup self-test requires ANTHROPIC_API_KEY; a local Claude Code login alone fails it. Bedrock authenticates through its own AWS credential chain. The self-test checks that a credential is present, not that it is valid. The captured failure below is the kind of diagnostic to preserve verbatim:


╭────────────────────────────────────────────────────────────────────╮
│  Hankweave v0.11.0                                                 │
│  linux x64 • node v22.23.2                                         │
╰────────────────────────────────────────────────────────────────────╯

Created new execution directory: ~/.hankweave-executions/<exec-id>
New execution: <exec-id>
  Source → data
  Exec   → ~/.hankweave-executions/<exec-id>
  SDKs   → Claude node_modules ✓

[<ts>] [ERROR] Self-test completed: FAILED
[<ts>] [ERROR] Self-test FAILED: Some checks failed
[<ts>] [ERROR]   - authentication: ✗ No authentication found (set ANTHROPIC_API_KEY)
[ERROR] Server startup failed!
Error message: Self-test failed for 1 model(s):
  - Claude Haiku 4.5 (latest) (anthropic/claude-haiku-4-5): Some checks failed
      • authentication: No authentication found (set ANTHROPIC_API_KEY)
Stack trace:
Error: Self-test failed for 1 model(s):
  - Claude Haiku 4.5 (latest) (anthropic/claude-haiku-4-5): Some checks failed
      • authentication: No authentication found (set ANTHROPIC_API_KEY)
    at c$ (file://<workspace>/build/runtime/0.11.0/node_modules/hankweave/dist/index.js:337:5382)
    at async N1t (file://<workspace>/build/runtime/0.11.0/node_modules/hankweave/dist/index.js:873:567)
    at async file://<workspace>/build/runtime/0.11.0/node_modules/hankweave/dist/index.js:874:658

exit=1

The failure shape is the diagnostic: the Self-test FAILED block, the authentication: No authentication found (set ANTHROPIC_API_KEY) line, and exit=1. The capture's banner box names the runtime and platform of the machine that recorded it; that line differs between machines. Timestamps, execution IDs and workspace paths are normalized to <ts>, <exec-id> and <workspace> – use the corresponding values from your own run and do not paste private paths.

The version string is the other piece of identity every report needs. Get it with:

bunx hankweave@0.11.0 --version

0.11.0

bunx hankweave@0.11.0 --version prints the bare version string to stdout and exits with code 0. Include that output verbatim in every report.

When you describe how to reproduce the run, give the exact command. Use an explicit path:

bunx hankweave@0.11.0 ./my-hank.json ./data

This runs a hank directly. Hankweave has no subcommands, and before it resolves any hank it checks whether the invocation names one of a fixed set of inputs – a hank path, --config, a data path, --data, -e/--execution, -i/--input, --init, --help, --version, --validate, --cleanup, --attach, --headless, --replay, --restore-journal or --diet-journal. When none is present, the runtime launches the welcome wizard and exits 0 without loading any hank.json. So a bare hankweave, or hankweave with only flags such as -o, -m, -p, -n, -f or -y, never runs the hank in the current directory. Name a path or flag for a direct reproduction.

Keep these runtime details with the report. Outputs stay in agentRoot/ unless an output directory is set by -o/--output or by outputDirectory in hankweave.json (or HANKWEAVE_RUNTIME_OUTPUT_DIRECTORY); there is no default hankweave-results directory. See the runbook for the complete output-directory behavior.

--attach is a boolean flag – it takes no URL. Combine it with --port 8080 or --execution <dir> to connect read-only to a running server.

How to reach the team#

File runtime bugs at the Hankweave issue tracker. The canonical documentation home is hankweave.southbridge.ai.

Send runtime contributions through the runtime repository. Send documentation contributions through the documentation pipeline.

The issue tracker belongs to the release this page describes. Its identity is:

Scroll to explore the table →

Release identity	Value
npm package	`hankweave`
repository	`https://github.com/SouthBridgeAI/hankweave-runtime`
tag	the release tag
commit	`8216cf3`

Compare the locked command reference#

The locked package requires Node ≥22.19.0. For command-reference details, the full --help output is the capture for this release: the version banner, the argument-inference rules, five option groups, all 34 parser flags, the three-tier safety system, and six examples. Use the CLI reference for the maintained flag inventory. When a run will not start, try --validate first; the full validation workflow belongs to the runbook.

Here is the output body of bunx hankweave@0.11.0 --help at this version, without the colored startup banner. You can compare the banner box in the authentication-failure capture above.

Hankweave Runtime - Codon Orchestration

Usage: hankweave [options] [config-or-data-path]

Arguments:
  config-or-data-path       Path to hank.json or project directory
                            When only one argument provided:
                            - If ends with .json: treated as hank-path
                            - Otherwise: treated as data-path

Execution Control:
  -e, --execution <path>    Use specific execution directory
                            Creates if doesn't exist, resumes if has state
  --replay <path>           Replay an execution from recorded logs (no LLM calls)
                            Mutually exclusive with --execution
  -n, --new, --start-new    Start new execution, never resume
                            Use -n -f to overwrite existing state
  -f, --force               Override safety checks (hash mismatch, existing state)
  --no-wipe                 With --start-new --force, preserve the existing
                            agentRoot/ workspace instead of wiping it
  -y, --yes                 Skip confirmation prompts
  --max-cost <dollars>      Set a run-wide cost ceiling in USD
  --max-time <seconds>      Set a run-wide wall-clock limit in seconds

Output:
  -o, --output <path>       Copy outputs to this path (default: stay in execution dir)
  --overwrite-output        Overwrite existing output files instead of renaming

Configuration:
  --config <path>           Path to hank.json (alternative to positional arg)
  --data <path>             Path to data source (default: config directory)
  -i, --input <text>        Use inline text as data input (highest priority)
  -m, --model <model>       Model override (sonnet|opus|gemini-flash|etc)

Server:
  -p, --port <port>         WebSocket server port (default: auto-select free port)
  --headless                Run without TUI (for CI/CD and scripts)
  --no-autostart            Don't automatically start codons
  --proxy                   Enable the LLM proxy server (disabled by default)
  --without-proxy           Disable the LLM proxy (this is the default)
  --anthropic-base-url <url>  Custom Anthropic API base URL
  --idle-timeout <seconds>  Idle timeout for WebSocket and proxy servers (0-255, 0 disables, default: 0)
  --shim-idle-timeout <seconds>   Harness idle timeout in seconds (default: 120, per-codon)

Other:
  --init                    Initialize a new hank in current directory
  -v, --validate            Validate configuration without running
  --cleanup                 Remove execution artifacts
  --restore-journal <path>  Rebuild a dieted execution's event journal (byte-for-byte, verified)
  --diet-journal <path>     Compress a finished execution's event journal (restorable)
  --copy                    Copy data instead of symlinking (for compatibility)
  --ignore-rig-failures     Ignore rig setup failures
  --attach                  Connect TUI to an already-running server (read-only mode)
  --ignore-data-mismatch    [Deprecated] Use --force instead
  -h, --help                Show this help
  --version                 Show version

Execution Safety:
  Hankweave implements a three-tier safety system for execution directories:
  - Tier 1: Cannot use ~/.hankweave-executions/ directly (reserved for auto-managed)
  - Tier 2: Directories with existing .hankweave/ require --force (backs up existing)
  - Tier 3: Non-empty directories show warning and prompt for confirmation

Examples:
  hankweave                           Run with hank.json in current directory
  hankweave ./my-project              Run project, resume if possible
  hankweave ./my-project -n           Start fresh execution (--new)
  hankweave -e ./my-exec              Use specific execution directory
  hankweave -o ./results              Copy outputs to ./results
  hankweave -m opus -p 8080           Use opus model on port 8080

Outputs are stored in the agent workspace (~/.hankweave-executions/{id}/agentRoot) by default.
Use --output to copy them elsewhere.

Tier 1 refuses only a new execution under that root; an existing managed execution with .hankweave/execution-meta.json can be passed to -e and resumed.

Five things in these shipped help bytes need qualification before you rely on them:

The Examples block's first, fifth and sixth lines – hankweave, hankweave -o ./results and hankweave -m opus -p 8080 – launch the welcome wizard and exit 0 without running a hank, because -o, -m and -p are not among the inputs that leave the wizard path. To run the hank in the current directory with those options, name a path: bunx hankweave@0.11.0 hank.json <data> -o ./results or bunx hankweave@0.11.0 . -m opus -p 8080. The other three examples (./my-project, ./my-project -n, -e ./my-exec) are working forms.
The printed default for --data ("default: config directory") is stale. The data source is the positional or --data path (--input and a lone - stdin win); with none of these the runtime resolves it to the directory the command was launched from, and -e or --replay reuse the recorded data path from execution metadata when it still exists. The flag contracts belong to the CLI reference.
The printed default for --shim-idle-timeout ("default: 120, per-codon") is also stale. The setting takes a positive integer up to 1800 with no configured default; a codon's own value wins, and when none is set the Claude Agent SDK harness falls back to 180 seconds and the embedded Pi SDK harness to 120 seconds – the help's 120 is the Pi figure.
--idle-timeout is parsed and validated but changes no idle limit: the merged value is never passed to the WebSocket server or the proxy. The wired harness setting is --shim-idle-timeout.
The --replay line's "(no LLM calls)" describes codon replay only. Replay reproduces the recorded per-codon logs and makes no new codon model calls, but the runtime's startup provider health checks still run and can make billable calls when provider credentials are set, and replay skips the per-model startup self-tests.

What issue #1 taught about first runs#

Issue #1 documented a model-selection failure involving a retired health-check model and the GOOGLE_API_KEY → GEMINI_API_KEY rename. For the full account, read the issue #1 postmortem. To distinguish codon self-tests from provider health checks and choose the next check, use the decision table in authentication and models.

The model_catalog preflight runs as part of the per-model startup self-test – a normal startup and --validate; --replay skips the self-tests – and checks at config load whether each codon's resolved model is servable by Pi, rejecting a model known to the registry but unavailable to Pi, with suggestions, before any API call.

For a first-run Model not found, follow this order:

Run bunx hankweave@0.11.0 --validate and read the catalog-preflight diagnostic.
Check the model spelling against model resolution.
Check the provider key name in the provider key table, including the GEMINI_API_KEY rename.

Before you file#

Start with your error text in troubleshooting, then follow it to the phase, cause, and fix. The entries are built from captured failure fixtures.

If you want to understand a design choice, try the FAQ: names, obsolescence, secrets, MCPs, skills, and parallel agents. You do not need a bug report to ask why something works this way.

--validate runs the same local per-model self-tests as a non-replay startup – SDK import, credential presence, and Pi catalog lookup – with no billable API call. The welcome wizard's pre-demo credit check is the one-token API call, not --validate.

There is no --verbose flag in the command surface. For pre-run checks, use --validate; for failures during a run, use the event journal – .hankweave/events/events.jsonl while the run is live or when the finalize diet was off, skipped or failed, and .hankweave/events/events.jsonl.zst with journal.meta.json after a dieted finish, read after bunx hankweave@0.11.0 --restore-journal <exec> or through the runtime. See the event journal.

If the problem remains, bring us the exact error, execution evidence, version output, and interactive-or-headless distinction at the issue tracker. Those details give us a place to start together.