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 exo cluster's HTTP API (https://github.com/exo-explore/exo) for chat-time helpers.
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.
Observation masking — the research-validated middle layer between source-side tool caps and whole-transcript summarization.
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.
Per-iteration conclusion extraction.
Resolves the provider and per-call options for an ExAthena request.
Canonical error surface across providers.
Single source of truth for the "all working-tree changes vs HEAD" diff that the chat UIs render (web Git tab + TUI Changes tab).
Lifecycle hooks the loop fires at key transitions.
Optional file logging for the athena.web / athena.chat mix tasks.
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.
Pure streaming filter that removes ~~~tool_call ... ~~~ and
~~~tool_result ... ~~~ fenced blocks from chunked assistant text.
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.
Generic HTTP-based model listing backed by an ETS TTL cache.
Orchestrator mode: plan → todo → delegate each step to a subagent → integrate summaries → finish.
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.
Network address classification for the web tools' SSRF guard.
Observable state of one agent (the main loop or a subagent) in an
orchestrated run — the pure functional core of
ExAthena.Orchestrator.Coordinator.
Per-run orchestration blackboard.
Decides whether a tool call is allowed.
Structured permission-denial returned by ExAthena.Permissions.check/3.
Behaviour every provider must implement.
GenServer that loads provider specs from ~/.config/ex_athena/providers/ at
startup and makes them available for lookup.
Represents a provider loaded from a JSON file in the providers config directory.
Provider that wraps the claude_code SDK — the local claude CLI driven by
an Anthropic subscription / OAuth token (CLAUDE_CODE_OAUTH_TOKEN) or a
logged-in CLI. No ANTHROPIC_API_KEY is required.
Boundary for discovering the models the local Claude Code CLI supports.
Real ExAthena.Providers.ClaudeCode.ModelSource backed by the claude_code SDK.
In-memory provider for tests.
Delegating provider that runs requests through the req_llm library.
A normalised inference request.
ETS-backed GenServer semaphore that limits concurrent in-flight requests per provider.
Supervisor for the ExAthena.RequestQueue GenServer.
A normalised inference response.
Canonical run outcome returned by ExAthena.run/2 and
ExAthena.Loop.run/2.
OS-level command confinement for the Bash tool.
Behaviour for web-search backends.
HTTP-backed ExAthena.Search implementation. Backend-agnostic: the actual
provider is chosen by config and is the only provider-specific code here.
One normalized web-search hit. Backends map their provider-specific JSON/HTML
into this shape so the web_search tool and the rest of the system never see
provider details.
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.
One GenServer per embedded web terminal.
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.
Ask the human a clarifying question mid-run and block until they answer.
Executes a shell command via /bin/sh -c with a configurable timeout.
Exact-string replacement in a file.
Built-in completion signal tool.
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.
Read dependency usage rules — the LLM-oriented usage-rules.md docs that
Elixir libraries ship in their Hex package (the usage_rules convention).
HTTP GET via Req, returning the body as text.
Search the web and return ranked results (title, url, snippet).
Creates or overwrites a file with the given content.
Per-session owner of one in-flight agent run, decoupled from the LiveView.
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>.