install github
what changed, and when

Changelog

All notable changes to swe-mux are recorded here.

The format follows Keep a Changelog, and the project follows Semantic Versioning. While the major version is 0, a minor bump may carry a breaking change; the entry says so explicitly when it does.

Entries describe what changed for someone running swe-mux, not how it was built. Internal refactors, test changes, and documentation edits are omitted unless they change observable behaviour, a supported platform, or a distributed artifact.

The release procedure that maintains this file is RELEASING.md.

Unreleased

Nothing yet.

0.1.0

2026-08-28 release notes

First public release.

swe-mux is a local daemon that owns long-lived pseudoterminals for coding-agent CLIs and shells, and presents them in a browser. Everything runs on the operator's own machine; the trust boundary is stated in SECURITY.md.

Windows is the proving platform and the only one with a frozen desktop application. Linux runs the daemon and the test suite from source. macOS is implemented and typechecked but has never been executed.

Added 52 entries · Session ownership and terminals · Projects and workspace · Agent sessions · Fleet control plane · Agent-facing MCP surface · Git · Voice and assistant · Remote access and desktop · Operations · Licensing and governance
all 52 entries
Added
Session ownership and terminals
  • muxd, an aiohttp daemon that owns every pseudoterminal, so closing or reloading the browser never stops a session.
  • A separate PTY supervisor process that holds the terminals, so live sessions survive a daemon restart, a backend reload, and a rebuild of the desktop application.
  • ConPTY on Windows and the stdlib pty module on POSIX behind one platform seam, with Win32 Job Object process ownership and its POSIX process-group equivalent.
  • Crash recovery for sessions the supervisor could not keep alive: a durable session registry, terminal checkpoints, and cold sessions that stay readable after their process ends.
  • Multi-device attach for one session, with exactly one connection permitted to write to the PTY and one arbitrated terminal size shared across devices.
  • Terminal-aware bracketed paste, copy/paste, find, clipboard capture, and a bounded clipboard-history ring that refuses secret-shaped copies.
Projects and workspace
  • Explicit Projects that bind sessions, layouts, notes, history, and file browsing to a canonical folder, plus optional Groups for sidebar organization.
  • A mixed-view workspace of panes, tabs, splits, and drag/drop, with desktop split geometry as durable Project state and a single-pane projection for mobile.
  • Project-owned notes, a file browser with editors, ignore rules, and leased non-recursive watches.
  • A reusable prompt library whose templates are inert text: selecting one inserts, and never submits.
  • Trusted task discovery and a per-Project Run menu over VS Code tasks, root package scripts, and .swe-mux/actions.toml; every task file stays inert until its exact current contents are reviewed and approved, and any edit revokes that approval.
  • Process and preview registration for Project-local listeners, with HTTP, WebSocket, and HMR traffic bridged through the daemon's own URL, and static document previews served from the checkout under a sandbox CSP.
Agent sessions
  • A harness registry with capability descriptors and adapter families, covering Claude Code, Codex CLI, and plain shells.
  • Automatic promotion of a nested agent started inside an ordinary terminal, through mux-local claude.cmd and codex.cmd shims that preserve the normal CLI invocation.
  • Session status detection with a durable transition ledger, a state watchdog, awaiting sub-reasons, and a golden detection corpus.
  • A fail-closed delivery-readiness contract (safe / blocked(reason) / unknown) that never authorizes automatic terminal input on unknown, and never reads child-agent completion as root-agent readiness.
  • Control-plane approvals driven by the harness's structured permission request rather than the terminal screen, with a floor that no configuration can reach past.
  • Managed provider accounts: save, relabel, reauthenticate, switch, and remove Claude and Codex logins, with subscription-window polling. Only authentication is copied, and switching is always an explicit act.
  • A read-only History browser that reconciles native Claude and Codex transcript directories at startup without moving or deleting the originals, and reads a Claude transcript as the branching DAG it is.
  • Launch profiles for shells and agents, and a WSL agent bridge with an explicit reachability probe.
