Codons

Every hank is built from codons: self-contained blocks of agent work, each with a clear purpose. If a hank is a program, a codon is a function—a single, focused task.

What is a Codon?

A codon is a single instruction for an AI agent. It packages a prompt, a model, and a list of files to watch. When Hankweave runs a codon, it spawns an agent (like Claude or Gemini), gives it the prompt, and monitors the files you specified for changes.

┌─────────────────────────────────────────────────────┐
│  CODON: build-schema                                │
├─────────────────────────────────────────────────────┤
│                                                     │
│  PROMPT                                             │
│  "Read the CSV files in data/ and create           │
│   strict Zod schemas in src/schema/"               │
│                                                     │
│  MODEL: claude-sonnet                               │
│  TRACKS: ["src/schema/**/*.ts"]                    │
│                                                     │
└─────────────────────────────────────────────────────┘

When the codon completes, Hankweave creates a checkpoint—a git commit that captures the exact state of the files. The behavior is captured, not emergent, meaning it's repeatable and deterministic, not unpredictable.

Codon Execution Lifecycle

When Hankweave runs a codon, it follows this sequence:

1. Pending — The codon is in the execution plan, waiting its turn.
2. Rig Setup — Deterministic setup commands run (if any).
3. Agent Spawned — The agent (Claude, Gemini, etc.) starts.
4. Running — The agent executes the prompt, reading and writing files.
5. Checkpointing — Tracked files are committed to git.
6. Completed — The codon finished successfully.

Anatomy of a Codon

Here's a minimal codon:

{
  "hank": [
    {
      "id": "build-schema",
      "name": "Build Zod Schemas",
      "model": "sonnet",
      "continuationMode": "fresh",
      "promptText": "Read the CSV files in read_only_data_source/ and create strict Zod schemas."
    }
  ]
}

And here's a full-featured codon using most available options:

{
  "id": "codon-1",
  "name": "Codon 1: Generate Schemas",
  "promptFile": ["./prompts/schema-builder.md", "./prompts/context.md"],
  "model": "sonnet",
  "continuationMode": "fresh",
  "rigSetup": [
    {
      "type": "command",
      "command": {
        "run": "mkdir -p src/schema",
        "workingDirectory": "project"
      }
    }
  ],
  "appendSystemPromptFile": ["./prompts/system-context.md"],
  "description": "Generate Zod schemas from CSV data",
  "checkpointedFiles": ["src/schema/**/*.ts"],
  "env": {
    "DEBUG": "true"
  },
  "outputFiles": [
    {
      "copy": ["src/schema/*.ts"],
      "beforeCopy": [
        {
          "type": "command",
          "command": {
            "run": "bun run typecheck",
            "workingDirectory": "project"
          }
        }
      ]
    }
  ],
  "sentinels": [
    {
      "sentinelConfig": "./sentinels/narrator.sentinel.json"
    }
  ],
  "onFailure": {
    "policy": "retry",
    "maxRetries": 2
  }
}

Field Reference

Required Fields

You must also provide either promptText or promptFile:

Optional Fields

Continuation Modes

The continuationMode field controls whether a codon starts a new conversation or picks up where the previous one left off. This is one of the most important decisions you'll make when designing a hank.

fresh — Start a New Conversation

{
  "id": "analyze-data",
  "continuationMode": "fresh",
  "model": "sonnet",
  "promptText": "Analyze the CSV files in read_only_data_source/..."
}

The agent starts with an empty conversation history. It sees only the current prompt and the state of the files. Use this for self-contained tasks, when switching models, or when the previous context would be confusing.

The first codon in any hank must use fresh.

continue-previous — Continue the Conversation

{
  "id": "refine-schema",
  "continuationMode": "continue-previous",
  "model": "sonnet",
  "promptText": "Now refine the schemas you just created to add validation..."
}

The agent continues from the previous codon's conversation, retaining the full context. Use this when the agent needs to remember its previous actions and reasoning—when the phrase "you just created" in your prompt should actually mean something.

In this flow, Codons 1 and 2 share a conversation (blue), while Codons 3 and 4 share a different conversation (orange). Codon 3 must start fresh because it switches to a different model.

The Dual ID System

Codons have two types of IDs:

