Configuration Reference

This is a comprehensive reference for all configuration options in Hankweave. It covers the hank.json and hankweave.json files, runtime settings, and environment variables.

Who is this for?

This guide is for:

• Hank authors (Track 2) who need detailed documentation for every configuration field.
• Developers building on Hankweave (Track 3) who need to understand the complete configuration schema.

Configuration Files Overview

Hankweave's configuration lives in two JSON files.

Hank File Structure

A hank file is a JSON object with up to three top-level keys. Only hank is required.

{
  "meta": {
    "name": "Data Codebook Generator",
    "version": "1.0.0",
    "description": "Generates documented schemas from raw CSV files",
    "author": "Your Name"
  },
  "overrides": {
    "model": "sonnet",
    "dataHashTimeLimit": 10000,
    "sentinel": {
      "enablePersistence": true
    }
  },
  "hank": [
    {
      /* codon or loop */
    }
  ]
}

Meta Section

Metadata for humans. Add it when you're sharing hanks or want to remember what you built six months from now.

Overrides Section

The hank author's overrides for runtime settings. These values take precedence over the hankweave.json config file but can still be overridden by environment variables and CLI arguments.

Configuration Layer Precedence: Overrides are layer 3 of 5. They override built-in defaults and the runtime config file, but are themselves overridden by environment variables and CLI arguments. See Configuration Layers for the full hierarchy.

Requirements Section

Declare required environment variables for fail-fast validation at startup.

{
  "requirements": {
    "env": ["ANTHROPIC_API_KEY", "DATABASE_URL"]
  }
}

Validation runs during both --validate and normal startup. The HANKWEAVE_ prefix is automatically supported: HANKWEAVE_API_KEY satisfies a requirement for API_KEY.

Global System Prompts

Apply a system prompt to ALL codons in the hank, useful for enforcing conventions across the entire workflow.

{
  "globalSystemPromptFile": ["./prompts/workspace-context.md", "./prompts/coding-standards.md"],
  "hank": [...]
}

Or with inline text:

{
  "globalSystemPromptText": "Always explain your reasoning. Never use TODO comments.",
  "hank": [...]
}

The global system prompt is prepended before any codon-specific appendSystemPromptFile or appendSystemPromptText content.

Common use cases for global prompts:

Using global prompts avoids repetition and ensures consistency—change the rules in one place, every codon sees the update.

Hank Array

The hank array is the actual program—your codons and loops in execution order. Everything else is metadata and settings; this is where the work happens.

{
  "hank": [
    {
      /* codon 1 */
    },
    {
      /* codon 2 */
    },
    { "type": "loop" /* loop definition */ },
    {
      /* codon 3 */
    }
  ]
}

Items execute sequentially. See Codon Configuration and Loop Configuration for field details.

Codon Configuration

A codon is the atomic unit of work—a single agent task with its own prompt, model, and settings. If hanks are programs, codons are the statements.

Required Fields

Every codon must have these fields:

Plus one of:

• promptFile: Path(s) to prompt file(s)
• promptText: Inline prompt string

Complete Field Reference

Here's a codon with every possible field. You'll rarely need all of these—most codons are much simpler.

{
  "type": "codon",
  "id": "generate-schema",
  "name": "Schema Generation",
  "description": "Generates Zod schemas from CSV observations",
 
  "model": "sonnet",
  "continuationMode": "continue-previous",
 
  "promptFile": ["./prompts/schema-gen.md"],
  "promptText": "Alternative: inline prompt text",
 
  "appendSystemPromptFile": ["./system/rules.md"],
  "appendSystemPromptText": "Alternative: inline system prompt",
 
  "rigSetup": [
    {
      "type": "copy",
      "copy": { "from": "./templates", "to": "src" }
    },
    {
      "type": "command",
      "command": { "run": "npm install", "workingDirectory": "lastCopied" },
      "allowFailure": true
    }
  ],
 
  "checkpointedFiles": ["src/**/*.ts", "schemas/*.json"],
 
  "env": {
    "NODE_ENV": "development",
    "DEBUG": "true"
  },
 
  "outputFiles": [
    {
      "copy": ["dist/**/*"],
      "beforeCopy": [
        { "type": "command", "command": { "run": "npm run build" } }
      ]
    }
  ],
 
  "sentinels": [
    { "sentinelConfig": "./sentinels/narrator.json" },
    {
      "sentinelConfig": "./sentinels/cost-tracker.json",
      "settings": { "failCodonIfNotLoaded": true }
    }
  ]
}

