Skip to main content

​
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

bun run agent:run -- --task .ai/tasks/<id>.md --workflow feature
Generate a patch from the task and repository context: 
OPENAI_API_KEY=<key> bun run agent:run -- --task .ai/tasks/<id>.md --workflow hotfix --generate
Generate a patch with Claude: 
AI_PROVIDER=claude ANTHROPIC_API_KEY=<key> bun run agent:run -- --task .ai/tasks/<id>.md --workflow hotfix --generate
Generate with project subagents (sequential): 
bun run agent:run -- --task .ai/tasks/<id>.md --workflow feature --generate --subagents .ai/agents
Generate with project subagents (parallel): 
bun run agent:run -- --task .ai/tasks/<id>.md --workflow feature --generate --subagents .ai/agents --subagent-mode parallel

​
Generate and apply patch automatically

# 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: 
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: 
---
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: 
    cp .env.example .env
# Edit .env with your API keys and preferences
  2. Environment variables: Export directly in your shell

​
OpenAI Provider (default)

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

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