Codeman/packages/desktop

Codeman Desktop

A small native app that opens Codeman in its own window. Double-click it, and it runs Codeman on this Mac (installing it first if it is not there) or connects to Codeman on another machine (installing it there over SSH if needed), and Codeman fills the window. ⌃⌘F puts it in full screen.

macOS first: the app runs on 11.3 or later, and Codeman's own page needs the WebKit of Safari 16.4 (see Known limits). The same code is meant to build for Windows and Linux later.

• Size: 4.6 MB for the universal Codeman.app (Apple Silicon + Intel), 3 MB as a .dmg (measured on the first build).
• Stack: Rust with tao (window and event loop), wry (the system web view: WKWebView on macOS) and muda (native menus), plus objc2 for the two things wry leaves out on macOS (JavaScript dialogs, HTTP Basic login). No bundled browser and no Node in the app.
• Server: unchanged. The app is a client of Codeman's web UI, like a browser tab.

Why it is cheap

Codeman is already a web app, so the desktop app is a native window around the operating system's own web view. An Electron build of the same thing would ship a whole Chromium (around 150 MB). The native side only adds what a browser tab cannot do.

What it does (v0.1)

This Mac	The connect screen's first tab looks for Codeman on this Mac and offers what fits: Open Codeman when it runs, Start Codeman when it is installed but stopped, Install Codeman on this Mac when it is not there. The address comes from Codeman's LaunchAgent (port, sub-path, HTTPS). When nothing answers there but one of your own Codeman servers runs (found with ps and lsof: a codeman web --port 4000 in a terminal, say), the tab opens that one, or says where it listens; it never offers to start a second server, which would take over the first one's sessions, and Start refuses while one runs. A server that runs but listens nowhere yet (the first seconds after login, a restart) shows as starting: the tab looks again every second and, when a connect to this Mac had just been refused, opens Codeman once it is up. Start asks launchd to run the LaunchAgent (kickstart, or bootstrap when it is not loaded), so the server keeps its own settings and supervision; without a LaunchAgent it runs codeman web -d. The login comes from where Codeman keeps it: the LaunchAgent's CODEMAN_USERNAME/CODEMAN_PASSWORD, else ~/.codeman/.env (what Codeman's command-line clients read), admin by default. It goes only to 127.0.0.1 on that Codeman's port, only while one of your own Codeman processes holds that port, is never saved to the Keychain, and never reaches the page. Whether Codeman is installed is looked up in its files and processes, then the login shell; the interactive profile (nvm in .zshrc, say) only on Check again. Install opens Terminal with Codeman's installer (install.sh --local --service --port N): it may ask for the Mac password (Homebrew, Node.js, tmux) and which AI coding tools to set up, then Codeman runs as a LaunchAgent, so it keeps running when the app quits and starts at login. Also reach it from my phone and other computers drops --local, and the installer asks how (Tailscale, or the local network with a password). Port 3000 is used unless something else answers there, then the next free one. While the installer runs, the app looks every 3 seconds and opens Codeman as soon as it answers; it stops looking after the first answer, after 30 minutes, or 90 seconds after a finished install whose server never answered (then it offers Start). An install still running in Terminal is recognized by its process, so the tab waits for it instead of offering Install twice.
Another machine	The second tab connects to a server by address (below). Codeman is not installed there yet? opens Terminal, connects with ssh -t and runs Codeman's installer on that machine, which asks its questions there; the app then suggests http://<host>:3000 and the installer prints the real address at the end. The SSH login is checked to the characters of a user and host name (no option can be slipped in) and may carry a :port. The remote command runs under bash -o pipefail, so a failed download fails the install instead of reporting success. The same tab shows the one-line install command, with a Copy button, to run on a machine by hand.
Connect screen	Server address, recent servers, a login for password-protected servers (password kept in the macOS Keychain), auto-connect at launch. An address typed without http:// or https:// gets http://, except a tailnet name with no port (machine.tailnet.ts.net, which is tailscale serve), which gets https://. It explains each failure: nothing listening; wrong password; too many failed logins (the password field stays open, since a single-user Codeman accepts the right password even then); unknown host name; an address this Mac cannot reach (with a pointer to the Local Network setting); an http:// address on a port that only speaks HTTPS; an untrusted certificate; a redirect, with a button for the suggested https:// address; not a Codeman server. A multi-user account that must change its password connects, and Codeman's own dialog asks for the new one. If the server page has not started showing within 15 seconds, or you press Cancel while it opens, the connect screen comes back with a notice. A login that would cross the network over plain http:// to another machine says so. Return opens or starts the Codeman on this Mac and Esc cancels a connect, as in a Mac dialog (Install always takes a click). On a Mac whose WebKit is too old for Codeman it says so and Connect stays off (see Known limits).
Start Codeman	On the This Mac tab, and when http://127.0.0.1:<port> or http://localhost:<port> answers nothing, one click runs codeman web -d (or ~/.codeman/app) with your login shell's environment, so the server gets your real PATH (Homebrew, nvm) for the agents it spawns. zsh, bash and other POSIX shells run the start themselves; fish, nu, xonsh, tcsh and other shells only report their environment, and the start runs under /bin/sh with it. Offered for those two addresses only: codeman web -d listens on 127.0.0.1.
Login	The app answers the server's HTTP Basic login requests itself, with the login you connected with, so the page keeps working after the server restarts (a restart forgets every session cookie). It answers only for Codeman's own pages under the server's base path: a web tab or a rendered HTML file that asks for a Basic login of its own is left to WebKit and never gets your Codeman password. WebKit keeps no copy of the login, so every request for it gets the current one. Each connect first clears the app's cookies, so connecting to the same server as another user really switches users (local storage, where Codeman keeps its per-device settings, stays; a dashboard in a web tab that keeps its own login in a cookie may ask for it again). A page that still gets a 401 reloads once. If the server refuses the login (the password was changed, say), the app does not keep sending it: it checks it with a single probe, and only if the server refuses that too does the connect screen come back with a notice. That does not take focus from the app you are in: if Codeman is in the background, its Dock icon bounces.
Dialogs	Codeman's confirm(), prompt() and alert() (Delete case, Kill all sessions, Update Codeman, discarding unsaved edits, ...) show as native macOS dialogs. wry implements none of them, and without them WKWebView answers Cancel without showing anything. Each dialog's first line names the page it comes from, and says so when that is an embedded frame (a web tab, a rendered HTML preview), so a frame cannot pass its text off as Codeman's.
Full screen	⌃⌘F or the green button. The last state is restored at launch; Always Open in Full Screen forces it. Leaving full screen returns to the saved window size and position.
Menus	A real Edit menu (without one, ⌘C/⌘V do nothing in a WKWebView), Reload ⌘R, Switch Server ⇧⌘O, Developer Tools ⌥⌘I. The page sees every key first, so Codeman's own shortcuts keep working. If the main window ends up showing a raw file instead of Codeman, ⌘R takes it back to Codeman.
Pop-outs	Implements Codeman's existing native-wrapper bridge, window.CodemanHost (openInHostWindow in src/web/public/app.js), so popping out a session or a file preview opens a real app window, and the pop-out icon is on by default. Session and rendered-HTML pop-outs come only from Codeman's own pop-out button. A window.open from page script opens only Codeman's file and download windows, without taking keyboard focus, at most 3 at once and then 1 per second. Only Codeman's own pop-out pages become app windows (see Decisions); when the app refuses one, Codeman shows a toast. Each pop-out opens a step down and to the right of the window in use, never exactly on top of another one. A web tab's Open in new tab opens the dashboard in your default browser, as it would from a browser tab.
Links	On Codeman's own pages (the dashboard and session windows), a link to another site opens in your default browser, also on ⌘-click or a middle click. Pages can send at most 3 links to the browser at once, then 1 per second. Inside a rendered HTML preview or a web tab, a plain link to another site does nothing, while one that asks for a new window (target="_blank", window.open) opens in your default browser within the same budget (see Known limits).
Downloads	Codeman's Download links, and downloads Codeman opens in a new window, save the file to ~/Downloads whatever its type, and a toast in Codeman names the file. Files the web view cannot display are saved the same way.
A page that stops	When the web content process of a window ends (a WebKit crash, or macOS taking the process back under memory pressure), the window loads its page again instead of staying blank. A second time within 30 seconds, the main window goes back to the connect screen and a pop-out closes, so a page that cannot stay up never becomes a reload loop.
Window	Size, position and full-screen state are remembered. A saved window that hangs off the screen it opens on (it was last on a larger display that is gone, say) is pulled back on and shrunk to fit; one whose title bar is on no screen at all opens at the default size instead. Clicking the Dock icon brings back a minimized window.

Build (on a Mac)

Needs Rust 1.90 or newer (rustup; rustup update for an older toolchain) and the Xcode Command Line Tools (xcode-select --install).

cd packages/desktop
cargo test                                  # unit tests
./scripts/bundle-macos.sh                   # dist/Codeman.app for this Mac's architecture
./scripts/bundle-macos.sh --universal --dmg # Apple Silicon + Intel, plus dist/Codeman-<version>.dmg
open dist/Codeman.app

The connect page has its own test, which needs no Mac: from the repository root, npm run test:browser -- test/desktop-connect-page.browser.test.ts drives assets/connect.html in Chromium through every state of both tabs, under the Content-Security-Policy the app serves it with. It is part of the nightly browser suite, not of npm test.

The script builds with --locked against the committed Cargo.lock, targets the macOS version in macos/Info.plist (LSMinimumSystemVersion, 11.3), and takes the binary from where cargo says it wrote it, so CARGO_TARGET_DIR and a cargo config's build.target-dir work.

Settings live in ~/Library/Application Support/Codeman/desktop.json; passwords in the Keychain under Codeman Desktop, one item per username and server. A desktop.json the app cannot read or parse is moved aside, never overwritten: to desktop.json.corrupt, or to the first free name of desktop.json.corrupt.1 to .corrupt.9 when that one is taken, so an earlier copy is kept. If all ten names are taken, or the file cannot be moved, the app starts with default settings and saves nothing, which leaves the file where it is. When a server's username changes (a change of letter case counts), or a server drops off the recent list (it keeps 8), the Keychain item of the old username is deleted.

Decisions, and why

tao + wry + muda directly, not Tauri. Tauri is built on the same three crates. The deciding detail is login: Codeman's password protection is HTTP Basic, and a WKWebView shows no login dialog of its own (wry 0.57 implements no authentication-challenge handler). So the app sends the Authorization header itself on the first load, with wry's load_url_with_headers (Tauri 2.12's navigate() takes only a URL), and from then on answers the HTTP Basic challenges of Codeman's own pages with the current login. Codeman keeps its session cookies in memory, so after a server restart that answer is what keeps the page logged in. Using the crates directly is also smaller.

What wry leaves out is added at runtime, not patched in. src/macos.rs adds the JavaScript dialog methods and the authentication-challenge method to the classes of wry's own delegates, so wry stays an unmodified crates.io dependency.

What a page may ask of the app (all in src/policy.rs, unit-tested):

• Codeman shows content it did not write on its own origin: rendered HTML files (/html-view/) and proxied dashboards (/webview/). Only Codeman's own app shell (the dashboard and a session pop-out) may use window.CodemanHost. That is an allowlist on the raw path, and a path holding any % fails it, so an encoded spelling or a route Codeman adds later stays out.
• An app window opens only for Codeman's own pop-out pages under the server's base path, checked after decoding the path once, and which ones depends on who asks. window.CodemanHost (the app shell only) may open sessions, rendered HTML views, the raw, preview, attachment and folder file routes, the path picker's preview and api/download. A window.open or target=_blank link, which WebKit passes on from any frame without saying which, gets only the file routes and api/download, the pages Codeman itself opens that way; otherwise a rendered HTML file could open copies of itself as top-level windows that pass for the app's own. Such a window does not take keyboard focus, and these windows have a budget of their own (3 at once, then 1 per second), apart from the one links draw on. Any other page on the server's origin is refused rather than sent to the browser: a top-level /webview/ load would escape the web tab's iframe sandbox in either place, so it never opens anywhere. window.open('') is refused too, since WebKit's blank window carries none of the app's handlers.
• wry's navigation handler sees every frame and does not say which one. So a navigation to another site is blocked rather than opened in the browser; otherwise a page full of external iframes could open browser tabs. A real link click is sent out by the injected script in the main frame only.
• Only http(s) URLs ever reach the default browser, at most 3 at once and then 1 per second. macOS lets a page call window.open without a click, so this keeps a script from opening a browser tab for every call.
• The Authorization header is only sent to URLs under the server's base path. The login answers a Basic challenge only when it is Codeman's own: the server's scheme, host and port (never a proxy's), a URL below the base path, and not a web tab (webview/) or a rendered HTML file (html-view/), which relay 401s from content Codeman did not write. Only such a challenge can send the user back to the connect screen. WebKit is handed the login without persistence, so it keeps no copy: every challenge gets the current login, and one from before a Switch Server is never replayed.
• Each connect starts by clearing the app's cookies (never local storage). Codeman checks its session cookie before the Authorization header, so an earlier user's cookie would otherwise win over the new login.
• Microphone and camera requests prompt per page. wry's default without a handler is to grant them to every frame, sandboxed previews included.
• The bundled connect page keeps working until a server page commits in the main window (it is still the live page while the server loads), and only the main window may talk to it.
• codeman web -d gets the port and base path as separate arguments, never as shell text.

The installer runs in Terminal, not inside the app. install.sh asks for the administrator password on a terminal (Homebrew, its sudo keep-alive), the Xcode tools arrive as a system dialog, and ssh asks about host keys and passwords on a terminal too, so an install without one fails on the first fresh Mac. The app writes a short script to the per-user temporary folder (mode 0700, created fresh, deleted by the script as it starts) and opens it with open -b com.apple.Terminal, which needs no permission; scripting Terminal with osascript would ask for Automation access. The script prints what it runs. A This Mac install downloads the installer to a temporary file and runs it from there, so the installer's input is the terminal. Everything in the scripts is built and unit-tested in src/setup.rs; the page sends only which install it wants, whether other devices should reach it, and the SSH login, which is checked before it is quoted.

This Mac's own login comes from where Codeman keeps it. A Codeman installed with a password keeps it in its LaunchAgent (install.sh) or in ~/.codeman/.env (what codeman attach, codeman tui and codeman agent read). The app reads the same places, so a password-protected Codeman on this Mac opens without typing the password. The username and password always come from the same place, since the server reads its username from its own environment. The login goes only to 127.0.0.1 on that Codeman's port, and only while lsof shows one of your own Codeman processes holding that port: with Codeman stopped, whatever else listens there never gets it.

Never a second server on the same sessions. Two Codeman servers on one data directory and tmux socket attach to each other's live sessions, and codeman web -d only notices a server it started itself or one at the same address. So the app looks for running Codeman servers of this user (ps) before it offers or runs a start, and opens the one it finds instead.

Closing the main window quits the app. Codeman's sessions keep running on the server, so nothing is lost, and reopening takes about a second.

One reachability probe per user action, and one to check a refused login. Codeman counts a request without valid credentials against its login rate limit (10 per IP, 15 minutes; a successful login resets the count), so the app never retries in a loop. Once the server refuses the login in a challenge, the app sends it only once more, in the single probe that checks the refusal. If that probe is refused or rate limited, the connect screen comes back; the app does not send the refused login again. Keeping no copy of the login in WebKit has a cost here: after a server restart, each request that arrives without a cookie gets a 401 before the login goes out, and those count until one succeeds. Many windows reconnecting at once can push a request past 10, and that request then fails with a 429 instead of being answered. A refusal that lands while you are in another app does not bring Codeman forward: the connect screen loads where the window is, and the Dock icon bounces.

Known limits

• Self-signed HTTPS is refused. A server started with codeman web --https uses a self-signed certificate, and WKWebView rejects it (wry has no trust override). Use http://127.0.0.1:3000 for a server on this Mac. For another machine, serve Codeman through tailscale serve (https://<machine>.<tailnet>.ts.net has a real certificate) or a reverse proxy with a real certificate. Marking the certificate as trusted in Keychain Access can only help at https://localhost or https://127.0.0.1, the only names Codeman's certificate carries, and may not work even there. The connect screen says so when it happens.
• Keychain prompt after every rebuild of an ad-hoc build. The Keychain knows the app that saved a password by its code signature, and an ad-hoc signature changes with every build and update. So each new build asks once for access to the saved passwords: choose Always Allow. All Keychain work runs on one background thread, so the prompt does not freeze the window while it waits for an answer. To keep one identity across builds, sign with SIGN_IDENTITY (a self-made code-signing certificate from Keychain Access is enough). Microphone and camera permissions are asked again for the same reason.
• Gatekeeper. Without a Developer ID the app is signed ad hoc. A build you made yourself opens normally; a copy that arrived by download or AirDrop is quarantined. On macOS 15 and later, try to open it once, then click Open Anyway in System Settings > Privacy & Security (it asks for an administrator password). On macOS 14 and earlier, right-click it and choose Open once. Either way, xattr -dr com.apple.quarantine /Applications/Codeman.app on the copy in Applications works too. The Codeman.dmg on each GitHub release is signed with a Developer ID and notarized by CI (.github/workflows/desktop-dmg.yml), so it skips all of this. To do the same by hand: SIGN_IDENTITY="Developer ID Application: ..." NOTARY_PROFILE=<profile> ./scripts/bundle-macos.sh --universal --notarize, where scripts/sign-macos.sh lists what it needs.
• Local Network permission (macOS 15 and later). The first connection to an address on the local network (a LAN IP, a .local name) makes macOS ask whether Codeman may use the local network, and that first attempt can fail while the question is open: connect again after answering. If it was denied, turn Codeman on in System Settings > Privacy & Security > Local Network. A server started with Start Codeman on this Mac counts as part of the app here, so the same answer covers what it reaches on the local network (ssh to LAN hosts, Wake-on-LAN, web tabs pointing at LAN dashboards), also after the app quits.
• Subagent transcript windows do not open in the app. Codeman writes that view into a blank window.open('') window, which the app refuses (see Decisions), and shows a toast instead. A Codeman without the null check in viewSubagentTranscript (src/web/public/panels-ui.js) reports Failed to load transcript there. Open the transcript from a browser tab.
• Dialogs are app-modal. While a JavaScript dialog is open, every Codeman window waits for it. A page that calls alert() in a loop (a rendered HTML preview or a web tab can) leaves no way out but Force Quit (⌥⌘⎋).
• Codeman needs the WebKit of Safari 16.4. The app itself runs on macOS 11.3 or later (downloads go through WKDownload, which arrived in 11.3), but Codeman's terminal (xterm.js 6 uses class static blocks) needs the WebKit that came with Safari 16.4: macOS 13.3, or macOS 11 or 12 with Safari 16.4 or later installed. On an older WebKit the connect screen says so and does not connect. Session pop-outs also need BroadcastChannel (Safari 15.4), which the same requirement covers.
• Plain links in rendered HTML and web tabs do not open. A link to another site inside a rendered HTML preview or a web tab does nothing, in the preview overlay, and for a rendered HTML file in its pop-out window too: the app blocks navigation to other sites in every frame (see Decisions). A link there that asks for a new window (target="_blank", or a script's window.open) does open, in your default browser, within the budget of 3 at once and then 1 per second.
• No login dialog for a web tab's own HTTP Basic login. The app answers only Codeman's own login, and WebKit shows no dialog for any other, so a dashboard in a web tab that asks for HTTP Basic shows its 401 page.
• Downloads from previews and web tabs are saved without asking. Rendered HTML files and web tabs are allowed to start downloads, and the app saves every download to ~/Downloads without a prompt. Asking first for those frames is not done yet.
• No desktop notifications yet. WKWebView has no Web Notification API. Native notifications are the first item on the list below.
• No service worker. Codeman works without it; it is only an offline cache.
• Installing from the app is macOS only so far, and installing on another machine needs ssh access to it and curl or wget there. The app does not know when a remote install is done or which address it chose: the installer prints the address, and you connect to it under Another machine.
• A This Mac install always sets Codeman up as a LaunchAgent that starts at login. To stop it: launchctl unload ~/Library/LaunchAgents/com.codeman.web.plist; to remove Codeman: curl -fsSL https://getcodeman.com/install | bash -s -- uninstall.
• Windows and Linux need their menu hookup (init_for_hwnd, GTK), a credential store (Credential Manager, Secret Service) and installers. The rest of the code is platform-neutral.

Ideas for next

• Native notifications and a Dock badge with the number of sessions waiting for you (tao has set_badge_label; Codeman already tracks which sessions need input).
• A global hotkey that brings Codeman to the front from anywhere.
• A menu bar icon showing session states.
• Trusting a self-signed server certificate by its fingerprint.
• Asking before a download that a rendered HTML file or a web tab starts.
• A way out of a page that keeps opening dialogs (a "block further dialogs" option).
• Windows and Linux builds, auto-update.