apex Overview

apex is a modernised acme. It keeps acme's way of working: a three-button mouse, tags that are text you type into, columns of tiled windows, B2 to execute, B3 to look, chords, plumbing, and everything as text. To that it adds what acme lacks for today's work. A client–server split lets the UI detach and re-attach, locally or over ssh. Terminals are embedded as first-class windows so coding agents can run inside the editor. And there is a tool API that does not depend on 9P or a mounted file system (DESIGN.md:1-7).

This page gives the big picture: the goals, the three kinds of process, how they talk, and where each part lives in the repository. The pages after it cover each part in depth, starting with the replication model (Sessions, Shards and Leadership) and the deterministic core (Entries, State and Apply).

What apex is for

DESIGN.md lists the goals, and most of the code follows from them:

• The acme experience. Colours, fonts and geometry follow plan9port. Local editing has no noticeable latency.
• All state on the server. The UI renders and takes input. A client can detach at any time and re-attach with nothing lost.
• Remotable. apex attach host over ssh is how you work on another machine. Files stay where the server runs, and nothing is synchronised.
• Agents. Terminal windows are first-class. An agent runs in one and drives the editor through the same CLI a shell script would use.
• Extensibility at least as good as acme's, with few concepts, exposed through the apex command and a typed protocol.

It has no plugin language and no configuration language. Configuration is a script of apex commands (see Configuration). "Single player mode" is deliberate: one UI attachment leads a session at a time (DESIGN.md:15-36).

Two principles run through the code. Nothing is ever lost: anything set aside is kept and shown, and silent discard counts as a bug. State on the server, rendering on the client: the client is a renderer and input device that holds a replica (DESIGN.md:48-57).

Features at a glance

Sources: DESIGN.md:1-57, crates/apex-cli/README.md:1-46

The model in one paragraph

A session (as in tmux) is a whole workspace living on one daemon, which hosts many. A client that joins a session gets an attachment, a fenced identity, over a connection (a socket that may drop and resume). The session's state is split into shards. Each shard is an independently replicated log with its own lease. Every shard has exactly one leader, which sequences entries into the log; everyone else replays them as a follower. A follower that wants a change proposes it to the leader (DESIGN.md:38-46, DESIGN.md:122-155).

In code, the shard is apex_core::Shard:

pub enum Shard {
    Buffer(BufferId),
    Window(WindowId),
    Layout,
    Term(TermId),
    /// The session's metalog: shards, attachments, leases, plumb rules.
    Meta,
}

Term and Meta are pinned: the server always leads them. Buffers, windows and the layout are leasable, so a UI that attaches takes their leases and edits with no round trip (crates/apex-core/src/ids.rs:46-62). DESIGN.md's table also lists a server-wide registry shard, but the code has no such shard: the daemon keeps its sessions in a map (crates/apex-server/src/daemon.rs:211-235).

State changes in one way only. State::apply is deterministic and pure: no clock, no randomness, no I/O. So a replica that replays the same log ends up with byte-identical state. Anything with an effect on the world is an exec entry naming its handler. The node that matches the handler carries out the effect and reports the outcome as further entries (DESIGN.md:157-187).

Ids need no coordination. Each attachment allocates from its own range, attachment << 40 | counter (crates/apex-core/src/node.rs:306, crates/apex-core/src/node.rs:312).

Sources: crates/apex-core/src/ids.rs:1-62, crates/apex-core/src/entry.rs:1-56, crates/apex-core/README.md:18-32, DESIGN.md:100-187

Three kinds of process

DESIGN.md names three kinds of process, and the code keeps the split (DESIGN.md:79-96):

The daemon

Daemon holds a map of Sessions. Each session has its Log, a Server, and a follower Node replica called view, plus the connection that currently leads it (crates/apex-server/src/daemon.rs:176-188). One thread owns all state. Connection readers and terminal events feed it through a channel, and each connection has a writer thread so a slow client never stalls the core. When no UI is attached, the daemon leads the session itself as the SERVER attachment, so scripts work headless and a UI that attaches later takes over (crates/apex-server/src/daemon.rs:1-11).

