Documentation

Installing it, getting a first agent session running, and reaching it from a phone. About half an hour end to end, and none of it needs a checkout.

• InstallInstall swe-mux from PyPI with uv, pipx, or pip, on Windows, Linux, or macOS. What each method leaves you with, and the two things no method does.
• Your first sessionCreate a Project, open a terminal, and promote it into an agent session by typing the command you already type. What to expect the first time.
• Reach it from your phoneThe phone client is the same application over your own Tailscale tailnet: no relay, no swe-mux login. How to set it up, and what the access boundary actually is.
• Have an agent set it upPaste one line into Claude Code, Codex, or any agent that can fetch a URL, and it reads a guide written for walking a person through installing swe-mux.

The four ideas the rest of the application is built on. Worth reading once, in order, because every later page assumes them.

• Projects and GroupsA Project binds a folder to sessions, layout, notes, files, history, and its own settings. What that means in practice, and which switches are per-Project.
• Sessions, terminals, and harnessesA session is one pseudoterminal with a process in it. What swe-mux owns, what survives a restart, and what a recognised harness gets that an unrecognised one does not.
• Session statusWorking, ready, awaiting, blocked: one status vocabulary across every vendor's CLI, how it is read, and why awaiting is the one to watch.
• What the control plane isThe layer that decides which session you look at next: deterministic facts, model-free detectors, attention ranking with an interrupt budget. Off by default, per Project.

What each surface does and where its controls are, one page per subsystem.

• Panes, tabs, and the drawerThe workspace is a mixed tree of panes, tabs, and splits, with a utility drawer beside it. What each drawer tab acts on, and how the phone projects the same tree.
• The prompt queueStage ordered messages against a session that is mid-turn. Durable, head-of-line, and with automatic delivery off by default. What turning it on actually means.
• Git, worktrees, and landingStatus and diff review beside the terminal, a worktree map, commit-level provenance split into committer and contributor, and a land queue that fast-forwards only.
• Notes, files, and previewsProject-owned notes in a real Markdown editor, a bounded file tree with editors, leased watches, and dev-server previews proxied so a phone never needs a raw port.
• History and transcriptsOne search and one resume across every supported harness, read from the vendors' own transcript files, which are never moved, rewritten, or deleted.
• Voice and the assistantRead aloud in three policy layers, hands-free conversation with local transcription and wake words, and an assistant whose confirmation floor is not configurable.
• Automation and alertsModel-backed observers that watch a run and report, an attention inbox with a hard daily interrupt budget, and push notifications to the device you are actually at.
• Accounts, usage, and budgetsSwitching between provider accounts you own, the three spend pots that are never summed, where a model call goes, and what a cap can and cannot enforce.

Every setting, every command, every default chord, and every file swe-mux writes.

• PluginsInstall versioned external-process plugins, understand their authority, and publish a standalone repository to the validated swe-mux catalog.
• Settings referenceEvery Settings tab, what it owns, and the rule that decides whether a switch is global, per Project, or per device.
• Command line referenceEvery mux subcommand, every muxd flag, the exit-code contract scripts branch on, and how the CLI resolves which daemon to talk to.
• Keyboard and the command paletteEvery default chord, the command palette that reaches the rest, and how rebinding and mobile gestures work.
• Where data lives, and what leaves the machineThe data directory and what each part of it holds, exactly which network requests swe-mux makes, what is worth backing up, and what an uninstall leaves behind.

What actually goes wrong, and what to do about it.

• TroubleshootingThe things that actually go wrong: a blank page, nothing on PATH, a daemon that will not start, sessions that look lost, a phone that cannot use the microphone.
• Developing swe-muxMaintainer material: running from a checkout, the verification gate a change has to pass, the DCO sign-off, and the extra rules a dependency change carries.