# Getting started

yaag runs Orchestration Programs: TypeScript modules that drive pi Agents.
Start a Run from the `yaag` CLI, or from a pi session with the yaag extension.

## Install

Install the extension into a pi session:

- `pi install @yaag/extension` adds it permanently.
- `pi -e @yaag/extension` loads it for one session.

yaag needs Bun on `PATH`. Install it with
`curl -fsSL https://bun.sh/install | bash`. If the extension reports that Bun is
missing, read [Bun is missing](troubleshooting.md#bun-is-missing).

## Prepare the workspace

Run the `yaag_setup_workspace` tool, or `yaag setup-workspace .` on the command
line. It creates `.yaag/` in the workspace root. `.yaag/types/` holds the
`@yaag/runtime` declarations that an editor needs. A folder with `.yaag/` is a
Program Directory, and the extension tells the model about it.

## Write and run the first program

Copy [`examples/01-minimal.ts`](examples/01-minimal.ts) into the Program
Directory:

<!-- embed: docs/examples/01-minimal.ts -->

```ts
import { defineRun, prompt } from "@yaag/runtime";

export default defineRun({
  name: "minimal",
  description: "Asks one Agent for one short answer.",
  async run(ctx) {
    const agent = await ctx.spawn({ name: "writer" });
    return await agent.ask(prompt`Write one sentence about the sea. Report only that sentence.`);
  },
});
```

Then run `yaag run 01-minimal.ts`, or ask the model to use the `yaag_run` tool.
`yaag describe 01-minimal.ts` reports the name, the description, and the
argument schema of the program.

A program can declare Profiles, so one `--profile` flag moves every Agent of
the Run to another model vendor — read [Profiles](authoring.md#profiles).

## Next

- [Authoring](authoring.md) — how to write a program.
- [Examples](examples.md) — twelve programs, from minimal to Groups.
- [CLI reference](cli.md) — every flag and every tool parameter.
- [The /yaag menu](cli.md#the-yaag-menu) — Runs, Status, and Settings in one command.
- [Configuration](configuration.md#locations) — the three config files a Run reads.
- [Troubleshooting](troubleshooting.md) — the errors you can meet.