1. Config ID — The ID you write in the hank.json file (e.g., "review", "codon-1").
2. Runtime ID — A generated ID used during execution to handle loops (e.g., "review#0", "review#1").

Outside of a loop, a codon's config ID and runtime ID are the same. Inside a loop, the runtime ID includes the iteration number:

This matters when reading logs (which use runtime IDs), rolling back to a specific iteration, or debugging which iteration of a loop failed.

Prompts

Inline Prompts

For short, simple prompts, use promptText:

{
  "id": "quick-fix",
  "name": "Quick Fix",
  "model": "sonnet",
  "continuationMode": "fresh",
  "promptText": "Fix the TypeScript errors in src/"
}

File-Based Prompts

For longer prompts, use promptFile. This keeps your hank.json clean and makes prompts easier to edit and version control.

{
  "id": "generate-schemas",
  "name": "Generate Schemas",
  "model": "sonnet",
  "continuationMode": "fresh",
  "promptFile": "./prompts/schema-generator.md"
}

Multiple Prompt Files

You can provide an array of files, which will be concatenated in order.

{
  "promptFile": [
    "./prompts/context.md",
    "./prompts/task.md",
    "./prompts/constraints.md"
  ]
}

This lets you compose prompts from reusable components.

Template Variables

Prompts support template variables that are replaced at runtime:

Read the CSV files in <%DATA_DIR%>/ and create Zod schemas.
Save the schemas to <%PROJECT_DIR%>/src/schema/.

Documenting Prompts with Comments

Use HTML comments to document your prompts without sending the comments to the LLM. Comments are stripped before the prompt is sent:

# Refactoring Task
 
Refactor the authentication module to use JWT tokens.
 
<!-- CONTEXT: Migrating from sessions to JWT for mobile app.
     See ENG-234 for requirements. -->
 
Preserve backward compatibility with /api/v1/\* endpoints.
 
<!-- WARNING: Don't touch OAuth flows - separate ticket (ENG-256). -->

The agent only sees:

# Refactoring Task
 
Refactor the authentication module to use JWT tokens.
 
Preserve backward compatibility with /api/v1/\* endpoints.

This keeps your prompts self-documenting for maintainers without wasting tokens on comments the agent doesn't need.

System Prompts

System prompts add context or constraints that apply to the entire codon. They are a good place for rules that the agent should follow throughout its execution.

{
  "appendSystemPromptFile": "./prompts/no-todos.md"
}

IMPORTANT: Never use TODO comments. Always implement functionality completely.

You can also use an inline system prompt with appendSystemPromptText:

{
  "appendSystemPromptText": "Always use TypeScript strict mode. Never use the 'any' type."
}

Checkpointed Files

The checkpointedFiles field tells Hankweave which files to track using glob patterns.

{
  "checkpointedFiles": ["src/schema/**/*.ts", "package.json"]
}

Checkpointed files are automatically committed to git, streamed to clients in real-time, and respect your project's .gitignore file—any matching files are automatically excluded.

Patterns use standard glob syntax:

• **/*.ts — All TypeScript files, any depth.
• src/schema/*.ts — TypeScript files directly in src/schema/.
• notes/**/* — Everything in notes/, any depth.

Environment Variables

Use the env field to set environment variables for the agent's process.

{
  "env": {
    "DEBUG": "true",
    "LOG_LEVEL": "verbose",
    "DATABASE_URL": "postgres://localhost:5432/test"
  }
}

The agent can read these like any other environment variable from its process.

Output Files

The outputFiles field lets you copy files from the execution environment to a final output directory after the codon completes.

{
  "outputFiles": [
    {
      "copy": ["src/schema/*.ts", "package.json"],
      "beforeCopy": [
        {
          "type": "command",
          "command": {
            "run": "bun run typecheck",
            "workingDirectory": "project"
          }
        }
      ]
    }
  ]
}

The copy field specifies glob patterns for files to copy. The beforeCopy field runs commands first, which is useful for builds, tests, or linting before extracting results. Output files are placed in the configured outputDirectory (default: hankweave-results/).

Failure Handling

By default, if a codon fails (e.g., the agent crashes, times out, or exits with an error), Hankweave aborts the entire hank. The onFailure field lets you configure different behaviors.

