Heimdall

About Heimdall

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Heimdall is a CLI for building deterministic agentic workflows from YAML. User-defined workflows describe the phases, gates, feedback loops, artifacts, and completion criteria that guide agentic work. Agents provide the intelligence; Heimdall owns the structure.

Each run executes in an isolated git worktree, so teams can run fixes and implementation tasks in parallel without mixing changes.

The problem

AI agents are powerful, but the process around them is often implicit:

Getting started

Mon, 01 Jan 0001 00:00:00 +0000

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

info

This YAML is illustrative. The workflow schema will be documented when the engine stabilizes.

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.

Workflow examples

Mon, 01 Jan 0001 00:00:00 +0000

The examples below are invented previews of how Heimdall workflows might look. They are not wired to a live engine yet — they demonstrate structure, gates, and code blocks in the docs theme.

Collect user input to file

A simple workflow that prompts for content and writes it to a file:

 name: collect-user-input
description: Prompt for text and save it to a file in the worktree.

phases:
 - id: prompt
 agent: input-collector
 prompt: |
 Ask the user what they want to save, then write the response
 to `output/user-notes.md` in the worktree.

 - id: verify
 gate: file-exists
 path: output/user-notes.md

Run it (preview):

Heimdall

About Heimdall

Overview link

The problem link

Getting started

Prerequisites link

Install (preview) link

Initialize a workflow link

Run a workflow link

Workflow examples

Collect user input to file link

Overview

The problem

Prerequisites

Install (preview)

Initialize a workflow

Run a workflow

Collect user input to file