We run a small IT services company in Santiago, Chile. A normal day for us is a dozen Linux servers, a handful of Windows machines we reach over RDP, and, since last year, three or four Claude Code sessions doing real work in parallel. For a long time that meant a laptop with too many tabs, a phone that was useless for any of it, and the recurring question "which Claude is waiting for me right now?".
MuxTerm is what we built to fix that. It has been our daily driver for months and we released it as open source (MIT) with a proper installer and signed updates this week. This post is the story and the design decisions, not a feature list; the list is in the README.
What we tried first
- Web terminals (ttyd, Wetty, Shellngn) are great at one thing: a shell in a browser tab. One shell, one tab. No remote desktop, no file browser, no memory of what you were doing.
- Apache Guacamole does RDP and VNC very well. It also brings Tomcat, a database and a web app whose terminal support feels like an afterthought. Running it for two Windows boxes felt like driving a truck to the bakery.
- tmux over SSH is perfect on a laptop. On a phone it is a punishment: tiny fonts, no Ctrl, no Esc, and every reconnect is a fight.
- None of them were responsive. Resize the window, rotate the phone, wake the laptop, and something broke.
The design
Terminals live in tmux on the server, not in the browser. Each panel is a tmux window served through ttyd. Close the browser, restart the server, update MuxTerm: the session is still there. This one decision gives you "pick up on the phone where you left the laptop" for free.
RDP and VNC through guacd, without Guacamole. guacd is the small C daemon that does the protocol work. We talk to it with guacamole-lite from Node and render in the browser with guacamole-common-js. No Java, no Tomcat. On a phone you get a touch trackpad (drag to move, tap to click, long-press for right-click) and a toolbar with the keys phones do not have.
One page, many panels. Local shell, SSH, RDP, VNC and an SFTP file browser are all panel types. Drag borders on a desktop; swipe between panels on a phone, with a pill at the bottom telling you where you are.
Credentials stay in your vault. We use Vaultwarden. MuxTerm asks the Bitwarden CLI for the credential when you open a connection and forgets it afterwards. Entries with ssh://, rdp://, vnc:// or sftp:// URIs show up directly in the connection dialog.
Responsive means re-fitting, not just media queries. The terminal has to be re-measured on every resize, rotation, tab switch and wake from sleep, and tmux has to be told the new size. Most of the bugs we fixed in the first months were in this area.
The Claude Code part
This is where MuxTerm stopped being "yet another web terminal" for us.
Claude Code writes a JSONL transcript of every session. MuxTerm reads it and turns a terminal panel into a conversation view: messages, tool calls, narration, the permission question with the options as buttons. You answer with a tap.
From tmux and the transcript we compute one state per panel: idle, working, waiting for permission, waiting for input, done. It shows as an indicator on the panel, so a glance at the workspace answers "which one needs me". An activity tray keeps every question and completion from every session, grouped by session, and Web Push sends the question to your phone. We have genuinely left Claude working and gone for a walk.
The honest caveat: Claude Code changes its transcript format between versions. The parser needs a small fix every few releases. If you see something rendered badly, an issue with the raw JSONL lines is the most useful thing you can send.
Shipping it to other people
Using a tool yourself and letting strangers install it are different jobs. Before releasing we spent a week on:
-
A one-line installer tested from scratch on Debian 12 and Ubuntu 24.04, including unprivileged Proxmox LXC containers (where guacd under systemd needs
Type=simple, a lesson learned the hard way). -
Signed release packages built in CI for x64 and arm64, with ed25519 signatures you can verify with
ssh-keygen -Y verify. No more "git pull and rebuild on the user's machine". -
An updater with rollback. Versions install side by side in
releases/<version>with acurrentsymlink. After restart the server checks its own health; if the new version cannot even start, a boot guard outside the release switches back. Failed versions are never retried. Stable and beta channels, staged rollout percentage.
curl -fsSL https://raw.githubusercontent.com/tecnologicachile/muxterm/main/install.sh | bash
# then https://your-host:3002, admin / admin, change it on first login
Docker works too, with guacd bundled, though tmux sessions do not survive recreating the container, so for daily use we recommend the native install.
What we would like help with
- Trying the installer on distros we have not tested and sending back what broke.
- The phone experience: it is good, it could be great.
- Translations. The UI is a mix of English and Spanish today.
- Anything about Claude Code transcripts after a new release.
Code and issues: https://github.com/tecnologicachile/muxterm. Landing with screenshots: https://muxterm.tecnologicachile.cl. If it saves you time, a star helps other people find it.
Top comments (1)
tr.ee/dev-to