The socket defaults to $TMPDIR/apex-$USER/main.sock, overridden by APEX_SOCKET (crates/apex-server/src/daemon.rs:64-79). apex server runs the daemon in the foreground (crates/apex-cli/src/main.rs:881-887). apex attach, and -ensure-server on any command, start one in the background when the socket does not answer (crates/apex-cli/src/main.rs:889-900). apexd is a thin standalone entry point to the same Daemon::run (crates/apex-server/src/bin/apexd.rs:1-29). See The Daemon.

The UI client

apex-ui attaches to the local daemon, starting it if needed, and reopens the sessions it had last time. Flags choose another daemon (--attach), a pipe (--via CMD), a remote destination (--remote DEST), or an in-process server (--local) (crates/apex-client/src/main.rs:1-12).

Its central type is Acme. It holds a Log, a Node, and a Backend that is either Local(Server) in the same process or Remote(Link) behind a socket (crates/apex-client/src/app.rs:381-392). Each frame, render syncs the node with the backend, measures the layout and paints straight from core state (crates/apex-client/src/main.rs:67-89). See The UI Client.

Tools and the CLI

Every apex subcommand attaches to the session as a tool. It receives the same snapshot a UI would, reads from its own replica, and proposes to the leader (crates/apex-cli/src/main.rs:1-7). So this works with no UI running, and a UI that attaches later finds the result:

apex new notes.txt
apex edit notes.txt ',x/TODO/ c/DONE/'
apex exec notes.txt Put

The bundled tools are subcommands of the same binary: apex tool win | lsp | preview | web | agent | bridge NAME (crates/apex-cli/src/main.rs:1055-1078). Each attaches through the same protocol as any other tool, with no special privileges (crates/apex-cli/src/main.rs:496-499).

Sources: DESIGN.md:61-96, crates/apex-server/src/daemon.rs:1-79, crates/apex-server/src/daemon.rs:176-235, crates/apex-client/src/app.rs:381-392, crates/apex-cli/src/main.rs:713-791

How they talk

