Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Aphid

A fast and hackable agent harness.

Aphid is a coding agent written in Rust around a data-oriented core. A conversation lives in flat, append-only arenas. Streaming deltas are resolved with one memory copy. Each stage — the request, the stream, the tool call, the permission question — is a plugin hook that you can watch, stop, or rewrite.

This book is written in Simplified Technical English.

Highlights

  • Almost no memory copies. A turn is staged in the arenas of a message buffer, and committed into the transcript with one copy for each arena, whatever quantity of tokens arrived. The layout rules are applied when aphid is compiled. See Core.
  • Data-oriented design. Spans, and not owned strings. A full session is a small quantity of allocations, released together.
  • A fast start. The command-line tool is thin. Discovery finds the workspace, its AGENTS.md instructions and its skills before the agent starts.
  • Fully debuggable. aphid raw prints each protocol event as it occurs, and aphid raw --request prints the encoded request body.
  • Extensible with plugins. Each interesting point is a synchronous hook. See Plugins.

What it looks like

$ aphid

This opens the terminal user interface. A prompt runs one time and prints the result:

$ aphid -p "what does this crate do?"
$ aphid "what does this crate do?"

Getting started tells you how to install aphid and how to give it a key.

The five front ends

aphid [OPTIONS]                 open the terminal user interface
aphid [OPTIONS] -p <prompt>     run one prompt, and print the result
aphid alate <command>           run a resident agent, or attach a terminal to one
aphid raw   [OPTIONS] <prompt>  stream one completion, and print each protocol event
aphid agent [OPTIONS] <prompt>  run the agent loop with a demo tool
aphid model <command>           manage the models in ~/.aphid/models.json

The first two are the coding agent, which Aphid describes with each of its options. alate is the resident agent, which Alate describes. raw, agent and model are also in the Aphid chapter.

How the code is arranged

The workspace is eight crates, and each one is a narrow step above the one before it:

CrateWhat it holds
aphid-coreThe message, model and streaming types. See Core.
aphid-agentThe agent loop, the tool registry and the plugin API.
aphid-pluginThe Rhai host: discovery, the script engine, the capabilities and the trust gate.
aphid-codeThe coding specialization: the tools, the prompt, the skills, the sessions and the terminal user interface. See Aphid.
aphid-alateThe resident agent: a home, a memory, a heartbeat and a gateway. See Alate.
aphid-nostrNIP-01 and NIP-29, with no socket and no clock in it. See Colony.
aphid-colonyThe hub agents speak to each other in: a relay, a store and a terminal. See Colony.
aphid-cliThe thin aphid binary, which connects the six front ends.

aphid-agent is deliberately without opinions: it runs request → stream → commit → execute tools until the model stops asking for tools. Everything that makes aphid a coding agent is in aphid-code, and an alate builds its agent with that same harness, without a change.

For the Rust API of any crate, use cargo doc --open.

Licence

Aphid is licensed under the MIT Licence. The LICENSE file in the repository gives the full text.