{
  "id": "risky-operation",
  "name": "Risky Operation",
  "model": "sonnet",
  "continuationMode": "fresh",
  "promptText": "Attempt to refactor the legacy module...",
  "onFailure": {
    "policy": "retry",
    "maxRetries": 3
  }
}

Failure Policies

Configuration Options

Examples

Retry with backoff (retries are immediate, but you get multiple attempts):

{
  "id": "flaky-operation",
  "onFailure": {
    "policy": "retry",
    "maxRetries": 3
  }
}

Best-effort documentation generation:

{
  "id": "generate-docs",
  "name": "Generate Docs (Optional)",
  "promptText": "Generate API documentation for the new endpoints",
  "onFailure": {
    "policy": "ignore"
  }
}

Extensions

Extensions allow a single codon to continue executing until context is exhausted. This is useful for open-ended exploration tasks where you don't know in advance how many iterations are needed.

{
  "id": "explore-codebase",
  "name": "Deep Codebase Exploration",
  "model": "sonnet",
  "continuationMode": "fresh",
  "promptText": "Explore this codebase thoroughly. Document everything interesting you find.",
  "exhaustWithPrompt": "Please continue exploring. Any more patterns or insights?"
}

The exhaustWithPrompt field specifies a follow-up prompt that is automatically sent to the agent after each completion. The codon will:

1. Run to completion normally
2. Automatically continue with the exhaustWithPrompt prompt
3. Keep iterating until the model's context window is full
4. Create checkpoints after each iteration

This is useful for tasks like:

• Comprehensive codebase exploration
• Thorough documentation generation
• Exhaustive test writing
• Deep refactoring sessions

Key behaviors:

• One codon.completed event (not one per iteration)
• One set of output files
• Sentinels fire once at true completion
• Rollback treats the entire extended codon as a single atomic unit

Common Patterns

Single-Purpose Codons

Keep codons focused on one task. Two codons that each do one thing well are better than one codon trying to do both. They are easier to debug, iterate on, and reuse.

{
  "id": "analyze",
  "name": "Analyze Data",
  "promptText": "Analyze the CSV structure and write observations to notes/observations.md"
}

{
  "id": "generate",
  "name": "Generate Schemas",
  "promptText": "Based on the observations, generate Zod schemas"
}

Context Firewalling

Use fresh mode to prevent context from one task from polluting the next.

{
  "id": "step-1",
  "continuationMode": "fresh",
  "promptText": "Generate initial schemas..."
}

{
  "id": "step-2",
  "continuationMode": "fresh", // Start fresh, no accumulated context
  "promptText": "Review and validate the schemas in src/schema/"
}

The second codon doesn't inherit any conversation history from the first; it only reads the state of the files. This ensures its behavior is reproducible and not influenced by prior conversational turns.

Context Accumulation

Use continue-previous when the agent needs a memory of its past actions.

{
  "id": "write",
  "continuationMode": "fresh",
  "promptText": "Write three poems about nature"
}

{
  "id": "pick-favorite",
  "continuationMode": "continue-previous",
  "promptText": "Pick your favorite of the three and explain why"
}

The second codon remembers what it wrote, allowing the agent to reason about its previous work without having to re-read files.

Common Mistakes

{
  "id": "first-codon",
  "continuationMode": "continue-previous" // Error: nothing to continue from
}

{
  "id": "step-1",
  "model": "sonnet",
  "continuationMode": "fresh"
}

{
  "id": "step-2",
  "model": "gemini",
  "continuationMode": "continue-previous" // Error: different model
}

{
  "promptText": "Analyze the data, generate schemas, validate them, fix errors, write tests, and generate documentation"
}

Codon vs Loop

A codon configuration can represent either a single execution or a loop, controlled by the optional type field.

If you omit the type field, it defaults to "codon". Loops are a powerful construct covered on their own page: Loops.

Next Steps

Now that you understand codons, you're ready to explore related concepts:

• Hanks — How codons are sequenced into programs
• Rigs — Deterministic setup scaffolding
• Loops — How to iterate codons
• Sentinels — Parallel observers that watch the agent
• Checkpoints — Git-based version control for agent work