WA: WezTerm Automata

Goal

Coordinate multiple AI coding agents running in WezTerm with real-time observation and automation.

What Is WA?

WezTerm Automata (WA) is a terminal hypervisor that captures pane output in real-time, detects agent state transitions through pattern matching, and enables event-driven automation.

When running multiple AI agents, you need to know when they hit rate limits, complete tasks, or need approval. WA observes all panes with sub-50ms latency and can trigger automated responses.

Real-time Observation

Sub-50ms pane monitoring

Pattern Detection

Recognizes agent state changes

Full-Text Search

FTS5 with BM25 ranking

Safety Engine

Capability gates & audit trails

How It Works

WA runs as a daemon that observes all WezTerm panes, detects patterns, and exposes a Robot Mode API for agent integration.

WA Observatory

Single Agent Working

One agent actively coding in pane #42

1/6

pane #42 -- claude-code

$ claude --project api-server

Reading src/routes/users.ts...

Analyzing authentication flow...

Writing src/middleware/auth.ts

+ export function validateToken()

35%

pane #43 -- idle

$ _

pane #44 -- idle

$ _

pane #45 -- idle

$ _

File Activity

src/routes/users.ts

#42

src/middleware/auth.ts

#42

src/types/auth.d.ts

#42

wa monitor

$ wa robot state | jq ".panes[] | {id,status}"

{"id": 42, "status": "active"}

{"id": 43, "status": "idle"}

{"id": 44, "status": "idle"}

{"id": 45, "status": "idle"}

Observation Flow

# WA observes terminal panes
Agent types: "Thinking..."
         ↓
# Pattern detection engine
         ↓
Agent completes: "Done!"
         ↓
# Event triggers automation
         ↓
WA notifies other agents via mail

Pro Tip

WA uses delta extraction instead of full buffer snapshots for minimal overhead.

Quick Start

Get started with these essential commands.

Start the observation daemon

Check daemon status

View all panes as JSON

Search captured output

Warning

WA requires WezTerm to be running. It won't work with other terminal emulators.

Robot Mode API

Robot Mode provides a JSON API for machine-to-machine communication.

Get all pane states as JSON

Get pane output

Send input to pane

Wait for pattern

Robot Mode Example

# Example: Wait for agent completion
wa robot wait-for 42 "Task complete"
# Then trigger next action
wa robot send 43 "Start next task"

Pattern Detection

WA detects state transitions for common AI agents.

Claude Code

Rate limits, approvals, completions

Codex CLI

Task completion, errors, waiting

Gemini CLI

Response completion, quota warnings

Custom Patterns

Define your own detection rules

Tool Integration

WA integrates seamlessly with other flywheel tools.

WA + NTM

WA automatically observes agents spawned by NTM. Use NTM to spawn agents and WA to monitor their state.

WA + Agent Mail

State changes detected by WA can trigger Agent Mail notifications. Coordinate agent handoffs through mail threads.

WA + Beads

When WA detects task completion, it can update bead status. Track agent progress through your issue tracker.

Diagnostics

Troubleshoot issues with built-in diagnostics.

Run diagnostic checks

Check daemon health

View recent logs

Note

Run wa doctor if pattern detection isn't working. It checks WezTerm connectivity and daemon status.

New to ACFS?

What Is WA?

Real-time Observation

Pattern Detection

Full-Text Search

Safety Engine

How It Works

Quick Start

Robot Mode API

Pattern Detection

Tool Integration

WA + NTM

WA + Agent Mail

WA + Beads

Diagnostics

Ready to level up?