Packages

View Source

Raxol ships as a main package plus 17 focused subsystems. Use the main raxol package for the full framework, or take individual packages for narrower needs.

Main

PackageHexWhat
raxol{:raxol, "~> 2.7"}Full framework: runtime, UI, examples

Core

PackageHexWhat
raxol_core{:raxol_core, "~> 2.7"}Behaviours, events, config, plugins
raxol_terminal{:raxol_terminal, "~> 2.7"}Terminal emulation, termbox2 NIF
raxol_mcp{:raxol_mcp, "~> 2.7"}MCP server, client, registry, test harness
raxol_liveview{:raxol_liveview, "~> 2.7"}Phoenix LiveView bridge, themes, CSS
raxol_plugin{:raxol_plugin, "~> 2.7"}Plugin SDK, testing, generator
raxol_sensor{:raxol_sensor, "~> 2.7"}Sensor fusion (zero deps)

Agents

PackageHexWhat
raxol_agent{:raxol_agent, "~> 2.7"}AI agent framework
raxol_payments{:raxol_payments, "~> 0.2"}Agent payments, Xochi cross-chain, stealth
raxol_earn (pre-alpha)path: "packages/raxol_earn"Virtuals Agent Commerce Protocol (seller)
raxol_agent_client_protocol (pre-alpha)path: "packages/raxol_agent_client_protocol"Editor<->agent Agent Client Protocol (agentclientprotocol.com)
raxol_symphony (pre-alpha)path: "packages/raxol_symphony"Tracker-driven coding-agent orchestrator
raxol_gateway (pre-alpha)path: "packages/raxol_gateway"Unified messaging gateway (multi-platform)
raxol_cli (pre-alpha)path: "packages/raxol_cli"The raxol command (code, p, acp, agent, playground, new), packaged as a self-contained Burrito binary
raxol_console (pre-alpha)path: "packages/raxol_console"Boots a Virtuals ACP Console agent package onto the gateway stack

The coding agent layers as: Backend.Selector (LLM backend adapter) -> the Harness engine (the event/command contract Raxol.Agent.Contract and the durable journal Raxol.Agent.Journal in raxol_agent, the projections and surface widgets Raxol.Harness.* in main raxol) -> the product surfaces mix raxol.code (interactive TUI, also over SSH), mix raxol.p (headless one-shot), and mix raxol.acp (ACP on stdio, for editors), all three in raxol_agent -> raxol_symphony, which orchestrates many agent runs above them. The Harness is the engine; the mix raxol.harness.*.bless tasks only regenerate its golden/fixture test snapshots.

Surfaces

PackageHexWhat
raxol_speech{:raxol_speech, "~> 0.2"}TTS (say/espeak), STT (Whisper), voice cmds
raxol_telegram{:raxol_telegram, "~> 0.2"}Telegram bot, per-chat sessions, keyboards
raxol_watch{:raxol_watch, "~> 0.2"}APNS/FCM push, glanceable summaries

Dependency graph

raxol --> raxol_core, raxol_terminal, raxol_sensor, raxol_mcp,
          raxol_liveview, raxol_plugin

raxol_terminal --> raxol_core
raxol_mcp      --> raxol_core
raxol_liveview --> raxol_core (+ phoenix_live_view optional)
raxol_plugin   --> raxol_core

raxol_agent    --> raxol + raxol_mcp
raxol_payments --> raxol_agent (compile-time only)
raxol_earn      --> raxol_payments (runtime), raxol_mcp + raxol_agent (compile-time only)
raxol_agent_client_protocol --> (none; jason only, zero raxol deps)
raxol_symphony --> raxol_core, raxol_agent, raxol_mcp (all optional)
raxol_cli      --> raxol, raxol_agent (+ raxol_agent_client_protocol for `raxol acp`)
raxol_console  --> raxol_agent, raxol_gateway, raxol_earn

raxol_speech   --> raxol_core (+ bumblebee/nx/exla optional for STT)
raxol_telegram --> raxol_core (+ raxol/telegex/raxol_gateway optional)
raxol_watch    --> raxol_core (+ pigeon optional for APNS/FCM)
raxol_gateway  --> raxol_core (+ raxol_agent optional)

raxol_core     --> telemetry (only external dep)
raxol_sensor   --> (none)

The main raxol package does not depend on raxol_agent, raxol_earn, raxol_agent_client_protocol, raxol_gateway, or any of the surface packages. You opt into those.

Publishing

See Hex Publishing for the publish order. HEX_BUILD=1 strips local path deps so mix hex.build sees only Hex packages.

Run mix raxol.release.check before publishing anything. It walks the public train in dependency order and, per package, validates the metadata, confirms every file the tarball would carry is tracked by git, and runs mix hex.build --unpack without publishing. --metadata-only skips the builds; mix raxol.check runs that faster half for you.

Two failures are worth recognising on sight:

  • packaged file X is not tracked by git: mix hex.build packages the working tree, not the commit, so an untracked file under a packaged directory really would ship. Dotfiles count: .env, .env.* and .secrets are gitignored, which makes them untracked by construction and exactly what this catches. Commit it, ignore it via :exclude_patterns, or narrow the :files entry. --allow-untracked downgrades this to a warning, which is what mix raxol.check passes so an unstaged new module does not fail the interactive gate; CI runs without it.
  • release dependency X is dropped from the published tarball: a HEX_BUILD conditional in that package's mix.exs removed a dependency. Intended for pre-alpha packages that are not on the train yet, and reported as a warning so the choice stays visible rather than silent.