Architecture

Aether is a Cargo workspace. Every crate lives in crates/.

Crate	Responsibility
app	The desktop app: windows, pages, sidebar, settings, notes, image viewer, browser, watch list, Touch Bar and the aether mcp entry point.
ui	Theme, color schemes and shared components, including the chat transcript views.
core	Settings, paths, the Update stream type and request types shared by everything else.
driver	One driver per provider CLI: Claude Code, Codex, OpenCode, Pi, Antigravity. Spawning and binary discovery live in spawn.rs.
agent	The built-in OpenRouter agent, the orchestrator for lead chats, tools, the SQLite store, usage history, skills and discovery of agents running outside Aether.
git	Refs, hunks and worktrees, on top of the git binary with timeouts and index.lock retries.
terminal	Terminal emulator on alacritty_terminal, and the split terminal workspace.
explorer	File index, search, tree and editor buffers.
voice	Microphone capture and on-device transcription with whisper.

The path of a message

1. You send from the composer in app.
2. agent looks up the chat’s live session, keyed by provider, binary, folder, model, effort and access. If the key changed, it drops the session and starts a new one that resumes the conversation.
3. A driver writes the prompt to the CLI in its own wire format: stream-json for Claude Code, the app-server protocol for Codex, HTTP plus server-sent events for OpenCode, NDJSON RPC for Pi.
4. The driver translates everything the CLI emits into aether_core::Update, the single stream the UI reads: text deltas, tool calls, approvals and questions, titles, usage.
5. ui renders the transcript from those updates.

There is no daemon. Drivers run inside the app process and each chat owns one CLI child process, except OpenCode, where chats share one service.

Orchestration

A lead chat’s CLI is launched with Aether’s MCP server attached. That server is the same binary run as aether mcp. It forwards tool calls over a Unix socket (orchestrator.sock) to the running app, which checks the per-lead token and acts on its chats. See orchestration.

Key dependencies

• GPUI through gpui-component for UI, with tree-sitter grammars for highlighting.
• wry for the browser panel on the system web view.
• alacritty_terminal for terminal emulation.
• whisper-rs and cpal for dictation.
• sqlx with bundled SQLite for the store, keyring for the OpenRouter key.
• adk-rust for the built-in OpenRouter agent.

Further reading in the repository

• GLOSSARY.md: the project’s vocabulary.
• docs/wayfinder/: research and decisions behind the CLI drivers.
• docs/superpowers/specs/: design specs for each feature.
• docs/adr/: architecture decision records.