All three kinds of process use one wire. It is postcard messages in u32 little-endian length-prefixed frames, over a Unix socket or any byte stream (such as ssh's stdio). On every connection the daemon first sends its PROTOCOL number and build id. The protocol number is bumped by hand with every wire change and currently stands at 54. A client of another protocol version stops at that first frame with an error saying what to do (crates/apex-server/src/proto.rs:23, DESIGN.md:606-620).

The client side runs its Node over a mirror Log. The mirror assigns the same sequence numbers the server will store, so the UI leads with no wait and ships its entries on flush (crates/apex-server/README.md:8-24). The details are on The Attach Protocol and Proposals.

flowchart LR
    subgraph app["Apex.app (per machine)"]
        ui["apex-ui (gpui)"]
        node["Node replica, leader of buffers, windows, layout"]
        ui --- node
    end
    subgraph d["daemon (per host)"]
        sess["Session: Log + follower Node"]
        srv["Server: commands, Get/Put, watcher, plumber"]
        term["ptys + libghostty-vt, leads term shards"]
        plane["I/O plane"]
        sess --- srv
        sess --- term
    end
    subgraph tools["tools on the host"]
        cli["apex CLI and scripts"]
        sdk["apex-tool SDK users"]
        bridge["apex tool bridge (JSON)"]
        go["Go SDK"]
        go --> bridge
        bridge --> sdk
    end
    host[("files, processes, network")]
    node <-->|"Append, Entries, Propose, Applied"| sess
    ui <-->|"Io frames"| plane
    cli <-->|"Propose, Plumb, Term*"| sess
    sdk <-->|"Hello, Entries, Propose, PlumbAck"| sess
    srv <--> host
    term <--> host
    plane <--> host

Some typical flows, as ARCHITECTURE.md traces them:

sequenceDiagram
    participant UI as "UI (leader)"
    participant D as "daemon"
    participant T as "tool"
    UI->>UI: key, Node applies the edit locally
    UI->>D: Append entries
    D->>T: Entries
    T->>D: Propose ReplaceRange
    D->>UI: Propose
    UI->>UI: proposal apply, new entries
    UI->>D: Append and Applied
    D->>T: Entries and Applied
    UI->>D: Plumb (B3)
    D->>T: Plumb (a rule names the tool)
    T->>D: PlumbAck

Sources: ARCHITECTURE.md:27-126, crates/apex-server/README.md:1-24, crates/apex-server/src/proto.rs:23

Map of the repository

Workspace crates

The Cargo workspace members are listed in Cargo.toml:1-13.

The dependency order is simple: apex-edit ← apex-core ← apex-server ← everything else. The client and the CLI both link apex-server, because its remote.rs is the client side of the wire. The CLI also links every bundled tool crate (crates/apex-cli/Cargo.toml:11-22).

The bundled tools are not all built the same way. lsp and win use apex-server's Remote and Proposal directly. agent, preview, web and exp/acp depend on the SDK, apex-tool. The architecture review counts this among the API gaps (see Writing Tools).

Outside the crates

Sources: Cargo.toml:1-26, crates/apex-core/src/lib.rs:1-29, crates/apex-server/src/lib.rs:1-24, crates/apex-cli/Cargo.toml:1-22, mac/build-app.sh:1-32, go/README.md:1-73, providers/README.md:1-31

Sessions, URLs and remote hosts

Every session is a URL. local:///name is on this machine's daemon, ssh://user@host/name is reached over ssh, and sprite://box/name goes through a provider script. A daemon's first session is default.

For a remote target, apex attach launches apex-ui --remote DEST --session S. The UI installs the right apex and rc into ~/.apex/bin on the destination when its hash differs, then runs apex attach -stdio there. That command starts the destination's daemon if needed and copies bytes between its stdio and the daemon's socket. The bridge knows nothing of frames (crates/apex-cli/src/main.rs:1165-1190, DESIGN.md:724-768).

Inside a session, commands and terminals get apexsession and APEX_SOCKET. So apex run from an apex terminal acts on the session it is in (crates/apex-cli/src/main.rs:735-742). The binary also answers to the names apex-editor ($EDITOR) and xdg-open ($BROWSER), which become apex editor and apex plumb (crates/apex-cli/src/main.rs:713-729). See Remote Hosts and Providers and The apex Command.

Sources: crates/apex-cli/README.md:20-56, crates/apex-cli/src/main.rs:713-791, crates/apex-cli/src/main.rs:1165-1190, DESIGN.md:724-768

Window kinds

A window's body says what its content is, and nothing else:

pub enum Body {
    Text(BufferId),
    Term(TermId),
    Page(Source),   // Source::Buffer(id) | Source::Url, fetched via Host | Client | Tool(name)
}

Text windows show a buffer: acme's File, with its views, undo and dirty state. Term windows show a grid that the daemon writes as TermOp rows into a pinned term shard. Page windows are HTML drawn by the client in a WKWebView. A page's content is either a buffer written by a tool or a URL fetched through the host, the client, or a tool (crates/apex-core/src/entry.rs:45-80).

Status, owner, live and working flags, and notifications are common to every kind. See Buffers, Views and Undo, Terminals and The I/O Plane and Pages.

Sources: crates/apex-core/src/entry.rs:45-80, ARCHITECTURE.md:698-730

The design documents

Four documents at the root explain why the code is shaped as it is. Their As built notes describe what actually runs.

Read the docs with some care, because the code has moved on in places. DESIGN.md's shard table lists a registry shard that the code does not have. apex-server's README credits alacritty's parser for terminal latency, but terminals now use libghostty-vt (crates/apex-server/src/term.rs:1-3). ARCHITECTURE.md warns that its own file and line references will drift.

Sources: DESIGN.md:1-11, ARCHITECTURE.md:1-23, WEB.md:1-17, MODERN.md:1-10, crates/apex-server/README.md:42-50, crates/apex-server/src/term.rs:1-3

Where to go next

• To understand any change to state, read Sessions, Shards and Leadership, then Entries, State and Apply and The Node.
• To work on what touches the host (commands, files, terminals), read The Server, The Daemon and Terminals.
• To work on the app, read The UI Client and its child pages.
• To extend apex, read Writing Tools, Plumbing Rules and Verbs and The apex Command.
• To build it, read Building, Testing and Packaging.