{
  "markdown": "# Raxol\n\n> Recursively, [axol](https://axol.io). Forever FOSS.\n\n[![CI](https://github.com/DROOdotFOO/raxol/actions/workflows/ci-unified.yml/badge.svg?branch=master)](https://github.com/DROOdotFOO/raxol/actions/workflows/ci-unified.yml)\n[![Hex](https://img.shields.io/hexpm/v/raxol.svg)](https://hex.pm/packages/raxol)\n\n[![raxol MCP server](https://glama.ai/mcp/servers/DROOdotFOO/raxol/badges/card.svg)](https://glama.ai/mcp/servers/DROOdotFOO/raxol)\n\nWrite one app. Render it to a terminal, a browser, an SSH session, or an agent.\n\nYour application is a single [TEA](https://guide.elm-lang.org/architecture/) module (`init`, `update`, `view`) running as an [OTP](https://en.wikipedia.org/wiki/Open_Telecom_Platform) GenServer. Raxol renders that module to four surfaces from one codebase:\n\n```\n                          +---> Terminal (termbox2 NIF)\n                          |\n  TEA module (GenServer) -+---> Browser (Phoenix LiveView)\n                          |\n                          +---> SSH (Erlang :ssh)\n                          |\n                          +---> Agent (MCP tools)\n```\n\nThe 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.\n\nBubble 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](docs/WHY_OTP.md) for the framework comparison, and [Why Raxol](docs/WHY_RAXOL.md) for how the runtime compares to Python agent stacks like Hermes and Omnigent.\n\n## Agents\n\nRaxol 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.\n\n```elixir\nimport Raxol.MCP.Test\nimport Raxol.MCP.Test.Assertions\n\nsession = start_session(MyApp)\n\nsession\n|> type_into(\"search\", \"elixir\")\n|> click(\"submit\")\n|> assert_component(\"results\", fn c -> c[:content] != nil end)\n|> stop_session()\n```\n\n`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 mutating tool call gated by an ALLOW/ASK/DENY authorization engine. See the [Coding Agent](docs/features/CODING_AGENT.md).\n\n**Code** is the coding-agent product, in two hands-on 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. From a clone, one setup command and one launch:\n\n```bash\n(cd packages/raxol_agent && mix deps.get)   # once\nbin/raxol-code                              # the TUI, your cwd as the workspace\n```\n\nNo API key configured? The TUI opens on a provider wizard instead of failing. `/inspect` (or `mix raxol.inspect` from `packages/raxol_agent`) shows every config source the agent will use in the current directory.\n\nSessions are durable. Each session journals its events to disk, so `--continue` and `--resume <id>` restore the model context and the scrollback together, `--replay <id>` prints a transcript straight from the journal (`--to-offset N` stops at an offset), `/rewind` drops back to an earlier turn, and `/share` mints a signed 24-hour link to a read-only transcript that follows the session live (needs `RAXOL_SHARE_SECRET` and a host mounting `Raxol.Agent.Code.ShareLive`).\n\nThe same TUI serves over SSH: `mix raxol.code --ssh --ssh-tenants /srv/tenants` hosts many users from one daemon, each behind their own public key with their own cwd jail, session store, and spending identity (`ssh <you>@your-host -p 2222` is the whole client). Single-tenant (`--authorized-keys`) and hosted deployment (`RAXOL_SSH_CODE=true`) are in [Coding Agent](docs/features/CODING_AGENT.md).\n\nTwo unattended surfaces run the same agent. `bin/raxol-acp` (or `mix raxol.acp`) serves it over the [Agent Client Protocol](https://agentclientprotocol.com) on stdio, for editors that spawn an agent themselves; `Raxol.Agent.Harness.McpTools` registers `harness_start_session`, `harness_send_prompt`, `harness_read_transcript`, and `harness_list_sessions` with the MCP registry, so a session started by an MCP client resumes later in the TUI. The ACP surface runs the full toolset with every sensitive call gated on a `session/request_permission` round trip, fail-closed on the decision: a client that refuses, times out, or does not implement permissions denies the write and keeps reading. The MCP surface stays read-only: `write_file`, `edit_file`, and `bash` are absent where nobody is there to answer an approval prompt.\n\nEvery one of those surfaces sits on the **Harness**, the agent-session engine: a durable event journal (`Raxol.Agent.Journal`), a typed event/command contract (`Raxol.Agent.Contract`), and surface state that is a pure fold over the event stream (`Raxol.Harness.Projection`), 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](docs/harness/architecture.md).\n\nThe agent subsystems ship as standalone packages:\n\n- **Pay** ([`raxol_payments`](docs/features/AGENTIC_COMMERCE.md)): wallets, ledger-enforced spending limits, and transparent auto-pay when an agent hits an HTTP 402, across five protocols (x402, MPP, Xochi cross-chain, Permit2, Riddler).\n- **Earn** (`raxol_earn`): the sell side. Declare an offering, implement two callbacks, and a buyer agent discovers it, escrows funds, and settles on-chain through the [Virtuals](https://virtuals.io) ACP job lifecycle (request, negotiation, transaction, evaluation, completed), one supervised process per job. Pre-alpha.\n- **Improve** ([`raxol_agent`](docs/features/SELF_IMPROVEMENT.md)): a solved task becomes a reusable `SKILL.md`. A background reviewer runs on a cheap model after each turn, writing durable memory and new skills without spending the live turn's latency or context.\n- **Reach** (`raxol_gateway`): one adapter contract to many chat platforms, process-per-chat sessions, DM pairing for authorization, and `/handoff` to move a conversation across platforms with its history intact.\n- **Orchestrate** (`raxol_symphony`): an OTP port of [OpenAI Symphony](https://github.com/openai/symphony) that polls a tracker, isolates each issue in its own workspace, and runs a coding agent, feeding six surfaces (terminal, LiveView, MCP, Telegram, Watch, JSON API) from one snapshot.\n- **Bridge** (`raxol_agent_client_protocol`): Elixir/OTP implementation of the [Agent Client Protocol](https://agentclientprotocol.com): the JSON-RPC 2.0 wire protocol between code editors and AI coding agents (the protocol Zed and a growing ecosystem speak). Bidirectional agent/client roles, pluggable transports (stdio, in-process), and durable resumable sessions (offset-based reattach/replay) as a vendor extension. Zero raxol-internal deps. Pre-alpha.\n\n## Install\n\n```elixir\n# mix.exs\ndef deps do\n  [{:raxol, \"~> 2.6\"}]\nend\n```\n\nOr generate a new project:\n\n```bash\nmix raxol.new my_app\n```\n\nWith [Nix](https://nixos.org), `nix develop` drops you into a shell with the full BEAM and NIF toolchain (no local Elixir install required):\n\n```bash\nnix develop github:DROOdotFOO/raxol   # dev shell with elixir, erlang, NIF + speech deps\n```\n\n## Try it\n\nNothing to install: [raxol.io](https://raxol.io) runs the same catalog in a\nbrowser, one LiveView per demo. That surface is this repo's `web/` app; see\n[web/README.md](web/README.md) to run it yourself. In a terminal:\n\n```bash\ngit clone https://github.com/DROOdotFOO/raxol.git\ncd raxol && mix deps.get\nmix raxol.playground          # 42 live demos, browse/search/filter\n```\n\nThe flagship demo is a live BEAM dashboard with scheduler utilization, memory sparklines, and a process table:\n\n```bash\nmix run examples/demo.exs\n```\n\nSee [examples/README.md](examples/README.md) for the full learning path, including agent examples, swarm demos, and the sandboxed REPL.\n\nHeadless environment (CI, containers, agents)? The whole build-and-test path needs no tty:\n\n```bash\nmix local.hex --force        # fresh machines and CI: install Hex without a prompt\nmix deps.get\nmix compile                  # termbox2 NIF needs make + a C compiler\nSKIP_TERMBOX2_TESTS=true MIX_ENV=test mix test --exclude slow --exclude integration --exclude docker\nMIX_ENV=test mix raxol.rate  # RATE: render-determinism golden suite\n```\n\nPrerequisites, the quality gate, and constrained-sandbox notes are in [Development](#development).\n\n## Performance\n\nFull frame in 5.0ms on Apple M1 (Elixir 1.20 / OTP 29), 31% of the 60fps budget.\n\n| What                                     | Time    |\n| ---------------------------------------- | ------- |\n| Full frame (create + fill + diff)        | 5.0 ms  |\n| Tree diff (100 nodes, 1 changed)         | 32 us   |\n| Cell write (single)                      | 1.4 us  |\n| Buffer create (80x24)                    | 0.32 us |\n| Emulator ingest (parse + apply, plain)   | 1.7 ms  |\n| Memory per 80x24 buffer                  | 2 KB    |\n\nMeasured 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`).\n\nUnix/macOS backend uses a termbox2 NIF; Windows uses a pure Elixir driver (usable, not yet tuned). See the [benchmark suite](docs/bench/README.md).\n\n## Documentation\n\nStart with the [documentation index](docs/README.md), or jump to:\n\n- [Quickstart](docs/getting-started/QUICKSTART.md)\n- [Components](docs/getting-started/COMPONENT_GALLERY.md)\n- [Surfaces](docs/guides/SURFACES.md)\n- [Coding Agent](docs/features/CODING_AGENT.md)\n- [Payments](docs/features/AGENTIC_COMMERCE.md)\n- [$RAXOL token facts](https://raxol.io/token)\n- [API docs](https://hexdocs.pm/raxol)\n\n## Development\n\nWorking from source needs Elixir/OTP (versions in `mise.toml`) and a C\ntoolchain: the termbox2 NIF compiles with `make` and `cc` (on Debian/Ubuntu,\n`apt-get install build-essential`). `nix develop` provides all of it in one\nshell. Every command below runs headless: no terminal is required for the\nbuild, the test suite, or the golden checks.\n\n```bash\ngit clone https://github.com/DROOdotFOO/raxol.git\ncd raxol\nmix local.hex --force        # fresh machines and CI: install Hex without a prompt\nmix deps.get\nmix compile                  # builds the termbox2 NIF\nSKIP_TERMBOX2_TESTS=true MIX_ENV=test mix test --exclude slow --exclude integration --exclude docker\nMIX_ENV=test mix raxol.rate  # RATE: render-determinism golden suite\nmix raxol.check              # full gate: format, compile, credo, dialyzer, security, docs, rate, test\nmix raxol.check --quick      # skip dialyzer\nmix raxol.demo               # built-in demos (needs a terminal)\n```\n\n`SKIP_TERMBOX2_TESTS=true` excludes the tests that need a real local terminal\n(pty lifecycle, timing-sensitive suites); CI sets the same variable. Plain\n`mix test` without the exclude flags also runs integration suites that need\nexternal services (the workflow checkpoint tests want PostgreSQL via\n`RAXOL_WORKFLOW_PG_URL`), so stick to the command above unless you have\nthem. In sandboxes where `HOME` is read-only, point `MIX_HOME` and\n`HEX_HOME` at a writable directory before running mix.\n\n## Origin\n\nRaxol 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.\n\n## Built with Raxol\n\n**[Xochi](https://xochi.fi)** 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.\n\n**[foglet-bbs](https://github.com/bmanturner/foglet-bbs)** by [Brendan Turner](https://foglet.io) is an SSH-only retro bulletin board ([bbs.foglet.io](https://bbs.foglet.io), `ssh bbs.foglet.io`) that stress-tested raxol's SSH path into shape.\n\n## License\n\nMIT. See [LICENSE.md](LICENSE.md).\n",
  "bytes": 13528,
  "sha": "d26683efa19638da99562c920917857ac4536d094a40b0499042dde576e074c6",
  "repo_slug": "droodotfoo/raxol",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_droodotfoo_raxol_d44549e0/readme"
}