Field Descriptions

Let's break down each group of fields.

Identity and Display

Model and Continuation

Warning: Model Matching Constraint

When using continue-previous, the model must match the previous codon's model. Different models cannot continue the same conversation.

Prompts

Info: Prompt Assembly

If you provide multiple files in promptFile or appendSystemPromptFile, they are concatenated in order. However, the *File and *Text variants for a given prompt type are mutually exclusive (e.g., you must use promptFile or promptText, but not both).

Rig Setup

Rigs handle deterministic setup tasks: copying templates, installing dependencies, or running build commands. Each rig setup item is either a copy operation or a command operation.

Copy Operation:

{
  "type": "copy",
  "copy": {
    "from": "./templates/typescript",
    "to": "src/generated"
  },
  "allowFailure": false
}

Command Operation:

{
  "type": "command",
  "command": {
    "run": "npm install",
    "workingDirectory": "lastCopied"
  },
  "allowFailure": false
}

Warning: Loop Rig Setup

Always use allowFailure: true for rig setup in loop codons. Operations that succeed on the first iteration might fail on the next (e.g., copying to a path that already exists).

File Tracking

Tell Hankweave which files matter. Files matching these patterns are watched for changes, streamed to connected clients, and versioned in the git-based checkpoint system.

"checkpointedFiles": [
  "src/**/*.ts",
  "schemas/**/*.json",
  "!src/**/*.test.ts"
]

Environment Variables

"env": {
  "NODE_ENV": "production",
  "API_ENDPOINT": "https://api.example.com"
}

These are merged with system environment variables, with codon-level variables taking precedence.

Output Files

"outputFiles": [
  {
    "copy": ["dist/**/*", "schemas/*.json"],
    "beforeCopy": [
      {
        "type": "command",
        "command": { "run": "npm run build" }
      }
    ]
  }
]

Sentinels

Sentinels watch the event stream and execute their own logic when patterns match—useful for real-time monitoring, documentation, and guardrails. Each sentinel entry wraps a config file with optional per-codon settings.

Failure Handling

Configure what happens when a codon fails:

{
  "onFailure": {
    "policy": "retry",
    "maxRetries": 3
  }
}

Extensions

Extensions enable unbounded exploration by letting a codon iterate until the model's context window is full. The exhaustWithPrompt string is automatically sent as a follow-up prompt after each completion:

{
  "exhaustWithPrompt": "Please continue. Any more insights or patterns to explore?"
}

See Codons: Extensions for detailed usage.

{
  "sentinelConfig": "./sentinels/narrator.json",
  "settings": {
    "failCodonIfNotLoaded": false,
    "outputPaths": {
      "logFile": "custom-log.md",
      "lastValueFile": "custom-value.json"
    },
    "reportToWebsocket": {
      "lifecycle": true,
      "errors": true,
      "outputs": true,
      "triggers": false
    }
  }
}

Info: Reusable Sentinel Configs

Keeping sentinel configurations in separate files makes them reusable across codons. The settings object lets you customize their behavior for each specific codon.

Loop Configuration

Sometimes, one pass isn't enough. Loops repeat a sequence of codons until a termination condition is met.

