Developer docs for main, checked against 9849aeb on 2026-11-16.

Sessions and CLI

CLI boundary

Commands in src/omar.rs defines the Clap command tree and dispatch. Global --session selects a runtime, --ea selects an assistant inside it, and --json requests structured command results.

The session-facing commands are implemented in src/sessions.rs:

CommandsResponsibility
up, serveStart or restart a runtime; foreground/background startup paths
ls, info, logsDiscover and inspect runtimes
attach --tui, attach --webOpen a runtime interface
run, runsSubmit a program and inspect runs
eaManage assistants and their events
downPause workflows and stop the runtime
rmRemove a runtime and its state

Follow the command enum for the remaining agent, workspace, checkpoint, and backend commands rather than treating this table as a full CLI reference.

Daemon ownership

The session registry lives under OMAR_HOME (default ~/.omar). Session records the name, process, state directory, socket, executable/build identity, tmux server, and HTTP URL. OMAR_STATE_DIR selects the runtime state root.

The hidden session-daemon command reads its private launch.json, loads configuration, recovers EA lifecycle state, starts Serve, and owns one scheduled-event delivery loop. The loop remains available without a dashboard client.

The Unix control socket accepts JSON requests with protocol, id, incarnation, and operation. The daemon checks all three identity fields before executing the operation. Responses identify the session and contain either result or error. A restarted session receives a new incarnation, preventing a stale client from addressing it as the old process.

Assistant scope and terminal UI

src/ea.rs defines EA IDs, registry entries, and scoped tmux names. src/ea_lifecycle.rs handles lifecycle admission and recovery.

src/app.rs holds terminal application state; src/ui/dashboard.rs renders it. Tmux operations live in src/tmux. Persistent scheduled events and delivery belong to src/scheduler, separate from the workflow runtime’s logical timers.