# ExAthena v0.7.1 - Table of Contents Provider-agnostic agent loop for Elixir. Drop-in replacement for the Claude Code SDK that runs on Ollama, OpenAI-compatible endpoints, llama.cpp, or Anthropic itself — same tools, hooks, permissions, and streaming across all providers. Includes a full Igniter installer. ## Pages - [ExAthena](readme.md) - [Changelog](changelog.md) - [LICENSE](license.md) - Guides - [Getting started](getting_started.md) - [Providers](providers.md) - [Tool calls](tool_calls.md) - [Tools](tools.md) - [The agent loop](agent_loop.md) - [Memory + Skills (v0.4)](memory_and_skills.md) - [Compaction pipeline (v0.4)](compaction_pipeline.md) - [Hooks reference (v0.5)](hooks_reference.md) - [Permissions (v0.4)](permissions.md) - [Agents + subagents (v0.4)](agents_subagents.md) - [Sessions + checkpoints (v0.4)](sessions_and_checkpoints.md) ## Modules - [ExAthena.Lsp](ExAthena.Lsp.md): Public facade for the LSP subsystem. - [ExAthena.Lsp.Client](ExAthena.Lsp.Client.md): GenServer wrapping a stdio `Port` that speaks JSON-RPC 2.0 (LSP framing). - [ExAthena.Lsp.Framing](ExAthena.Lsp.Framing.md): Pure decoder for LSP's `Content-Length`-prefixed JSON-RPC framing. - [ExAthena.Lsp.ImplicitDiagnostics](ExAthena.Lsp.ImplicitDiagnostics.md): 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. - [ExAthena.Lsp.Manager](ExAthena.Lsp.Manager.md): Manages one `ExAthena.Lsp.Client` per `{project_root, language}` pair. - [ExAthena.Lsp.ServerRegistry](ExAthena.Lsp.ServerRegistry.md): Maps file extensions to language atoms and language atoms to LSP server spawn specifications. - [ExAthena.Lsp.Supervisor](ExAthena.Lsp.Supervisor.md): Top-level supervisor for the LSP subsystem. - [ExAthena.Mcp.Config](ExAthena.Mcp.Config.md): Loads and validates MCP server configuration. - [ExAthena.Mcp.Config.Server](ExAthena.Mcp.Config.Server.md): Validated MCP server configuration entry. - [ExAthena.Mcp.Server](ExAthena.Mcp.Server.md): Per-MCP-server GenServer. Owns one `Client` and the cached tool catalog. - [ExAthena.Mcp.Supervisor](ExAthena.Mcp.Supervisor.md): Supervises one `ExAthena.Mcp.Server` per enabled MCP server config entry, plus the `ExAthena.Mcp.Registry`. - [ExAthena.Mcp.Tool](ExAthena.Mcp.Tool.md): Executor for MCP-backed tool specs. - [ExAthena.Sessions.SchemaStore](ExAthena.Sessions.SchemaStore.md): Behaviour for row-shaped session storage (sessions / messages / snapshots). - [ExAthena.Sessions.Stores.ETS](ExAthena.Sessions.Stores.ETS.md): ETS-backed store implementing both `ExAthena.Sessions.Store` (event-log) and `ExAthena.Sessions.SchemaStore` (row-shaped sessions / messages / snapshots). - [ExAthena.StructuredOutput](ExAthena.StructuredOutput.md): Strict structured-output helper. Requires provider `:structured_output` capability. - [ExAthena.Telemetry](ExAthena.Telemetry.md): Telemetry emission for ExAthena, shaped to the OpenTelemetry GenAI semantic conventions so consumers can plug directly into OTel without a translation layer. - [ExAthena.Tool.Spec](ExAthena.Tool.Spec.md): Canonical, unified representation of a tool — whether backed by a behaviour-implementing module or a dynamically-discovered MCP tool. - [ExAthena.ToolCalls.RawJson](ExAthena.ToolCalls.RawJson.md): Best-effort parser for bare JSON tool calls embedded in assistant text. - [ExAthena.Tools.ApplyPatch](ExAthena.Tools.ApplyPatch.md): Apply a unified diff patch across one or more files atomically. - [ExAthena.Tools.Lsp](ExAthena.Tools.Lsp.md): Built-in tool that exposes Language Server Protocol queries to the model. - Core API - [ExAthena](ExAthena.md): Provider-agnostic agent loop for Elixir. - [ExAthena.Config](ExAthena.Config.md): Resolves the provider and per-call options for an ExAthena request. - [ExAthena.Request](ExAthena.Request.md): A normalised inference request. - [ExAthena.Response](ExAthena.Response.md): A normalised inference response. - [ExAthena.Result](ExAthena.Result.md): Canonical run outcome returned by `ExAthena.run/2` and `ExAthena.Loop.run/2`. - Agent loop - [ExAthena.Budget](ExAthena.Budget.md): Usage + cost accounting and budget checks for agent runs. - [ExAthena.Loop](ExAthena.Loop.md): Agent-loop kernel. Dispatches to a `ExAthena.Loop.Mode` implementation and handles everything around it: caps, budget, hooks, counters, events, and termination accounting. - [ExAthena.Loop.Events](ExAthena.Loop.Events.md): Flat, pattern-matchable event tuples the loop emits to `:on_event`. - [ExAthena.Loop.Mode](ExAthena.Loop.Mode.md): Pluggable control-flow strategy for the agent loop. - [ExAthena.Loop.Parallel](ExAthena.Loop.Parallel.md): Parallel tool-call dispatcher. - [ExAthena.Loop.State](ExAthena.Loop.State.md): Internal state of a running agent loop. - [ExAthena.Loop.Terminations](ExAthena.Loop.Terminations.md): Typed termination subtypes for agent-loop runs. - [ExAthena.Session](ExAthena.Session.md): GenServer that owns a multi-turn conversation. - [ExAthena.Structured](ExAthena.Structured.md): One-shot structured extraction backed by a JSON schema. - Modes - [ExAthena.Modes.PlanAndSolve](ExAthena.Modes.PlanAndSolve.md): Plan-and-Solve mode. - [ExAthena.Modes.ReAct](ExAthena.Modes.ReAct.md): Default mode: Reason-Act cycle. - [ExAthena.Modes.Reflexion](ExAthena.Modes.Reflexion.md): Reflexion mode: after each ReAct iteration, insert a short self-critique pass before the next turn. - Messages - [ExAthena.Messages](ExAthena.Messages.md): Canonical in-memory representation of a conversation. - [ExAthena.Messages.Message](ExAthena.Messages.Message.md): A single turn in the conversation. - [ExAthena.Messages.ToolCall](ExAthena.Messages.ToolCall.md): A tool call the model wants the runtime to execute. - [ExAthena.Messages.ToolResult](ExAthena.Messages.ToolResult.md): The outcome of a tool execution, replayed back to the model. - Provider contract - [ExAthena.Capabilities](ExAthena.Capabilities.md): Provider-capability map shape. - [ExAthena.Provider](ExAthena.Provider.md): Behaviour every provider must implement. - Providers - [ExAthena.Providers.Mock](ExAthena.Providers.Mock.md): In-memory provider for tests. - [ExAthena.Providers.ReqLLM](ExAthena.Providers.ReqLLM.md): Delegating provider that runs requests through the `req_llm` library. - Tool calls - [ExAthena.ToolCalls](ExAthena.ToolCalls.md): Extracts tool calls from a provider response. - [ExAthena.ToolCalls.Native](ExAthena.ToolCalls.Native.md): Parses native tool-call structures from provider responses. - [ExAthena.ToolCalls.TextTagged](ExAthena.ToolCalls.TextTagged.md): Parses `~~~tool_call` fenced blocks out of assistant text. - Tool contract - [ExAthena.Tool](ExAthena.Tool.md): Behaviour every tool must implement. - [ExAthena.ToolContext](ExAthena.ToolContext.md): Context handed to every tool execution. - [ExAthena.Tools](ExAthena.Tools.md): Resolves tools into `ExAthena.Tool.Spec` structs for the provider and loop. - Builtin tools - [ExAthena.Tools.Bash](ExAthena.Tools.Bash.md): Executes a shell command via `/bin/sh -c` with a configurable timeout. - [ExAthena.Tools.Edit](ExAthena.Tools.Edit.md): Exact-string replacement in a file. - [ExAthena.Tools.Glob](ExAthena.Tools.Glob.md): Finds files matching a glob pattern, relative to `ctx.cwd`. - [ExAthena.Tools.Grep](ExAthena.Tools.Grep.md): Search file contents with a regex under `ctx.cwd`. - [ExAthena.Tools.PlanMode](ExAthena.Tools.PlanMode.md): Toggle the loop's permission phase. - [ExAthena.Tools.Read](ExAthena.Tools.Read.md): Reads a file from the filesystem. - [ExAthena.Tools.SpawnAgent](ExAthena.Tools.SpawnAgent.md): Synchronously run a sub-agent-loop with its own prompt, tools, and budget. - [ExAthena.Tools.TodoWrite](ExAthena.Tools.TodoWrite.md): Writes the agent's todo list. - [ExAthena.Tools.WebFetch](ExAthena.Tools.WebFetch.md): HTTP GET via `Req`, returning the body as text. - [ExAthena.Tools.Write](ExAthena.Tools.Write.md): Creates or overwrites a file with the given content. - Memory + Skills - [ExAthena.Memory](ExAthena.Memory.md): File-based project memory. - [ExAthena.Skills](ExAthena.Skills.md): Claude Code-style skills with progressive disclosure. - [ExAthena.Skills.Skill](ExAthena.Skills.Skill.md): A discovered skill. `body` is the markdown after the frontmatter, loaded only when needed; the catalog only ever uses `name` and `description`. - Compaction pipeline - [ExAthena.Compactor](ExAthena.Compactor.md): Behaviour for context-window compaction. - [ExAthena.Compactor.Pipeline](ExAthena.Compactor.Pipeline.md): Multi-stage context-compaction runner. - [ExAthena.Compactor.Stage](ExAthena.Compactor.Stage.md): Behaviour for a single compaction stage. - [ExAthena.Compactors.BudgetReduction](ExAthena.Compactors.BudgetReduction.md): First stage of the compaction pipeline. Replaces oversized tool-result contents with a short reference pointer. - [ExAthena.Compactors.ContextCollapse](ExAthena.Compactors.ContextCollapse.md): Fourth pipeline stage — non-destructive view-time projection. - [ExAthena.Compactors.Microcompact](ExAthena.Compactors.Microcompact.md): Third pipeline stage — collapses runs of repetitive tool calls. - [ExAthena.Compactors.Snip](ExAthena.Compactors.Snip.md): Second pipeline stage — drops *old* tool-result messages whose paired assistant turn already happened. - [ExAthena.Compactors.Summary](ExAthena.Compactors.Summary.md): Default `ExAthena.Compactor` — replaces the middle of message history with a short LLM-generated summary. - Permissions + hooks - [ExAthena.Hooks](ExAthena.Hooks.md): Lifecycle hooks the loop fires at key transitions. - [ExAthena.Permissions](ExAthena.Permissions.md): Decides whether a tool call is allowed. - Agents - [ExAthena.Agents](ExAthena.Agents.md): Custom agent definitions loaded from YAML/markdown files. - [ExAthena.Agents.Definition](ExAthena.Agents.Definition.md): A single named agent loaded from a markdown+frontmatter file. - [ExAthena.Agents.Sidechain](ExAthena.Agents.Sidechain.md): Writes a subagent's transcript to disk so it doesn't bloat the parent's context. - [ExAthena.Agents.Worktree](ExAthena.Agents.Worktree.md): Git-worktree isolation for subagents. - [ExAthena.Agents.WorktreeSweeper](ExAthena.Agents.WorktreeSweeper.md): One-shot startup task that GCs orphaned ex_athena git worktrees. - Sessions - [ExAthena.Sessions.Store](ExAthena.Sessions.Store.md): Behaviour for append-only session event storage. - [ExAthena.Sessions.Stores.InMemory](ExAthena.Sessions.Stores.InMemory.md): ETS-backed in-memory session store. Default; ephemeral. - [ExAthena.Sessions.Stores.Jsonl](ExAthena.Sessions.Stores.Jsonl.md): ETS-buffered JSONL session store. - Checkpointing - [ExAthena.Checkpoint](ExAthena.Checkpoint.md): File-history checkpointing + rewind. - [ExAthena.Checkpoint.Sweeper](ExAthena.Checkpoint.Sweeper.md): One-shot startup task that GCs file-history directories older than 30 days. Runs alongside the `Agents.WorktreeSweeper`. - Streaming - [ExAthena.Streaming](ExAthena.Streaming.md): Canonical streaming event types and the broadcaster helper. - [ExAthena.Streaming.Event](ExAthena.Streaming.Event.md): A single streaming event. - Errors - [ExAthena.Error](ExAthena.Error.md): Canonical error surface across providers. - MCP - [ExAthena.Mcp](ExAthena.Mcp.md): Facade for MCP (Model Context Protocol) server management. - [ExAthena.Mcp.Client](ExAthena.Mcp.Client.md): JSON-RPC 2.0 MCP client GenServer. ## Mix Tasks - [mix ex_athena.install](Mix.Tasks.ExAthena.Install.md): Installs ExAthena into your project. - [mix ex_athena.upgrade](Mix.Tasks.ExAthena.Upgrade.md): 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 `.