Getting Started

This guide takes you from zero to running your first AI workflow with Hankweave. In five minutes, you'll have it installed, configured, and analyzing data.

What You'll Build

By the end of this guide, you will have:

• A working Hankweave project initialized from a template.
• A sample dataset analyzed by two different AI agents (Claude and Gemini).
• Generated analysis files that you can inspect and modify.

Prerequisites

Before starting, make sure you have the following.

Bun (Required)

Hankweave is built on Bun (opens in a new tab), a fast JavaScript runtime.

To install it, run:

curl -fsSL https://bun.sh/install | bash

Verify the installation by checking its version:

bun --version

Git (Required)

Hankweave uses Git to create checkpoints of your workflow's state. You likely already have it installed.

Verify your installation:

git --version

If not, you can install it from git-scm.com (opens in a new tab).

API Keys (At Least One)

You need an API key for at least one AI model provider. The starter project uses both Claude and Gemini.

• Anthropic (Claude): Get a key at console.anthropic.com (opens in a new tab)
• Google (Gemini): Get a key at aistudio.google.com (opens in a new tab)

Once you have your key(s), set them as environment variables:

export ANTHROPIC_API_KEY="your-anthropic-key"
export GEMINI_API_KEY="your-gemini-key"

export OPENAI_API_KEY="your-openai-key"

1. Create Your First Project

mkdir my-first-hank
cd my-first-hank

bunx hankweave@latest --init

my-first-hank/
├── hank.json              # The workflow definition
├── prompts/
│   ├── analyze-haiku.md   # Prompt for Claude Haiku
│   └── analyze-gemini.md  # Prompt for Gemini
├── data/
│   ├── sample1.txt        # Sample data files
│   ├── sample2.txt
│   └── notes.txt
└── README.md

{
  "meta": {
    "name": "My Workflow",
    "version": "1.0.0",
    "description": "Generated by hankweave init"
  },
  "hank": [
    {
      "id": "analyze-haiku",
      "name": "Analyze Project (Claude Haiku)",
      "model": "claude-3-haiku-20240307",
      "continuationMode": "fresh",
      "promptFile": "./prompts/analyze-haiku.md",
      "outputFiles": [{ "copy": ["analysis-claude.md"] }]
    },
    {
      "id": "analyze-gemini",
      "name": "Analyze Project (Gemini Flash)",
      "model": "gemini-1.5-flash-latest",
      "continuationMode": "fresh",
      "promptFile": "./prompts/analyze-gemini.md",
      "outputFiles": [{ "copy": ["analysis-gemini.md"] }]
    }
  ]
}

2. Run Your First Hank

bunx hankweave@latest

Hankweave v0.2.0

Calculating data signature...
Data signature: a1b2c3
Created execution directory: ~/.hankweave-executions/1737001234567-abc1-a1b2c3
📁 Data source: /path/to/my-first-hank
🏃 Execution: /Users/you/.hankweave-executions/1737001234567-abc1-a1b2c3
🔗 Link type: symlink
🎮 Running in TUI mode (use --headless to disable)

3. Modify and Re-run

Hankweave is designed for iteration. Let's change a prompt and see what happens.

# Project Analysis (Claude)
 
Please analyze the files in the `data` directory and create a comprehensive analysis report.
 
Your analysis should include:
 
1. Overview of each file's purpose
2. Key themes across the files
3. Suggestions for improvement
4. A summary in the form of a haiku.
 
Please create your analysis in a file called `analysis-claude.md` in the execution directory.

bunx hankweave@latest

bunx hankweave@latest --start-new

Understanding the Output

Isolated Execution Environment

Hankweave never modifies your source files. All work happens in an isolated execution directory, ensuring your project stays clean and runs are reproducible.

This directory contains everything related to a specific run:

• read_only_data_source/: A symlink to your project data.
• analysis-claude.md: The file created by the first codon.
• analysis-gemini.md: The file created by the second codon.
• .hankweave/: A folder containing logs, state, and checkpoints.

Checkpoints

Every time a codon completes, Hankweave creates a Git commit in the execution directory's .hankweave/checkpoints repository. This allows you to inspect the state of the filesystem at any point and roll back to a previous state if needed.

Troubleshooting

Pro Tips

As you start building your own hanks, keep these patterns in mind:

Validate Before Running

Always validate your configuration before spending tokens:

bunx hankweave@latest --validate

This catches missing files, invalid models, and configuration errors for $0.00. It also shows you an ASCII visualization of your hank's structure.

Test Cheaply with Model Override

When iterating on workflow structure, test with the cheapest model:

bunx hankweave@latest --model haiku

This overrides all codons to use Haiku, which is ~10-20x cheaper than Sonnet. The output quality won't be production-ready, but you'll know if your workflow executes correctly.

Declare Required Environment Variables

Add a requirements section to fail fast when keys are missing:

{
  "requirements": {
    "env": ["ANTHROPIC_API_KEY"]
  },
  "hank": [...]
}

This is checked during --validate and at startup, so you won't discover missing keys mid-execution.

Next Steps

Congratulations, you've run your first hank! Now you're ready to explore further.

• Learn Core Concepts: Read about Codons and Hanks to understand the building blocks of a workflow.
• Explore Execution: See Execution Flow for a deeper dive into what happens under the hood.
• Master Advanced Patterns: See Advanced Patterns for production-tested techniques like codon decomposition, global system prompts, and archiving in loops.

Reference

Common Commands

Specifying Paths

By default, Hankweave looks for hank.json and your data in the current directory. You can override this behavior.

# Use a specific config file and data directory
bunx hankweave@latest ./my-hank.json ./my-data
 
# Use a specific data directory (with default hank.json)
bunx hankweave@latest ./my-data
 
# Use a remote hank definition from GitHub
bunx hankweave@latest https://github.com/user/repo ./my-data

How It Works

This diagram shows the logic Hankweave follows when you run the command.