Prerequisites

When the CLI ships, you will need:

  • Node.js 22 or later
  • Git with worktree support
  • A repository where agents will make changes

Install (preview)

Installation instructions are not finalized. The intended experience will look like:

  npm install -g heimdall
heimdall --version

Initialize a workflow

Create a workflows/ directory in your repository and add a workflow definition:

  # workflows/fix-issue/workflow.yaml
name: fix-issue
description: Triage, implement, validate, and open a PR for an issue.

phases:
  - id: plan
    agent: spec-planner
    gate: plan-approved

  - id: implement
    agent: ts-engineer
    artifacts:
      - src/**

  - id: validate
    command: npm run quality
    on_failure: implement

  - id: review
    agent: ts-code-reviewer
    on_failure: implement

  - id: publish
    command: heimdall pr create

Run a workflow 

  # Run against the current repo; Heimdall creates an isolated worktree
heimdall workflow run fix-issue --issue 42

# Inspect run status
heimdall workflow status --run-id wf_01HXYZ

Each run gets its own git worktree under .heimdall/worktrees/, keeping parallel agent tasks isolated.

Configuration

Shared config will load from defaults, a config file, environment variables, and CLI flags (highest precedence last):

  # .heimdallrc.toml (example)
default_branch = "main"
worktree_root = ".heimdall/worktrees"
verbose = false
  
  export HEIMDALL_VERBOSE=true
heimdall workflow run fix-issue --verbose

Next steps