Raxol

Raxol Skill

Elixir TEA framework for terminal UIs + AI agent orchestration. The same TEA model runs in the terminal, browser (LiveView), SSH, and as MCP tools/resources. OTP provides supervision, crash isolation, and hot reload.

Raxol v2.6.1 targets Elixir 1.20 / OTP 29 and supports 1.17+. The repo holds 18 Mix projects: 17 under packages/ plus the root raxol package. Both numbers are correct and they count different things, so a packages/ listing showing 17 is not stale.

The terminal emulator + termbox2 NIF were extracted from the root raxol package into raxol_terminal. raxol is now the full-framework package, and it is a plain Mix project rather than a Mix umbrella (the root mix.exs has no apps_path): it depends on raxol_core, raxol_terminal, raxol_sensor, raxol_mcp, raxol_liveview, and raxol_plugin. The 15 packages this skill covers:

• raxol_core -- TEA runtime, buffer/rendering, events, directives, telemetry
• raxol -- full-framework package at the REPO ROOT, not under packages/ (depends on core, terminal, sensor, mcp, liveview, plugin)
• raxol_terminal -- VT/ANSI emulator, screen buffers, driver, input, sessions, termbox2 NIF (extracted from raxol in v2.6)
• raxol_agent -- agent framework: TEA/Process agents, turn driver, memory, self-improving skills, journal, backends, coding harness, teams
• raxol_mcp -- MCP server/client: tool auto-derivation, focus lens, resources
• raxol_liveview -- Phoenix LiveView bridge (buffer -> HTML, a11y)
• raxol_plugin -- plugin SDK (mix raxol.gen.plugin)
• raxol_sensor -- sensor fusion for Process agents
• raxol_gateway -- unified messaging gateway: one daemon, many chat platforms via a shared adapter contract, process-per-chat sessions, DM pairing auth
• raxol_speech -- speech surface: TTS reads a11y announcements, STT captures voice input via Bumblebee/Whisper and injects events
• raxol_telegram -- Telegram surface: renders TEA apps as monospace code blocks with inline-keyboard navigation
• raxol_watch -- Watch notification bridge: glanceable summaries to Apple Watch (APNS) and Wear OS (FCM); tap actions route back as events
• raxol_agent_client_protocol -- Elixir/OTP implementation of ACP (Agent CLIENT Protocol): JSON-RPC 2.0 between editors and coding agents, pluggable transports
• raxol_cli -- the raxol command: interactive AI agent + toolkit as a self-contained binary via npm wrapper
• raxol_console -- console runtime: boots an ACP Console agent package onto the gateway stack

Payments / the Agent COMMERCE Protocol (raxol_payments, raxol_earn) and the Symphony orchestrator (raxol_symphony) have their own skills -- see below. Do not confuse raxol_earn (Agent Commerce Protocol, payments) with raxol_agent_client_protocol (Agent Client Protocol, in scope here).

What You Get

• TEA agent and Process agent patterns with lifecycle examples
• Turn driver + memory stack + self-improving skills (v2.6)
• Workflow engine: graph DSL, checkpointing, human-in-the-loop, saga rollback
• AI backends (HTTP, Mock, native ClaudeCode/Cursor, OpenRouter) + harness selection
• MCP server (auto-derive tools from the widget tree) and MCP client
• LiveView surface (buffer -> HTML, themes, accessibility)
• Multi-agent orchestration (teams, cockpit, message protocol)
• Agent skills / procedural memory + the journal (blast radius, spend gate)
• Coding agent harness (mix raxol.code, mix raxol.p) with tool classification
• Chat surfaces via the gateway (Telegram, Discord, email) + speech (TTS/STT)
• Agent Client Protocol: editor <-> agent JSON-RPC (distinct from ACP payments)
• Headless sessions and agent testing patterns (unit, integration, E2E)

Two Agent Models

For a full LLM chat turn (memory + skills + user model + tool loop) use the Raxol.Agent.Turn driver -- see agents/turn-memory.md.

See also

• raxol-payments -- agentic commerce: Xochi/Riddler/ACP, agent wallets, privacy tiers
• raxol-symphony -- tracker-driven coding-agent orchestrator (Symphony)
• droo-stack -- general Elixir patterns (pipes, pattern matching, ExUnit)
• design-ux -- TUI design principles (terminal layout, box-drawing, density)
• claude-api -- Anthropic SDK integration in Elixir

Reading Guide

Message Protocol

All TEA agents receive these in update/2. Defined once here, referenced from other files.

# Async message from another agent
{:agent_message, from_id, payload}

# Sync call -- MUST reply with send(pid, {:agent_reply, ref, reply})
{:call, caller_pid, ref, message}

# Team broadcast
{:team_broadcast, team_id, payload}

# Async command / directive results
{:command_result, result}
{:command_result, {:shell_result, %{output: string, exit_status: int}}}
{:command_result, {:action_result, module, result_map}}
{:command_result, {:action_error, module, reason}}
{:command_result, {:pipeline_result, result_map}}
{:command_result, {:pipeline_error, step_module, reason}}

Key Conventions

• All agents auto-register in Raxol.Agent.Registry by :id
• Always return {model, command} from update/2, never bare model
• view/1 returning nil = headless (no rendering overhead)
• Effects are struct-based Directives (v2.6): Raxol.Core.Runtime.Directive (stop/1, schedule/2, spawn_task/1) and Raxol.Agent.Directive (async/1, shell/2, send_agent/2). The use Raxol.Agent helpers wrap these.
• Session agents register as agent_id, Process agents as {:process, agent_id}, MCP clients as {:mcp_client, name}
• Agent package: packages/raxol_agent/

Common Pitfalls

1. Wrong update/2 return -- must return {model, Command.none()} not bare model
2. Forgetting call reply -- {:call, pid, ref, msg} requires send(pid, {:agent_reply, ref, reply}); caller blocks with timeout
3. Mixing agent models -- TEA callbacks and ProcessBehaviour callbacks are separate behaviours
4. Sync call deadlocks -- Agent A calls B, B calls A = deadlock. Break cycles with async send_agent/2
5. String vs atom keys -- Headless send_key uses atoms for special keys (:tab), strings for characters ("q")
6. Real backends in tests -- always use Backend.Mock, never HTTP

Design Context

Raxol treats each rendering surface (terminal, web, SSH, MCP) as a functor from the TEA model. Same update/2, same model, different projections. In v2.6 MCP is a first-class surface (raxol_mcp): widgets auto-export tools via the Raxol.MCP.ToolProvider behaviour, model state is exposed via ResourceProvider, and FocusLens filters tools by attention. When building features, consider how they surface as MCP tools -- see mcp/server.md.