Raxol

Recursively, axol. Forever FOSS.

CIHex

Write one app. Render it to a terminal, a browser, an SSH session, or an agent.

Your application is a single TEA module (init, update, view) running as an OTP GenServer. Raxol renders that module to four surfaces from one codebase:

                          +---> Terminal (termbox2 NIF)

                          |

  TEA module (GenServer) -+---> Browser (Phoenix LiveView)

                          |

                          +---> SSH (Erlang :ssh)

                          |

                          +---> Agent (MCP tools)

The interesting part is the runtime. Your app gets crash isolation per Component, hot code reload without restart, distributed clustering with CRDTs, and an agent surface where LLMs interact with structured Component trees instead of scraping pixels. Those are BEAM properties, from a VM built for systems that can't go down, can't lose state, and hot-swap code while running.

Bubble Tea, Ratatui, and Textual are excellent renderers. A2UI and AG-UI define agent-UI wire formats. Raxol is the runtime that renders all four surfaces from one source module. See Why OTP for the framework comparison, and Why Raxol for how the runtime compares to Python agent stacks like Hermes and Omnigent.

Agents

Raxol is a runtime for agents as much as for humans. Every interactive Component automatically exposes MCP tools (Button gives click, TextInput gives type_into/clear/get_value), and a focus lens filters to roughly 15 relevant tools per interaction. Where A2UI and AG-UI define how agents talk to UIs at the wire level, raxol generates the UI and the agent surface from one Component tree: same source, two projections.

import Raxol.MCP.Test

import Raxol.MCP.Test.Assertions



session = start_session(MyApp)



session

|> type_into("search", "elixir")

|> click("submit")

|> assert_component("results", fn c -> c[:content] != nil end)

|> stop_session()

mix mcp.server starts the MCP server on stdio for Claude Code integration, and mix raxol.code is an interactive terminal coding agent (the axol face) with every tool call gated by an ALLOW/ASK/DENY authorization engine. See the Coding Agent.

Code is the coding-agent product, in two surfaces: mix raxol.code is the interactive terminal TUI (the axol face ≡··≡), and mix raxol.p is its headless twin (prompt in on argv, answer to stdout, contract events to stderr) for pipes and CI. Every mutating tool call is gated by an ALLOW/ASK/DENY authorization engine.

Both surfaces sit on the Harness, the agent-session engine (Raxol.Harness.*): a durable event journal, a typed event/command contract, and pure replay-from-offset surfaces, with staged interrupt, steer, and spend/blast-radius gates underneath. The same engine can supervise external agent CLIs (claude, cursor) as readily as Raxol's own loop. See Harness architecture.

The agent subsystems ship as standalone packages:

Install

# mix.exs

def deps do

  [{:raxol, "~> 2.6"}]

end

Or generate a new project:

mix raxol.new my_app

With Nix, nix develop drops you into a shell with the full BEAM and NIF toolchain (no local Elixir install required):

nix develop github:DROOdotFOO/raxol   # dev shell with elixir, erlang, NIF + speech deps

Try it

git clone https://github.com/DROOdotFOO/raxol.git

cd raxol && mix deps.get

mix raxol.playground          # 40 live demos, browse/search/filter

The flagship demo is a live BEAM dashboard with scheduler utilization, memory sparklines, and a process table:

mix run examples/demo.exs

See examples/README.md for the full learning path, including agent examples, swarm demos, and the sandboxed REPL.

Headless environment (CI, containers, agents)? The whole build-and-test path needs no tty:

mix local.hex --force        # fresh machines and CI: install Hex without a prompt

mix deps.get

mix compile                  # termbox2 NIF needs make + a C compiler

SKIP_TERMBOX2_TESTS=true MIX_ENV=test mix test --exclude slow --exclude integration --exclude docker

MIX_ENV=test mix raxol.rate  # RATE: render-determinism golden suite

Prerequisites, the quality gate, and constrained-sandbox notes are in Development.

Performance

Full frame in 5.0ms on Apple M1 (Elixir 1.20 / OTP 29), 31% of the 60fps budget.

WhatTime
Full frame (create + fill + diff)5.0 ms
Tree diff (100 nodes, 1 changed)32 us
Cell write (single)1.4 us
Buffer create (80x24)0.32 us
Emulator ingest (parse + apply, plain)1.7 ms
Memory per 80x24 buffer2 KB

Measured 2026-08-07 at fce2465bb with mix run bench/suites/comparison/framework_comparison.exs (full mode). The ingest row is the whole emulator path (parse plus state application), not the standalone ANSI lexer, which handles plain text in under a microsecond (mix raxol.bench parser).

Unix/macOS backend uses a termbox2 NIF; Windows uses a pure Elixir driver (usable, not yet tuned). See the benchmark suite.

Documentation

Start here

Cookbook

Reference

Advanced

Standalone packages: grab just the subsystem you need. See PACKAGES.md for the full table.

Development

Working from source needs Elixir/OTP (versions in .tool-versions) and a C toolchain: the termbox2 NIF compiles with make and cc (on Debian/Ubuntu, apt-get install build-essential). nix develop provides all of it in one shell. Every command below runs headless: no terminal is required for the build, the test suite, or the golden checks.

git clone https://github.com/DROOdotFOO/raxol.git

cd raxol

mix local.hex --force        # fresh machines and CI: install Hex without a prompt

mix deps.get

mix compile                  # builds the termbox2 NIF

SKIP_TERMBOX2_TESTS=true MIX_ENV=test mix test --exclude slow --exclude integration --exclude docker

MIX_ENV=test mix raxol.rate  # RATE: render-determinism golden suite

mix raxol.check              # full gate: format, compile, credo, dialyzer, security, docs, rate, test

mix raxol.check --quick      # skip dialyzer

mix raxol.demo               # built-in demos (needs a terminal)

SKIP_TERMBOX2_TESTS=true excludes the tests that need a real local terminal (pty lifecycle, timing-sensitive suites); CI sets the same variable. Plain mix test without the exclude flags also runs integration suites that need external services (the workflow checkpoint tests want PostgreSQL via RAXOL_WORKFLOW_PG_URL), so stick to the command above unless you have them. In sandboxes where HOME is read-only, point MIX_HOME and HEX_HOME at a writable directory before running mix.

Origin

Raxol started as two converging ideas: a terminal for AGI, where AI agents interact with a real terminal emulator the same way humans do; and an interface for the cockpit of a Gundam Wing Suit, where fault isolation, real-time responsiveness, and sensor fusion are survival-critical. The Gundam thing sounds like a joke. Then you look at the constraint set and it's exactly what OTP was built for: systems that can't go down, can't lose state, and have to hot-swap components while running.

Built with Raxol

Xochi is a private cross-chain DEX (intent-based swaps across 6 chains, sub-3s settlement, stealth addresses by default, ZKSAR compliance proofs) whose entire trading surface is raxol. One Component tree projects four ways: an SSH trader terminal, a LiveView web UI, a solver-agent surface for Riddler's sub-2ms solver, and an ops cockpit running sensor fusion on solver health. The solver executes behind a dedicated fail-closed stack (buyer-pre-signed intents, ledger-enforced spend gates, deployment guards that refuse to run unconfigured), kept deliberately off the MCP surface, so no fund-moving action is reachable as a generic tool call.

foglet-bbs by Brendan Turner is an SSH-only retro bulletin board (bbs.foglet.io, ssh bbs.foglet.io) that stress-tested raxol's SSH path into shape.

License

MIT. See LICENSE.md.