github
how it works, in its own words

Documentation

swe-mux is documented in the repository, beside the code, and this index is generated from those documents rather than rewritten beside them. Each entry links to the document itself; the summary is the document's own opening line. These are design documents. They state what a subsystem is, the invariants it holds, and the decisions it has already made, which is what you want when a behaviour surprises you and not what you want on your first ten minutes - for that, the in-app tour and mux doctor come first.

Paths under each title are relative to .docs/, and a bare filename means .docs/design/features/. The link is the whole path.

#

Overview

  • Architecturedesign/architecture.md
  • Data modeldesign/data-model.md
    Durable data and ownership.
  • Interfacesdesign/interfaces.md
    All JSON APIs are rooted at /api. PTY and event streams use /pty/{session_id} and /events WebSockets.
#

Sessions and terminals

  • Sessions and terminalssessions.md
    Daemon-owned interactive ConPTY processes with immutable Project ownership, bounded replay, and reattachable browser viewports.
  • Cold and inactive session recoverysession-recovery.md
    Durable per-session state that outlives both the daemon and the PTY supervisor, so sessions whose processes died without anyone recording it come back as visible, dead, resumable rows instead of vanishing.
  • Multi-device terminal inputterminal-input.md
    One session can be attached from several devices at once, and two of the things they share cannot be shared: who may type into the PTY, and how big it is.
  • Launch profileslaunch-profiles.md
    A launch profile is a named executable/argv/environment definition for one backend.
  • Backend detection and observationbackends.md
    Adapters isolate spawn/resume syntax, transcript discovery, hook wiring, and graceful exit.
  • Agent status detection and regression defensestatus-detection.md
    The user-visible session status (starting | running | working | idle | awaiting | exited | crashed, plus the awaiting sub-reason approval | question | elicitation | rate_limit) is a contract, not a heuristic: every state names the positive evidence that may set it, every transition is ledgered with that evidence and a proven/inferred classification, and the whole surface is reproduced from the golden corpus so status regressions fail CI.
  • Evidence replay and delivery readinessdelivery-readiness.md
    The versioned replay corpus provides a deterministic regression boundary around every observed harness and a provider-neutral, read-only delivery classification.
  • Control-plane approvalsapprovals.md
    A per-conversation switch deciding what swe-mux answers on the agent's behalf when the harness asks for tool permission.
#

Projects and the workbench

  • Projects and Groupsprojects.md
    Projects are the durable catalog of canonical folders swe-mux can own.
  • Project resourcesproject-resources.md
    Safe access to Project-owned notes, the global Scratchpad, a bounded Project file tree, revision-checked text editing, ignore patterns, host file-manager reveal, and leased filesystem watches.
  • Project Actionsproject-actions.md
    The Project-level Run menu is the single launch surface for a new Claude, Codex, shell, custom terminal, worktree session, or an explicitly selected repository task.
  • Project context cardproject-card.md
    Project context is one user-owned Markdown file at <project>/.swe-mux/project-context.md.
  • Workspace panes and tabsworkspace-layout.md
    One Project-owned mixed-view workspace.
  • Browser shell and interactionui.md
    The Project-first browser shell around the mixed-view workspace: persistent app identity, active-Project navigation, provider/resource status, viewport overlays, settings, focus, and responsive controls.
  • Universal prompt libraryprompt-library.md
    Global and Project-scoped reusable text templates that can fill a focused terminal without submitting, executing, or becoming automation.
  • Process ownership and previewsprocesses-and-previews.md
    Per-session descendant attribution and bounded resource/listener snapshots.
  • Git awareness and worktreesgit.md
    Attached sessions poll the latest accepted live cwd (or spawn cwd until live telemetry is available) for HEAD, branch, dirty count, upstream divergence, linked-worktree identity, working-tree root, lines changed against HEAD, and lines and files changed against the comparison ref.
  • Agent Contextagent-context.md
    Read-only Project/global agent instructions, memory, and manual Project-root sync.
  • Agent Environmentagent-environment.md
    Passive session CLI tools, extensions, policies, and configuration inventory.
  • Configurator agentconfigurator.md
    A button that opens an ordinary agent session pointed at swe-mux itself.
#

History and transcripts

  • History and eventshistory.md
    SQLite indexes durable Claude/Codex run lifetimes and append-only daemon events.
  • Transcript branchestranscript-branches.md
    A Claude transcript is an append-only DAG, not a list of turns.
#

