[Ark0N]

What this does

Installing Codeman from the macOS app used to mean opening Terminal, typing a Mac password and answering the installer's questions there. With this PR the app does it in its own window: no Terminal, no password. If the Mac has no coding agent, the app asks which one you want and installs it along with Codeman.

The steps on a Mac without Codeman:

1. Install Codeman on this Mac. The app fetches the installer and asks it what is on this Mac.
2. Choose a coding agent, shown only when none is installed. The list comes from the installer's catalogue, the first entry is preselected, and Skip for now is there.
3. Who can reach Codeman? Only this Mac, or this Mac and the local network with a password.
4. A checklist follows the install, with a clock on the running step and the installer's output one click away. Cancel stops it.
5. Codeman opens by itself.

The app can be closed during the install. It keeps going, and the app picks it up when it opens again.

The same chooser works after the install. Add a coding agent is on the This Mac tab whenever Codeman is on this Mac, running or not, and Add a Coding Agent to This Mac… is in the app menu, so it can be reached from a Codeman page too. It lists what can be added and what is already here, installs one agent with the same checklist and Cancel, and ends on Open Codeman, Add another or Done. It needs no password and leaves a running Codeman alone. After Skip for now, the app says Codeman has no agent yet and offers this before it opens Codeman.

Finding a Codeman that is already running

The This Mac tab now lists every Codeman server of this user on this Mac, with its address and version. When nothing answers at the default address it says Codeman is already running on this Mac. with a row each. Otherwise they sit under Open Codeman as Also running on this Mac. A second instance beside the main one (a beta, a codeman web --port 4000 in a terminal) used to go unseen, and a server at another address sent the user to Another machine to type it in.

A row has Connect, or the reason the app cannot open it. Connect fills in the address and runs the page's one connect(), so the app checks it, uses its saved login and remembers it like a typed address. Nothing connects by itself.

found_addresses in src/setup.rs is pure and works out an address for each listening socket of the user's servers, with https and the base path from the command line. Each address other than the default one is asked once, all at the same time, with no login: 2 seconds next to a Codeman that answers, the usual 5 when none does.

Stacked on #763

This cannot work without #763, which is the app. It also needs #768, install.sh --no-admin, the route that needs no password, which is what makes a terminal-free install possible at all. #768 has shipped in 1.49.0.

