Getting Started with Arial

This guide walks you through running your first parallel AI workstreams with Arial.

Prerequisites

• Node.js 18+
• Git
• A git repository to work with

Step 1: Install Arial

npm install -g arial

Verify the installation:

arial --version

Step 2: Authenticate

Arial needs authentication to run Claude agents. Choose one method:

Option A: Local credentials (recommended)

claude login

This opens a browser for OAuth authentication.

Option B: API key

export ANTHROPIC_API_KEY=sk-ant-your-key-here

Get your key from console.anthropic.com.

See the Authentication guide for more details.

Step 3: Initialize Arial

Navigate to your git repository and run:

cd /path/to/your/repo
arial init

You'll see:

Initialized Arial

Next steps:
  1. Create a specs directory with markdown files describing your work
     mkdir specs
     echo "# Build auth system" > specs/auth.md

  2. Plan the workstreams:
     arial plan --specs ./specs

  3. Run all workstreams:
     arial run

This creates a .arial/ directory for state and workspace management.

Step 4: Create Spec Files

Create a specs/ directory with markdown files. Each file becomes a workstream:

mkdir specs

Create specs/auth.md:

# Add User Authentication

## Goal
Implement JWT-based authentication for the API.

## Requirements
- POST /auth/register - Create new user account
- POST /auth/login - Authenticate and return JWT token
- Auth middleware to protect routes
- Password hashing with bcrypt

## Technical Notes
- Use jsonwebtoken package
- Token expiry: 24 hours
- Follow existing error handling patterns

Create specs/api.md:

# Build User API

## Goal
Create REST endpoints for user management.

## Requirements
- GET /users - List all users
- GET /users/:id - Get user by ID
- PUT /users/:id - Update user
- DELETE /users/:id - Delete user

## Technical Notes
- Follow existing controller patterns
- Add input validation
- Include proper error responses

Step 5: Plan Workstreams

Create workstreams from your specs:

arial plan --specs ./specs

Arial will:

1. Read all markdown files in the specs directory
2. Optionally analyze them with AI to suggest improvements
3. Create workstreams for each spec

You'll see a summary:

Loading specs...
Found 2 spec file(s)

Workstreams (2):

  auth
    Add User Authentication
    Implement JWT-based authentication for the API.

  api
    Build User API
    Create REST endpoints for user management.

Create these workstreams? [y/N] y

Created 2 workstream(s)

Next steps:
  Run all workstreams:
    arial run

  Or view status:
    arial status

Step 6: Run Workstreams

Execute all workstreams in parallel:

arial run

Arial will:

1. Create a git worktree for each workstream
2. Run a Claude Code agent in each worktree
3. Show live progress in a TUI dashboard
4. Auto-merge completed branches to your base branch

The TUI shows status for each workstream:

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

Base branch: main
Status: running

Progress: 1 running, 1 pending (2 total)

Workstreams:

● auth - Add User Authentication
  Implement JWT-based authentication for the API.
  Running for 45s

○ api - Build User API
  Create REST endpoints for user management.

Press Ctrl+C to pause. Run arial run again to resume.

Step 7: Check Status

View the current state anytime:

arial status

For JSON output (useful for scripting):

arial status --json

Run Options

Verbose Mode

See all agent output in real-time:

arial run --verbose

Console Mode

Disable TUI and output to console:

arial run --no-tui

What Happens After Completion

When all workstreams complete:

1. Each workstream's branch merges to your base branch
2. Worktrees are cleaned up
3. You see a summary of results

If any workstream fails, you'll see the error. Check arial status for details.

Quick Reference

Next Steps

• Read the command reference for all options
• See workflow examples for real-world scenarios
• Check troubleshooting if you run into issues