Core Concepts

This guide explains how Arial works and the key concepts behind it.

What is Arial?

Arial is a lightweight Claude Code orchestrator. It runs multiple Claude Code agents in parallel, each working on a separate spec in an isolated git branch.

The key insight: instead of one agent doing everything sequentially, split the work across multiple agents running simultaneously.

Without Arial:                    With Arial:

  Agent ──────────────────►        Agent 1 ────────►
        (all work sequential)      Agent 2 ────────►    (parallel)
                                   Agent 3 ────────►

The Workflow

Arial follows a simple three-step workflow:

1. Plan

arial plan --specs ./specs

You provide a directory of spec files. Each .md file becomes a workstream:

specs/
├── auth.md      → Workstream: auth
├── api.md       → Workstream: api
└── tests.md     → Workstream: tests

Arial can optionally analyze your specs with AI to suggest improvements.

2. Run

arial run

Arial executes all workstreams in parallel:

• Each workstream gets its own git worktree
• A Claude Code agent works in each worktree
• Progress is shown in a TUI dashboard

3. Merge

When workstreams complete, Arial automatically merges their branches back to your base branch.

Workstreams

A workstream is a unit of parallel work. It consists of:

Workstream Lifecycle

pending ──► running ──► done
                 │
                 └──► failed
                 │
                 └──► paused (on interrupt)

• pending: Ready to run, waiting to start
• running: Claude Code agent is working
• paused: Interrupted by user (Ctrl+C), can resume
• done: Completed successfully, branch merged
• failed: Agent encountered an error

Git Worktrees

Arial uses git worktrees to isolate each workstream:

repo/                              ← Main working tree
├── .git/                          ← Shared git database
├── src/
└── .arial/
    ├── state.json                 ← Run state
    └── workspaces/
        ├── auth/                  ← Worktree for "auth" workstream
        │   ├── src/               ← Full copy of working files
        │   └── ...
        └── api/                   ← Worktree for "api" workstream
            └── ...

Why Worktrees?

• Isolation: Each agent works in its own directory
• Parallel-safe: No file conflicts between workstreams
• Lightweight: Shares git history (no full clone per workstream)
• Clean merges: Each workstream has its own branch

Branch Strategy

Each workstream creates a branch from your current branch:

main ────────────────────────────────► main (with merged changes)
  │
  ├── arial/auth ────► (work) ────────┘
  │                                   │
  └── arial/api ─────► (work) ────────┘

Specs

A spec is a markdown file describing what you want an agent to build. Good specs include:

Structure

# Title

## Goal
What you want to achieve.

## Requirements
- Specific requirement 1
- Specific requirement 2
- ...

## Technical Notes
- Any constraints or preferences
- Libraries to use
- Patterns to follow

Tips for Good Specs

1. Be specific: Vague specs lead to unexpected results
2. Include context: Reference existing code patterns
3. List requirements: Concrete, verifiable items
4. One concern per spec: Each spec = one workstream

Examples

Good spec:

# Add User Authentication

## Goal
Add JWT-based authentication with login and registration endpoints.

## Requirements
- POST /auth/register with email, password, name
- POST /auth/login returning JWT token
- Password hashing with bcrypt
- Token expiry of 24 hours

## Technical Notes
- Use jsonwebtoken package
- Follow existing controller patterns in src/controllers/

Too vague:

# Auth

Add authentication to the app.

State Management

Arial stores all state in a single JSON file:

.arial/state.json

The state includes:

• Current run status
• Base branch
• Specs directory path
• All workstreams with their status

State Persistence

• State is saved after each workstream status change
• On interrupt (Ctrl+C), state is saved with workstreams marked as paused
• Run arial run to resume from saved state

TUI Dashboard

When you run arial run, you see a live dashboard:

Arial Status
────────────────────────────────────

Base branch: main
Status: running

Progress: 1 done, 1 running, 1 pending (3 total)

Workstreams:

✓ auth - Add User Authentication
  Implement JWT-based authentication.
  Completed in 2m 15s

● api - Build REST API
  Create user management endpoints.
  Running for 1m 30s

○ tests - Add Integration Tests
  Write tests for auth and API.

Status Icons

Key Principles

1. One Spec = One Workstream

Each markdown file becomes one workstream. Keep specs focused:

• One feature per spec
• One area of the codebase per spec

2. Parallel by Default

All workstreams run simultaneously. Arial doesn't manage dependencies between workstreams—that's your job when writing specs.

3. Git Isolation

Each workstream works in its own branch. This means:

• No conflicts during execution
• Clean history per feature
• Easy to review changes

4. Auto-merge

When workstreams complete, they auto-merge to your base branch. If you want to review first, check the branches before they merge.

Observability

Status Command

Check status anytime:

arial status
arial status --json

Verbose Mode

See all agent output:

arial run --verbose

Axiom Integration

For production observability, Arial integrates with Axiom to send structured events:

export AXIOM_TOKEN=xaat-...
export AXIOM_DATASET=arial
arial run

Events include run lifecycle, workstream progress, merge operations, and timing metrics. See the Axiom Observability guide for complete setup and query examples.

Next Steps

• Follow the Getting Started guide to run your first workstreams
• See Workflow Examples for real-world scenarios
• Check the Command Reference for all options