Modules
Provider-agnostic agent loop for Elixir.
Custom agent definitions loaded from YAML/markdown files.
A single named agent loaded from a markdown+frontmatter file.
Writes a subagent's transcript to disk so it doesn't bloat the parent's context.
Git-worktree isolation for subagents.
One-shot startup task that GCs orphaned ex_athena git worktrees.
Usage + cost accounting and budget checks for agent runs.
Provider-capability map shape.
Pure parser + dispatcher for slash commands in the mix athena.chat REPL.
Talks to a local llama.cpp server's OpenAI-compatible HTTP API for chat-time helpers.
Talks to a local Ollama daemon's native HTTP API for chat-time helpers.
In-memory state for one interactive mix athena.chat session.
Full-screen TUI App for mix athena.chat, built on ExRatatui.App.
Bridges ExAthena.run/2 with the ExAthena.Chat.Tui App process.
Pure state container for the mix athena.chat TUI.
Pure view function for ExAthena.Chat.Tui. Turns a %State{} into the
list of {widget, %Rect{}} tuples the ex_ratatui runtime needs.
File-history checkpointing + rewind.
One-shot startup task that GCs file-history directories older than
30 days. Runs alongside the Agents.WorktreeSweeper.
Behaviour for context-window compaction.
Multi-stage context-compaction runner.
Behaviour for a single compaction stage.
First stage of the compaction pipeline. Replaces oversized tool-result contents with a short reference pointer.
Fourth pipeline stage — non-destructive view-time projection.
Third pipeline stage — collapses runs of repetitive tool calls.
Second pipeline stage — drops old tool-result messages whose paired assistant turn already happened.
Default ExAthena.Compactor — replaces the middle of message history
with a short LLM-generated summary.
Resolves the provider and per-call options for an ExAthena request.
Canonical error surface across providers.
Lifecycle hooks the loop fires at key transitions.
Agent-loop kernel. Dispatches to a ExAthena.Loop.Mode implementation
and handles everything around it: caps, budget, hooks, counters, events,
and termination accounting.
Flat, pattern-matchable event tuples the loop emits to :on_event.
Pluggable control-flow strategy for the agent loop.
Parallel tool-call dispatcher.
Internal state of a running agent loop.
Typed termination subtypes for agent-loop runs.
Public facade for the LSP subsystem.
GenServer wrapping a stdio Port that speaks JSON-RPC 2.0 (LSP framing).
Pure decoder for LSP's Content-Length-prefixed JSON-RPC framing.
PostToolUse hook that automatically fetches LSP diagnostics after Edit/Write tool calls and injects any errors or warnings into the next turn's tool-result.
Manages one ExAthena.Lsp.Client per {project_root, language} pair.
Maps file extensions to language atoms and language atoms to LSP server spawn specifications.
Top-level supervisor for the LSP subsystem.
Facade for MCP (Model Context Protocol) server management.
JSON-RPC 2.0 MCP client GenServer.
Loads and validates MCP server configuration.
Validated MCP server configuration entry.
Per-MCP-server GenServer. Owns one Client and the cached tool catalog.
Supervises one ExAthena.Mcp.Server per enabled MCP server config entry,
plus the ExAthena.Mcp.Registry.
Executor for MCP-backed tool specs.
File-based project memory.
Canonical in-memory representation of a conversation.
A single piece of content within a message — text, inline image, image URL, or file.
A single turn in the conversation.
A tool call the model wants the runtime to execute.
The outcome of a tool execution, replayed back to the model.
Plan-and-Solve mode.
Default mode: Reason-Act cycle.
Reflexion mode: after each ReAct iteration, insert a short self-critique pass before the next turn.
Decides whether a tool call is allowed.
Structured permission-denial returned by ExAthena.Permissions.check/3.
Behaviour every provider must implement.
In-memory provider for tests.
Delegating provider that runs requests through the req_llm library.
A normalised inference request.
A normalised inference response.
Canonical run outcome returned by ExAthena.run/2 and
ExAthena.Loop.run/2.
GenServer that owns a multi-turn conversation.
Behaviour for row-shaped session storage (sessions / messages / snapshots).
Behaviour for append-only session event storage.
ETS-backed store implementing both ExAthena.Sessions.Store (event-log)
and ExAthena.Sessions.SchemaStore (row-shaped sessions / messages /
snapshots).
ETS-backed in-memory session store. Default; ephemeral.
ETS-buffered JSONL session store.
Claude Code-style skills with progressive disclosure.
A discovered skill. body is the markdown after the frontmatter,
loaded only when needed; the catalog only ever uses name and
description.
Canonical streaming event types and the broadcaster helper.
A single streaming event.
One-shot structured extraction backed by a JSON schema.
Strict structured-output helper. Requires provider :structured_output capability.
Telemetry emission for ExAthena, shaped to the OpenTelemetry GenAI semantic conventions so consumers can plug directly into OTel without a translation layer.
Behaviour every tool must implement.
Canonical, unified representation of a tool — whether backed by a behaviour-implementing module or a dynamically-discovered MCP tool.
Extracts tool calls from a provider response.
Parses native tool-call structures from provider responses.
Best-effort parser for bare JSON tool calls embedded in assistant text.
Parses ~~~tool_call fenced blocks out of assistant text.
Context handed to every tool execution.
Resolves tools into ExAthena.Tool.Spec structs for the provider and loop.
Apply a unified diff patch across one or more files atomically.
Executes a shell command via /bin/sh -c with a configurable timeout.
Exact-string replacement in a file.
Finds files matching a glob pattern, relative to ctx.cwd.
Search file contents with a regex under ctx.cwd.
Built-in tool that exposes Language Server Protocol queries to the model.
Toggle the loop's permission phase.
Reads a file from the filesystem.
Synchronously run a sub-agent-loop with its own prompt, tools, and budget.
Writes the agent's todo list.
HTTP GET via Req, returning the body as text.
Creates or overwrites a file with the given content.
File-based session persistence for the web UI.
Mix Tasks
Drops you into an interactive chat session against the ExAthena agent loop.
Starts the ExAthena web chat UI on localhost.
Installs ExAthena into your project.
Igniter upgrader task. Invoked automatically by
mix igniter.upgrade ex_athena after the dependency is bumped;
can also be invoked directly via mix ex_athena.upgrade <from> <to>.