Use a tree

Every published abtree workflow installs and runs the same way. This page is the canonical reference — individual tree READMEs link here instead of duplicating it.

Prerequisites

Install these on your PATH:

• abtree CLI — see Get started for one-liner installers (macOS, Linux, Windows).
• An agent. abtree is agent-agnostic. Examples on this site use Claude Code, but any LLM agent that runs shell commands works.
• A node package manager — Bun, pnpm, or npm.

Install the abtree skill

The skill is the prompt template that teaches your agent how to drive an abtree execution. If you kick off a workflow and the agent does not seem to know what to do, the skill is missing:

abtree install skill

You only do this once per agent setup, not per tree.

Install the tree

Choose one of two options. Either way, the tree lands as a node package — abtree finds it by path or by slug at execution time.

Option A — per-repo (recommended)

In the repository you want to run the workflow against:

bun

bun add --dev <pkg>

pnpm

pnpm add -D <pkg>

npm

npm install --save-dev <pkg>

The tree lands at ./node_modules/<pkg>/. It is a dev-time tool — nothing ships in your runtime bundle.

Option B — global

Install once, run from any repository:

bun

bun add -g <pkg>

pnpm

pnpm add -g <pkg>

npm

npm install -g <pkg>

The tree lands at $(npm root -g)/<pkg>/ (use pnpm root -g or bun pm -g bin for those managers).

Pin a version

Pin an npm version for byte-stable resolution across machines:

bun add <pkg>@1.2.0

For full reproducibility, commit your lockfile (package-lock.json, pnpm-lock.yaml, or bun.lock).

Install from sources other than npm

If you consume a tree that is not published to npm (a private fork, an unpublished prototype, a local tarball), every supported package manager already documents Git, local-path, tarball, and URL forms — see the manager's add/install reference: npm install, pnpm add, bun add.

Run the workflow

Hand a brief to your agent. The exact phrasing does not matter — the agent reads the skill, calls abtree --help, and figures out the protocol from there:

# Option A — per-repo install
claude 'Using the abtree cli, run the tree ./node_modules/<pkg>'

# Option B — global install
claude "Using the abtree cli, run the tree $(npm root -g)/<pkg>"

The agent walks the tree and persists state to a new .abtree/ directory at the repo root. Gitignore it, or commit it if you want shareable run history.

What gets written

Every execution writes the same three artefacts under .abtree/executions/:

Path	Purpose
.abtree/executions/<id>.json	Full execution document — input, output, every state mutation.
.abtree/executions/<id>.mermaid	Live Mermaid diagram of the run, regenerated on every state change.
.abtree/executions/<id>.svg	Live SVG diagram of the run, same trigger.

Individual trees also write workflow-specific files (reports, plans, and so on) — see the tree's own README.

Reference

• Concepts — what behaviour trees are and why.
• Writing trees — author your own.
• Design a new tree — ten-step design process.
• Idioms — reusable shapes for production workflows.
• Fragments — split a large tree across files.
• Inspecting executions — debug a stuck or failed run.
• Execution protocol — what the agent does at each step.
• CLI reference — every command, every flag.

Next

• Writing trees — build the bundled hello-world tree from scratch.