Fleet control plane
  • Tier 0 deterministic fact capture with source pointers and fingerprints, scoped by a run boundary that survives an in-CLI conversation replacement.
  • Model-free detectors for loops and stalls, declared-versus-verified claims, documentation debt, and provenance.
  • A tree-sitter code-structure graph backing blast-radius, navigation, context, and test-gap reads.
  • An opt-in scan timeline with per-run grants, budgets, source rehydration, and dead-end extraction.
  • Attention ranking with an interrupt budget, four in-app delivery channels, breakpoint detection, and an absence digest.
  • Automation observers that can capture and report but cannot type, approve, spawn, execute scripts, or mutate a Project, governed by a per-Project enablement dependency graph and an install-wide ceiling.
  • An automation dashboard with policy, usage, and activity tabs as the single editor that may turn an automation off in either scope.
  • A prompt queue with head-of-line ordering, stranding, and seed staging for new sessions; gated auto-delivery with a stability window, quiet hours, an emergency pause, and a consecutive-send cap.
  • Agent-to-agent messages and a fleet queue, where a non-human sender's write ends at a human unless the receiver granted it or itself solicited it.
  • Scheduled runs (cron, interval, one-off) that go through the ordinary spawn, resume, and queue paths and grow no second authority.
  • A land queue that serializes branch landing: reconcile, then a verification gate whose exact bytes a human approved, then a fast-forward-only merge, returning conflicts and failures to the branch's own agent.
Agent-facing MCP surface
  • A per-session MCP server exposing reads over the fleet: sibling sessions and their status, paged transcripts, archived conversation search, Project notes, Agent Context sources, scan timeline and search, provenance, verified status, prior resolutions, and dead ends.
  • Bounded writes only: staging a message into another session's prompt queue, drafting a spawn request for human approval, arming a session-settle watch, and interrupting or ending a session behind a per-Project grant.
Git
  • Git status, comparison, diff review, first-time repository initialization, a commit graph, and a provenance ledger that separates who authored a change from who landed it.
  • Worktree creation and removal, including a background purge that never appears in git worktree list and never raises a checkout's dirty count.
Voice and assistant
  • Read aloud, from a summarized or verbatim slice of the last turn, through the OS voice engine, a local Kokoro model, or an explicitly acknowledged external Edge TTS provider that is never bundled.
  • Hands-free conversation: browser capture through an AudioWorklet, Silero VAD, a frame-counted endpoint gate, and faster-whisper transcription with configurable wake words and commands.
  • The Mux assistant, where the model proposes names, deterministic code resolves and executes through existing paths, and the confirmation floor for a consequential action is not configurable.
Remote access and desktop
  • A loopback listener plus an optional direct Tailscale listener carrying the same UI and API, with automatic Tailscale Serve on HTTPS 443 so a phone browser gets the secure context its microphone requires.
  • Web push notifications with per-device preferences, and device presence that decides which device the operator is at once for the whole application.
  • A Windows desktop shell: a WebView2 window, a system tray supervisor, login startup, and a frozen onedir bundle that can rebuild and redeploy itself while preserving live sessions.
  • A progressive web app manifest and service worker for phone installation.
  • A daily release check against a static version.json, which is the only request swe-mux makes on its own behalf: it carries nothing identifying the install, it downloads nothing, and update_check_enabled turns it off entirely.
  • An updater for the frozen desktop app (mux update --install <version>, POST /api/update/install) that downloads a release only on an explicit act naming a version, verifies its SHA-256 against the published manifest before staging anything, and reuses the redeploy's staged swap so live sessions survive. It refuses, rather than installs, a release that would require a new PTY supervisor - that upgrade ends every live session and is an announced, deliberate act.
Operations
  • mux, an HTTP CLI with stable human and JSON output, and mux doctor for local configuration, integration, ownership, tailnet, provider, telemetry, automation, and queue problems.
  • A copyable diagnostics bundle (sanitized config, remote state, firewall status, network counters, status-health aggregate, log tails) that contains no terminal bytes and no message content.
  • Durable operational telemetry for process ownership, quota samples and reset detection, compaction, and tool evidence, all recorded as observations with confidence rather than as authoritative facts.
  • Usage analytics that never sum agent spend, metered automation spend, and provider quota into one figure, and spending budgets denominated in tokens or dollars with an honest floor when cost is unmeasurable.
  • Traffic accounting, response compression, static precompression, and conditional Git reads.
Licensing and governance
  • Apache-2.0 with NOTICE and TRADEMARK.md, declared in package metadata as a PEP 639 license expression and carried into the wheel.
  • Contributions under a DCO sign-off rather than a CLA.
  • A generated THIRD-PARTY-NOTICES.md and a two-half license gate: a metadata check over the resolved dependency closure that runs in the test suite, and a payload check over the built desktop bundle. No GPL or AGPL code ships; the two LGPL libraries ship as replaceable source.