How EONYX Works: The Agent Architecture from the Inside

EONYX is written in Go and builds into a single static binary. Inside is a tidy set of packages built around one central abstraction. Let’s walk through how it is put together — useful both for contributors and for understanding the agent’s behaviour.

1 The agent core

At the heart of it there is a single interface and a loop around it; let’s look at how the packages, the provider and the agent itself are connected.

1.1 Dependency flow

At a high level: cmd → (tui | agent) → (provider → llm) + tools + session + permission + prompt. The default command brings up tui; the run subcommand drives the same agent headless. Everything below the llm.Provider interface is hidden behind it.

1.2 One abstraction: llm.Provider

The core is the internal/llm package, with no concrete backends. A provider has one method:

Stream(ctx, []Message, []Tool) (<-chan Event, error)

Event is a closed sum type: EventTextDelta, EventReasoningDelta, EventToolCall, EventUsage, EventDone, EventError. All communication with the model is reduced to a stream of events. Because of that, adding a backend means implementing a single interface.

The only concrete implementation is internal/llm/openai: an OpenAI-compatible client on top of net/http + SSE, with no vendor SDKs. internal/provider.For(...) is the single place where a model is mapped to a concrete provider.

1.3 The agent loop

internal/agent is the loop itself. Send records the user message, then repeats: stream the response, execute tool calls, feed the results back, and stop when the model no longer calls tools (the limit is maxSteps, 50 by default).

It is configured through Options:

• History — seed/resume;
• Persist — write every message (an error aborts the turn — the store is the source of truth);
• Authorize — the permission gate (a denial becomes an error result, it does not kill the turn);
• Events — streaming callbacks;
• ContextTokens — enables auto-summarization.

Consecutive read-only calls (read, ls, glob, grep, git statuses) run in parallel; results are always returned in the original order.

2 Tools and the build

Around the core sit the tool registry, the built-in shell, the remaining packages and, finally, the build into a single binary.

2.1 Tools

internal/tools is the registry of executable tools plus DefaultSet(...), which registers the 15 standard ones (read, write, edit, multi_edit, ls, picker, glob, grep, bash, fetch, git_status, git_diff, git_log, git_commit, todo_write). A tool’s declaration (what the model sees) is separate from its Handler (what actually runs). When the sandbox is enabled, file tools are wrapped in sandboxed(...).

internal/shell runs bash-like scripts in-process via mvdan.cc/sh/v3 — which is why bash works cross-platform without a system shell.

2.2 The remaining packages

2.3 Build and version

The version is a git tag, hardcoded nowhere: make build bakes git describe --tags --always --dirty into the binary, and eonyx --version prints it. A release is a v* tag push; from there GoReleaser in GitHub Actions builds binaries for Linux, macOS and Windows.

3 Summary