• The base is feat/desktop-app (feat(desktop): native macOS app that runs, installs or connects to Codeman #763), so feat(desktop): native macOS app that runs, installs or connects to Codeman #763 is not in this diff.
• That base predates 1.49.0, so feat(install): install without administrator rights (--no-admin) #768's changes are in this diff until feat(desktop): native macOS app that runs, installs or connects to Codeman #763 takes master. To see only this PR, open these under Commits: feat(desktop): install Codeman from the app..., feat(desktop): add a coding agent once Codeman is installed, fix(install): say why an added agent failed... and feat(desktop): find the Codeman servers running on this Mac.... The merges between them fit this work onto feat(desktop): native macOS app that runs, installs or connects to Codeman #763's review commits.
• On a Mac without the developer tools, fix(macos): never run Apple's placeholder git, which opens the developer tools window #779 is needed as well: without it Codeman's first page load runs Apple's placeholder git, which opens the window that offers to install them.
• Merge order: feat(desktop): native macOS app that runs, installs or connects to Codeman #763, then this one. GitHub retargets this PR to master once feat/desktop-app is merged and deleted.
• getcodeman.com/install is install.sh on master, so the shipped app can only use this route once this is merged. Until then the app explains that and offers Terminal.

No changeset: COM writes it.

How it works

The app runs the installer and supplies the answers. src/gui_install.rs runs install.sh --no-admin --progress --service --ai-cli <id>|none with CODEMAN_NONINTERACTIVE=1 and stdin closed. The login shell's environment goes along, so it finds the Node.js, git and agents that are already there. The network password travels in the environment, never in the arguments, where ps would show it.

The installer's output goes to a file, never a pipe, and it runs in its own process group. With a pipe, quitting the app would kill the installer at its next write; in the app's group, launchd would kill it with the app. The file holds the whole run, so a reloaded page or a reopened app finds the process in ps and replays the file from the top. The app keeps no other state about a run.

The app has no list of coding agents. It reads them from install.sh preflight, so a new agent needs no new app, and the list always matches what can be installed on that machine. On the no-admin route that means omp (its macOS install is Homebrew) and deepseek (a launcher alone cannot drive a pane) are not offered.

Adding an agent is a run of its own. install.sh agent <id> touches neither Codeman nor its service, so it may run next to a live server, which an install must refuse: the service step would replace that server under its sessions. It has its own temporary folder, so ps tells the two apart, because everything that reads a running install takes it to mean "Codeman is being installed". One run goes at a time. --no-admin goes to both preflight and agent: it decides what counts as installable, so without it on both the page could offer an agent the run refuses.

Terminal stays as the fallback. no_admin_blocker decides: on a Mac older than 15 with no tmux, the tmux project's build cannot run, so the app says why and offers Terminal. Install in Terminal instead is always on the last question, and the install over SSH on another machine is unchanged.

Changes to install.sh

All usable from a terminal too, and all documented in docs/wiki/Installation.md.

--ai-cli <id>|none / CODEMAN_AI_CLI	Answers the agent menu. Without it CODEMAN_NONINTERACTIVE=1 installs the first entry of the catalogue, and a GUI must never rely on that. A typo stops before anything runs; a name this machine cannot install warns and carries on, and never installs a different one.
install.sh agent <id>	Installs that one agent and nothing else. It checks that this agent landed before it says done: the install's own check is fatal only when no agent is left, so with another one present a failed install would have reported success. An agent that is already here is a success that runs nothing.
install.sh preflight	One JSON object on stdout: what is here, what is missing, why --no-admin cannot finish (if so), every agent with installed and installable. Prompts for nothing and writes nothing.
--progress / CODEMAN_PROGRESS=1	Adds @@codeman phase <name> and @@codeman error <text> lines. A run that ends without phase done failed.

cli_offerable is now the one rule for what can be installed here, so the menu, --ai-cli and preflight cannot disagree. A step's failure now reads Building Codeman failed (exit 1). and the Last lines of ...: header moved to its own line, so the app can show the sentence alone.

Tested

Clicked through on a fresh MacBook Pro by the maintainer (M5 Pro, 48 GB, macOS 27.2), in the real WKWebView against the real Rust side. That Mac had no Node.js, tmux, Homebrew or developer tools and no ~/.codeman. It did have Claude Code, so the agent step did not show.

• The install from the app took about 25 seconds, with no Terminal, no password and no error. The LaunchAgent ran, the server answered on 127.0.0.1:3000, and Codeman opened. One second after the server started, Apple's developer tools window came up: that is the bug fix(macos): never run Apple's placeholder git, which opens the developer tools window #779 fixes.
• After a full uninstall, with the developer tools removed again and fix(macos): never run Apple's placeholder git, which opens the developer tools window #779 in the build, the same install took about 20 seconds. Apple's window did not open, and the system log holds no install request.
• Running the installer again over a live install, as an update does, took about 20 seconds.
• With a second server on port 4000, the This Mac tab listed it under Also running on this Mac, and Connect opened it.

On a real Mac (Apple Silicon, macOS 27.2, stock /bin/bash 3.2), through the Rust code the page calls. Under a throwaway HOME whose login PATH holds no Node.js or tmux, with xcode-select stubbed to fail the way a Mac without developer tools does, so git counts as missing:

• A fresh install downloaded real Node.js and tmux and installed the real Claude Code. It took 20 to 30 seconds on that fast machine, with Codeman's own source coming from a local archive of this branch, so the app keeps saying "a few minutes". That install took 947 MB (measured once, with Claude Code), which the app states up front as about 1 GB.
• Cancel in the middle of packages left no installer process behind. Installing again finished the job.
• A second fresh install with Codex covered the npm route, which lands in the runtime folder instead of ~/.local/bin.
• The server each install built ran on the PATH the LaunchAgent would get (minus Homebrew), and a real shell session in real tmux answered through the API: 2.1.318 (Claude Code), tmux 3.7c, and for the other run codex-cli 0.166.0.

Adding an agent, on the same Mac, after a real install with Skip for now, with that install's server running:

• Codex (the npm route) installed in 3 seconds and Claude Code (the curl route) in 11, and the server's process never changed. A real shell session then ran both: codex-cli 0.167.0 and 2.1.318 (Claude Code).
• That Mac's own Codeman was running too, so this is also the proof that an agent run is not refused next to a live server.
• Cancel left no installer process behind, and adding an agent that is already there installed nothing.
• The first Claude Code attempt died on the vendor's download (curl: (56)). The app reported it as failed with Codex already present, which is the case the old check would have called a success. The retry worked.
• The running server saw Codex 56 seconds after the install, which is what the last screen's "within a few minutes" rests on (see Known limits).

The process side, in cargo test on that Mac: a reader that goes away leaves the install running, the next reader replays it, Cancel kills what the installer started, including subshells, and a failure reports its first error. An agent run is never taken for an install, and a second run of either kind is refused. 130 pass, plus cargo clippy -D warnings.

The screens: test/desktop-connect-install.test.ts runs the real connect.html against a fake native side, 72 tests, including the exact spelling of every message the page sends. That spelling matters: deny_unknown_fields on the Rust side silently drops a command with a misspelled field, so policy.rs pins the same spelling from its side.

The installer: new drives of the real functions in test/install-sh-invariants.test.ts, a step in CI's bash:3.2 container, and the phase order is pinned against the page. That container's preflight check from this PR's first commit never tested anything: its child run inherited CODEMAN_INSTALL_SH_LIB and stopped at the sourcing guard, and a false [[ ]] does not trip set -e on bash 3.2. It is fixed here, and both checks were shown to fail when they should.

Not tested

• The agent chooser in the real window. The test Mac already had Claude Code, so the chooser step never showed there, and Add a coding agent and its menu item have not been clicked. They ran in Chromium and in cargo test.
• Quitting the app during an install. Replay is tested with a reader going away, not with the real app exiting under launchd.
• A real standard (non-admin) macOS account, also still open from feat(install): install without administrator rights (--no-admin) #768.

Known limits, left for later

• A new agent can take a few minutes to show up in a running Codeman. The server remembers that a CLI is missing, for up to 5 minutes after it last looked, so that a status poll never spawns a login shell, and Run reads that same memory. Only the CLI management routes clear it, and those are off by default. So the app's last screen says it can take a few minutes, and an open page needs a reload. fix(cli): a running server notices a CLI the installer just added #778, stacked on this PR, makes a running server notice at once.
• OMP is not offered, also on a Mac with Homebrew: its macOS install is Homebrew, and the app stays on the no-admin route.
• Agents that install with npm use whichever Node.js the login shell finds. On a Mac whose Node.js came from the nodejs.org installer, /usr/local/lib/node_modules belongs to root, so they would be expected to fail with npm's permission error, while the agents with their own installer still work. This has not been tried: both Mac runs used the Node.js the installer downloaded.
• Reaching Codeman stops at the local network: Tailscale needs its own login and setup, which the installer does at a terminal.
• An agent that only .zshrc can find (nvm, say) counts as missing, because the app reads the login shell's environment, as its own server start does. Installing it again is harmless.
• The bash 3.2 step in CI has 10 more bare [[ ]] checks from earlier installer work that a failure would walk past, for the reason above. They are not changed here.

The README's limits and docs/architecture-invariants.md carry the rest.