# ExAthena v0.4.2 - 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.4)](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.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.

- 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 tool modules into the shape the provider + loop expect.

- 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.

## 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 <from> <to>`.

