ash

Getting Started

Installation

npm install -g ash-lang

Verify it's installed:

ash discover

Built-in support: opencode, claude-code, aider, codex, gemini-cli, kimi, and more. See supported agents for the full list and default configs.

Use --agent to specify which agent to run with:

ash --agent opencode ./tasks

The tasks/ folder contains numbered .md files — each file is one task sent to the agent, executed in sorted order. Drop in an .ash file when you need loops, retries, or conditionals. See How Ash Works for the expected folder layout.

If you add a new agent after ash was already installed, run:

ash discover

Any CLI-based agent can be configured manually via ash.yml:

agents:
  my-tool:
    type: local-cli
    cmd: my-tool
    message_flag: "--prompt"
    yes_flag: "--yes"

How Ash Works

Drop markdown files in a folder, number them, and run. Each file is a task sent to an AI agent. Output flows between steps.

tasks/

Step 1: Create a folder of tasks 
tasks/
├── 01-research.md
├── 02-implement.md
├── 03-review.ash
└── 04-deploy.md

Terminal

Step 2: Run — agents execute each task in order
$ ash --agent opencode tasks/
[1/4] 01-research.md → opencode sonnet-4
[2/4] 02-implement.md → claude-code claude-sonnet-4
[3/4] 03-review.ash (shebang: codex)
[4/4] 04-deploy.md → opencode haiku-flash
4 tasks, 4 passed

When You Need Full Orchestration

Markdown tasks handle simple agent calls. Drop in an .ash file when a single prompt isn't enough — variables, conditionals, shell commands within one step. Standalone scripts give you the full language: loops, retry, parallelism, functions. Same runtime, same state passing. Just add power as you need it.

Variables, Strings & Shell

MSG = "hello"
ITEMS = ["a", "b", "c"]
FIRST = ITEMS[0]
print "count: ${len(ITEMS)}"
working_dir = $(pwd)

Agent Calls

do "Review this code" with opencode

try {
  do "Fix the bug" with fixer
} fail {
  do "Retry: ${stderr}"
} upto 3

Control Flow

for FILE in FILES {
  do "Review ${FILE}"
  if $? != 0 { exit 1 }
}

exec npm test
if $? == 0 {
  print "all good"
}

Functions & Composition

fn review(path) {
  do "Review ${path}" with opencode
}

include "helpers.ash"
review("src/main.rs")

For .ash scripts, declare the agent with a shebang:

#!opencode:1.0

do "Review src/" with opencode

For .md tasks, optionally set the agent in YAML frontmatter:

---
agent: opencode
model: sonnet
---

# Task Title

The prompt content goes here...