ashlar-ao 1.0.0

Local-first agent orchestration platform — one developer, many AI coding agents, single command center.

Ashlar AO

A local-first agent orchestration platform. Manage multiple AI coding agents (Claude Code, Codex, etc.) across projects from a single browser-based command center.

Spawn agents, monitor their status in real time, approve plans, respond to questions, and coordinate work — all without switching terminals.

Installation

pip install ashlar-ao

Then run:

ashlar

Prerequisites

• Python 3.11+
• tmux — used for agent process isolation and output capture
• At least one agent backend CLI:
  • Claude Code: npm i -g @anthropic-ai/claude-code
  • Codex: npm i -g @openai/codex

If no backend is installed, agents run in demo mode.

Install tmux

# macOS
brew install tmux

# Linux
sudo apt install tmux

Quick Start (from source)

./start.sh

The launch script handles everything: checks dependencies, creates a Python virtual environment, installs the package in editable mode, and starts the server.

Open http://127.0.0.1:5111 in your browser.

Port Conflicts

Port 5000 conflicts with macOS AirPlay Receiver. Ashlar defaults to port 5111 to avoid this. To use a different port:

ASHLAR_PORT=8080 ashlar

Configuration

Config lives at ~/.ashlar/ashlar.yaml (auto-created on first run). Defaults work out of the box.

Optional Environment Variables

Variable	Purpose
ASHLAR_PORT	Override server port (default: 5111)
XAI_API_KEY	Enable LLM-powered agent summaries via xAI Grok

Architecture

Two files make up the core application, packaged as ashlar_ao:

• ashlar_ao/server.py — Python aiohttp server. Manages agents via tmux, serves the dashboard, provides REST + WebSocket APIs, collects system metrics.
• ashlar_ao/dashboard.html — Single HTML file with all CSS and JS inline. No build step, no bundler, no node_modules.

Data is persisted in SQLite at ~/.ashlar/ashlar.db.

Usage

• Spawn agents from the dashboard or command palette (Cmd+K)
• Monitor status via live-updating cards (planning, working, waiting, error)
• Respond to agents inline when they need input
• Push-to-talk with Space for voice commands
• Keyboard shortcuts: Cmd+N new agent, 1-9 focus agent, Cmd+Shift+A approve

Development

git clone https://github.com/masonwyatt/ashlar-ao.git
cd ashlar-ao
pip install -e ".[dev]"
pytest

See CLAUDE.md for full architecture, data models, API reference, and implementation details.