The control plane

  • Tier 0 deterministic factstier0-facts.md
    Durable, no-model capture of deterministic facts about agent sessions (file writes, commands, tests, git, tools) with pointers back to the immutable event log.
  • Deterministic control-plane consumersdeterministic-consumers.md
    The first layer that turns captured Tier 0 facts into user-visible judgements, and it is deliberately model-free: every detector is a query over deterministic facts, spends no tokens, and writes nothing but annotations.
  • Code-structure graphcode-graph.md
    A deterministic, always-fresh graph of how the code connects: who imports whom, who calls whom, where each symbol is defined.
  • Attention rankingattention-ranking.md
    The layer that decides which of many concurrent sessions actually needs the human, and when.
  • Fleet attention and intelligencefleet-intelligence.md
    Explainable cross-session evidence, attention routing, lineage, and user-confirmed review built on normalized events and read-only observer results.
  • Scan timelinescan-timeline.md
    The scan timeline is a read-only, run-scoped semantic index over bounded transcript deltas and deterministic Tier 0 facts.
  • Durable operational evidenceoperational-telemetry.md
    Durable, bounded observations for process identity, provider quota movement, reset evidence, quota/activity correlation, explicit context compaction, and explicit tool/skill activity.
  • Universal hooks and OpenRouter observersautomation.md
    Asynchronous, harness-neutral rules over normalized persisted mux events.
  • Automation enablementautomation-enablement.md
    Per-project opt-in for control-plane automations, gated by a dependency graph and an install-wide ceiling.
#

Queues, messaging, and landing

  • Persistent manual prompt queueprompt-queue.md
    Durable, ordered messages staged against a target agent run, delivered through one typed operation, surviving daemon and browser restarts without duplicate delivery.
  • Gated auto-deliveryauto-delivery.md
    A bounded controller that presses "send next" on a session's prompt queue when - and only when - delivery readiness has been continuously safe for a held window.
  • Agent messaging, the fleet queue, and drafted spawnsagent-messaging.md
    Bounded messaging between sessions that already exist, plus a way for an agent to ask a human to create one.
  • Land queueland-queue.md
    Serialized, deterministic landing of a finished worktree branch onto its Project's trunk.
  • Scheduled runsscheduled-runs.md
    A schedule does one of two things in one Project on its own, on a cron expression, on an interval, or once at a time.
  • mux MCP: the agent return path (reads + bounded writes and session control)mux-mcp.md
    A streamable-HTTP MCP endpoint (POST /mcp) hosted in the daemon that gives every spawned agent session visibility into the fleet - sibling sessions, their live status, bounded transcript reads, indexed search over conversation history, exact Agent Context sources, Project notes, cross-session memory reads, and request outcomes, plus the bounded write tools added in Phase 5 and the session-control tools added in Phase 7.6.
#

Voice, assistant, and alerts

  • Read aloud and hands-free conversationvoice.md
    Optional per-session reply synthesis (TTS, "read aloud") plus a workspace-level, browser-captured Conversation mode (STT, "hands-free"), isolated from history, Project, and transcript correctness.
  • The Mux assistantassistant.md
    A conversational operator for the whole workspace: the control plane given a chat surface and, behind the voice grammar's fallback tier, a voice.
  • Session and reset alertsnotifications.md
    Alerts are normalized root-session events delivered through an optional sound channel in a live tab and an optional Web Push channel that can reach a locked phone.
  • Device presencedevice-presence.md
    Which device class the human is actually using right now, tracked per client connection and aggregated to desktop / mobile.
#

Accounts, usage, and budgets

  • Provider accountsprovider-accounts.md
    App-owned credential snapshots for harnesses that explicitly declare provider-account management, reconciled against one live system login per provider.
  • Usage analyticsusage.md
    Optional cached historical token and cost summaries collected by the locally installed ccusage CLI.
  • Spending budgetsbudgets.md
    Every model-cost ceiling in the install has one shape, one editor, and one enforcement path.
#

Running it

  • Remote accessremote-access.md
    The same browser/API surface over localhost or a policy-controlled direct Tailscale listener, with optional Tailscale Serve for browser-recognized HTTPS.
  • Windows desktop shelldesktop-shell.md
    An optional Windows WebView2 window and system-tray supervisor around the same Preact/aiohttp surface used by ordinary desktop and mobile browsers.
#

Technical reference

  • Technical documentationtechnical/00_INDEX.md
    Implementation-facing rules supplement the product/design contracts in ../design/. Read the design feature first, then the relevant technical page before changing code.
  • Backend package responsibilitiestechnical/backend/packages.md
    Where daemon code lives and how to modify it. The map is split by domain so a change touches one file; this page is the index, the dependency rules, and the composition boundary.
  • Shared SQLite concurrencytechnical/backend/sqlite.md
    Shared SQLite operation rules.
  • Frontend package responsibilitiestechnical/frontend/packages.md
    Where browser code lives and how to modify it. The map is split by domain so a change touches one file; this page is the index and the shared rules.
  • Workspace state and persistencetechnical/frontend/workspace-state.md

Not everything under .docs/ is listed here. Left out, each with its reason: features/meta-hooks.md, a compatibility engine for a retired hook contract, not a feature; features/observations.md, storage compatibility for a user surface that was retired; features/ghost-windows.md, an internal remediation sweep with no user-facing control; features/setting-links.md, the internal mechanism behind a switched-off surface. Development notes, audits, and the internal plan are unlisted too; the roadmap page is the public projection of the last of those.