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. Four items make that possible:

Attach hank.json, the hank – the workflow definition – with env, requirements.env, and embedded keys redacted.
Include the execution directory path. It has the form ~/.hankweave-executions/<id>/; startup prints New execution: <id>, and that ID forms the directory name.
Include the contents of <execution-dir>/.hankweave/state.json. It records progress for each codon – 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 hankweave --version output.

Preserve the surrounding evidence too. The execution directory contains agentRoot/, .hankweave/checkpoints/, .hankweave/events/events.jsonl, and .hankweave/runtime.lock. The exact agent-log path is recorded as claudeLogPath in state.json; follow the log-inspection procedure in 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 is not a substitute. The credential-presence check is not proof that the credential is valid. The captured failure below is the kind of diagnostic to preserve verbatim:


╭────────────────────────────────────────────────────────────────────╮
│  Hankweave v0.10.0                                                 │
│  darwin arm64 • node v23.8.0                                       │
╰────────────────────────────────────────────────────────────────────╯

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 eU (file://<workspace>/build/runtime/0.10.0/node_modules/hankweave/dist/index.js:260:5401)
    at async Egt (file://<workspace>/build/runtime/0.10.0/node_modules/hankweave/dist/index.js:842:647)
    at async file://<workspace>/build/runtime/0.10.0/node_modules/hankweave/dist/index.js:843:754

exit=1

This capture normalizes timestamps, execution IDs, and workspace paths as <ts>, <exec-id>, and <workspace>; use the corresponding values from your own run and do not paste private paths. The run banner is Hankweave v0.10.0 / darwin arm64 • node v23.8.0; the platform, architecture, and Node version vary by machine.

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

hankweave --version

0.10.0

hankweave --version prints the bare version string to stdout and exits with code 0. Include that output verbatim in every report, alongside the run banner. The --help excerpt later on this page labels Saved lockfile as stderr; it is separate from the bare version string.

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

hankweave ./my-hank.json ./data

This runs a hank directly. Hankweave has no subcommands. With no arguments, the runtime launches the welcome wizard rather than running a hank. The captured help text below contains a conflicting bare-invocation example; use the explicit path for a direct reproduction while the discrepancy remains.

Keep these runtime details with the report. Outputs stay in agentRoot/ by default; there is no default hankweave-results directory. See the runbook for the complete output-directory behavior.

If a flag is absent from --help, it may be --replay, --max-cost, --max-time, --without-proxy, or --ignore-data-mismatch; check the CLI reference for their documented forms and the help-parity note. --attach is boolean: use --attach --port 8080 or --attach --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	`v0.10.0`
commit	`d0f0a86`

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. It includes the version banner, argument-inference rules, five option groups, 26 documented 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 hankweave --help at this version, without the colored startup banner. You can compare the banner text above and its box in the authentication-failure capture.

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
  -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                        Non-interactive mode, skip confirmation prompts

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)
  --anthropic-base-url <url> Custom Anthropic API base URL
  --idle-timeout <seconds>  Idle timeout for WebSocket and proxy servers (0-255, 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
  --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)
  -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.


--- stderr ---
Saved lockfile

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.

At 0.10.0, the model_catalog preflight checks at config load whether each codon's resolved model is servable by Pi – the check uses Pi's model catalog – and rejects a model known to the registry but unavailable to Pi, suggesting alternatives before any API call.

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

Run hankweave --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 based on 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.

At 0.10.0, --validate self-tests are local: SDK import, credential presence, and Pi catalog lookup. They make 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 locked command surface. For pre-run checks, use --validate; for failures during a run, use the event journal at .hankweave/events/events.jsonl. 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.