{
  "type": "loop",
  "id": "validation-loop",
  "name": "Iterative Validation",
  "description": "Run validation until passing or limit reached",
  "terminateOn": {
    "type": "iterationLimit",
    "limit": 3
  },
  "codons": [
    {
      /* codon 1 */
    },
    {
      /* codon 2 */
    }
  ]
}

Loop Fields

Termination Modes

There are two fundamentally different ways to end a loop.

Iteration Limit: Stops the loop after a fixed number of iterations. This is the safe, predictable choice.

{
  "terminateOn": {
    "type": "iterationLimit",
    "limit": 5
  }
}

Iterations are 0-indexed, so a limit of 5 runs iterations 0, 1, 2, 3, and 4.

Context Exceeded: Stops when the model's context window is full. This is for long-running tasks where you want the agent to work until it genuinely can't continue.

{
  "terminateOn": {
    "type": "contextExceeded"
  }
}

Warning: contextExceeded Constraint

Loops with contextExceeded termination cannot contain codons with continuationMode: "fresh". A fresh codon would reset the context, preventing it from ever filling up and creating an infinite loop.

Loop Constraints

A few rules keep loops predictable and safe:

1. No nested loops: The codons array can only contain codons, not other loops.
2. Model matching: Within a loop, any codon with continue-previous must use the same model as the preceding codon.
3. Post-loop continuation: Any codon immediately following a loop with terminateOn: { "type": "contextExceeded" } must use continuationMode: "fresh", as there is no meaningful context left to continue.

See Loops for detailed behavior documentation.

Runtime Configuration (hankweave.json)

The hankweave.json file controls the Hankweave server's behavior—ports, timeouts, model defaults, and sentinel system settings. This file is optional; sensible defaults are used if it's not present.

{
  "port": 7777,
  "autostart": true,
  "model": "sonnet",
  "outputDirectory": "hankweave-results",
  "sentinel": {
    "enablePersistence": true,
    "healthCheckGracePeriodMs": 2000
  }
}

Server Behavior

Model & API

Info: Model Override Behavior

When model is set via CLI, environment variable, or hankweave.json, it overrides all codon models globally. When set in hank.json overrides, it only serves as a fallback for codons that don't specify their own model.

Resources & Limits

Sentinel System

Environment Variables

Environment variables provide another way to configure Hankweave, which is useful for CI/CD, containers, and keeping secrets out of config files. Hankweave reads variables with three different prefixes.

Runtime Configuration: HANKWEAVE_RUNTIME_*

Override hankweave.json settings. The prefix is stripped and names are converted from SNAKE_CASE to camelCase.

Nested sentinel settings:

Type conversion:

• Booleans: "true" or "1" become true; "false" or "0" become false.
• Numbers are parsed from strings.

Sentinel API Keys: HANKWEAVE_SENTINEL_*

Provide sentinels with their own API keys, which is useful for separate billing or using a different provider than your main codons.

Sentinel-specific keys are checked first. If they aren't found, Hankweave falls back to the standard API key variables.

Codon Environment: HANKWEAVE_*

Variables with the HANKWEAVE_ prefix (excluding RUNTIME_ and SENTINEL_) are passed to codon processes with the prefix stripped.

export HANKWEAVE_DATABASE_URL="postgres://localhost/mydb"
# The codon process sees DATABASE_URL="postgres://localhost/mydb"

Standard API Keys

For primary LLM calls in codons, use the standard environment variables for your provider.

Configuration Layers

Configuration is merged from five sources in a predictable order. Higher layers override lower ones.

Deep merge behavior: Nested objects are merged, not replaced. If layer 2 sets sentinel.enablePersistence and layer 4 sets sentinel.healthCheckGracePeriodMs, the final config will include both settings.

Model Specification

You can specify models in several formats. Start with short names for convenience; use full IDs when you need specific versions.

Short Names

Common Claude models have short aliases:

Full Model IDs

Specify the exact model ID from the provider:

"model": "claude-3.5-sonnet-20240620"

Provider-Prefixed

For non-Anthropic models, use the provider's standard model name:

