> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobile-starter.amisi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Runner

> Run planner, implementer, reviewer, and release stages locally

# Agent runner

`apps/agent-runner` orchestrates staged subagent roles for feature, hotfix, and release workflows.

## Stages

1. Planner
2. Implementer
3. Reviewer
4. Release

## Run

```sh theme={null}
bun run agent:run -- --task .ai/tasks/<id>.md --workflow feature
```

Generate a patch from the task and repository context:

```sh theme={null}
OPENAI_API_KEY=<key> bun run agent:run -- --task .ai/tasks/<id>.md --workflow hotfix --generate
```

Generate a patch with Claude:

```sh theme={null}
AI_PROVIDER=claude ANTHROPIC_API_KEY=<key> bun run agent:run -- --task .ai/tasks/<id>.md --workflow hotfix --generate
```

Generate with project subagents (sequential):

```sh theme={null}
bun run agent:run -- --task .ai/tasks/<id>.md --workflow feature --generate --subagents .ai/agents
```

Generate with project subagents (parallel):

```sh theme={null}
bun run agent:run -- --task .ai/tasks/<id>.md --workflow feature --generate --subagents .ai/agents --subagent-mode parallel
```

### Generate and apply patch automatically

```bash theme={null}
# Using .env file (recommended)
bun run agent:run -- --task .ai/tasks/templates/feature.md --workflow feature --auto

# Or with environment variables
AI_PROVIDER=claude ANTHROPIC_API_KEY=<key> \
bun run agent:run -- --task .ai/tasks/templates/feature.md --workflow feature --auto
```

Generate and apply automatically:

```sh theme={null}
OPENAI_API_KEY=<key> bun run agent:run -- --task .ai/tasks/<id>.md --workflow hotfix --auto
```

`--auto` enables both `--generate` and `--apply`.

## Subagents

Subagents are opt-in and loaded from markdown files.

### CLI flags

* `--subagents <path>`: directory, file, or glob for subagent markdown files
* `--subagent-mode <sequential|parallel>`: execution mode (default: `sequential`)

`--subagents` requires `--generate` or `--auto`.

### Subagent file format

Create files under `.ai/agents/*.md`:

```md theme={null}
---
name: planner
description: Plan code changes and constraints
provider: openai
model: gpt-4.1-mini
tools:
  - Read
  - Grep
maxTurns: 1
---

Generate a concise implementation plan for this task before coding.
```

Supported frontmatter fields:

* `name` (required)
* `description` (required)
* `provider` (`openai` or `claude`, optional)
* `model` (optional)
* `tools` (optional)
* `maxTurns` (optional)

Prompt source:

* Uses markdown body if present
* Falls back to `prompt` frontmatter if body is empty

## Configuration

The agent-runner requires environment variables for AI code generation. You can set these via:

1. **`.env` file** (recommended): Copy `.env.example` to `.env` and configure:

   ```bash theme={null}
   cp .env.example .env
   # Edit .env with your API keys and preferences
   ```

2. **Environment variables**: Export directly in your shell

### OpenAI Provider (default)

```bash theme={null}
AI_PROVIDER=openai  # optional, defaults to openai
OPENAI_API_KEY=your-api-key-here
OPENAI_MODEL=gpt-4.1-mini  # optional, defaults to gpt-4.1-mini
OPENAI_BASE_URL=https://api.openai.com/v1  # optional
```

### Claude Provider

```bash theme={null}
AI_PROVIDER=claude
ANTHROPIC_API_KEY=your-api-key-here
# Alternative key names also supported:
# CLAUDE_API_KEY=your-api-key-here
# CLOUDE_API_KEY=your-api-key-here
ANTHROPIC_MODEL=claude-3-5-sonnet-latest  # optional
ANTHROPIC_BASE_URL=https://api.anthropic.com/v1  # optional
```

## Supported workflows

* `feature`
* `hotfix`
* `release`
* `bugfix` alias to `hotfix`

## Artifacts

Workflow artifacts are saved to:

`/.ai/tasks/artifacts/<task-id>/`

Expected outputs:

* `plan.md`
* `implementer.md`
* `implementer.patch`
* `review.md`
* `release.md`
* `subagents/*.prompt.md` (when `--subagents` is enabled)
* `subagents/*.patch` (when `--subagents` is enabled)

## Notes

* Patch apply is opt-in through `--apply` or `--auto`
* Verification runs through canonical `bun run verify`