ash

Getting Started with Ash

By Ash Team ·

Getting Started with Ash

Ash is an open-source task orchestration language for AI coding agents. Whether you are running a single prompt or a multi-step pipeline across different models, Ash gives you a simple, composable way to define and execute agent workflows from the command line.

Installation

npm install -g ash-lang

Verify it works:

ash --version
ash discover

ash discover auto-detects installed agents on your system and generates sensible defaults. Run it whenever you add a new agent.

Why Ash?

Modern AI coding tools are powerful, but stitching them together into repeatable workflows is painful. You end up writing shell scripts, chaining commands with &&, or building bespoke orchestrators. Ash replaces all of that with a minimal language designed for exactly this problem.

What you get:

  • Agent-agnostic. Swap between opencode, claude-code, aider, codex, gemini-cli, and kimi with a single --agent flag.
  • Plain-text tasks. Drop numbered .md files in a folder. That is your workflow.
  • Full scripting when you need it. Use .ash files for loops, retries, conditionals, functions, and shell integration.
  • State passing between steps. Each task output is available to the next step via stdout and stderr.

Your First Workflow

Create a folder and add numbered task files:

my-workflow/
├── 01-research.md
├── 02-implement.md
└── 03-review.md

Each .md file is a prompt that gets sent to the agent. They run in sorted order, and the output of each step is captured for the next one.

01-research.md:

Research how to add dark mode to a React app using CSS variables.
List the key files that need to change and the CSS custom properties to use.

02-implement.md:

Based on the research from the previous step, implement dark mode toggle
in the React app. Use a ThemeContext and CSS variables.

03-review.md:

Review the dark mode implementation. Check for:
- All components respect the theme
- No hardcoded colors remain
- The toggle persists across page reloads

Then run:

ash --agent opencode my-workflow/

Ash will execute each task in order, passing context between steps. That is it.

When to use .ash files

Markdown tasks work great for linear agent prompts. But sometimes you need more control. Drop in a .ash file when you need:

  • Retry logic with exponential backoff
  • Conditional branching based on previous output
  • Loops to iterate over multiple items
  • Shell commands mixed with agent calls
  • Reusable functions shared across workflows

Example 03-review.ash replacing the markdown review step:

#!opencode:1.0

do "Review the dark mode implementation from the previous step. Focus on correctness and edge cases."

if $? != 0 {
  print "Review found issues. kicking off fix..."
  do "Fix all issues identified in the review: ${stdout}"
}

What is next?

Happy orchestrating.