"model": "gemini-1.5-pro-latest"
"model": "gpt-4o"

Validation

Models are validated at load time against the LLM Provider Registry. Invalid model names will cause a validation error with suggestions for valid alternatives.

Template Variables

When you need an agent to write to specific paths, template variables provide runtime-resolved locations.

{
  "promptText": "Save the output to <%PROJECT_DIR%>/results/output.json"
}

Info: When to use template variables

Use template variables in your prompts when the agent needs to know the absolute path to a file or directory within its sandboxed environment. The agent sees the fully resolved path.

JSON Schemas

Hankweave provides JSON schemas for configuration files, enabling autocomplete and validation in your editor.

Schema Locations

The schemas are included in the npm package at:

node_modules/hankweave/schemas/
├── hank.schema.json        # Schema for hank.json files
├── hankweave.schema.json   # Schema for hankweave.json files
└── sentinel.schema.json    # Schema for sentinel config files

Editor Integration

VS Code: Add this to your workspace settings (.vscode/settings.json):

{
  "json.schemas": [
    {
      "fileMatch": ["**/hank.json", "**/strand.json"],
      "url": "./node_modules/hankweave/schemas/hank.schema.json"
    },
    {
      "fileMatch": ["**/hankweave.json"],
      "url": "./node_modules/hankweave/schemas/hankweave.schema.json"
    },
    {
      "fileMatch": ["**/*.sentinel.json"],
      "url": "./node_modules/hankweave/schemas/sentinel.schema.json"
    }
  ]
}

This gives you:

• Autocomplete for all configuration fields
• Inline documentation on hover
• Validation errors as you type

Validation

Hankweave catches mistakes early. Validation occurs at multiple stages to find different kinds of problems.

Schema Validation

Zod schemas enforce the structure and types of your config files. Invalid fields produce detailed error messages pinpointing the problem.

Invalid hank file:
  - Codon "schema-gen" (codon-2) - continuationMode: Required
  - Codon "validate" (codon-3) - model: Invalid model 'claude-999': Model not found

File Validation

The loader verifies that all referenced files exist before any tokens are spent:

• Prompt files (promptFile, appendSystemPromptFile)
• Rig setup sources (copy.from)
• Sentinel config files (sentinelConfig)

Constraint Validation

Beyond the schema, semantic rules catch configurations that are technically valid but logically broken:

• Codon and loop IDs must be unique.
• continue-previous mode requires matching models between codons.
• contextExceeded loops cannot contain codons with fresh continuation.
• Continuation chains must be valid (e.g., no continuing from a contextExceeded loop).

Pre-flight Validation

Run hankweave --validate before committing tokens to a run. It combines all the above with additional runtime checks:

• All schema, file, and constraint validation.
• Rig setup path security (no .. escapes).
• Model self-tests to verify API connectivity.
• Warnings for risky configurations, like rig setup in a loop without allowFailure: true.

Common Mistakes

These trip up most people at least once. Save yourself the debugging time.

Warning: Missing allowFailure in loops

Rig setup operations in loop codons should almost always have allowFailure: true. Without it, a copy that succeeds on iteration 0 but fails on iteration 1 (because the target already exists) will kill the entire loop.

Warning: Model mismatch with continue-previous

Different models cannot share a conversation. If codon A uses sonnet and codon B uses opus with continue-previous, validation will fail.

Warning: Wrong copy.to path

The to field is the full target path, including the final name, not just the parent directory. from: "./templates/config", to: "src" copies the config directory as src, not into src.

Warning: Fresh codons in contextExceeded loops

This creates an infinite loop because the context never accumulates. All codons in a contextExceeded loop should use continue-previous.

Related Pages

• Codons — Detailed codon behavior and lifecycle
• Loops — Loop termination modes and constraints
• Sentinels — Full sentinel configuration reference
• Hanks — How codons compose into programs
• Rigs — Deterministic setup operations