Codeman: Self-Hosted Mission Control for Claude Code, Codex and Gemini CLI

What Codeman is for, and who it is not for

Codeman is a self-hosted control plane that wraps command-line AI coding agents. The README lists seven it can spawn per session: Claude Code, OpenCode, Codex, Antigravity, Gemini, Pi, and Grok, plus a plain shell. The problem it addresses is not code generation. It is the operational gap around code generation: an agent that stops when it hits a usage limit, a terminal that dies when your SSH connection drops, and no way to see what a background agent is doing without keeping a laptop open.

The people this fits are those already running one of those CLIs on a machine that stays powered on. A home server, a workstation, a small VPS. The README frames the target use case as "24+ hour unattended runs". If you open Claude Code in one terminal, watch it, and close the window when you are done, Codeman adds a server, a browser UI, and a persistence layer you will not use.

It is explicitly not a hosted product. The README states it is loopback-only by default, MIT licensed, with no telemetry, and that it runs entirely on your machine. There is no account, and no vendor-side component to trust. That is the whole value proposition and also the whole support burden.

How the tmux session model actually works

The mechanism is tmux. Codeman spawns each agent inside a persistent tmux session, then streams that session's terminal to a browser. Nothing about the agent itself is reimplemented. Claude Code runs as Claude Code; Codeman owns the pty, the session lifetime, and the transport to the client.

That choice explains most of the feature list. tmux persistence is why a session survives a restart or a network drop. Full-scrollback replay is possible because tmux keeps the buffer. The README also claims "exactly-once input delivery", which is the harder half: a browser terminal that reconnects must not resend keystrokes the agent already consumed.

The server is Fastify on Node.js, written in TypeScript. node-pty provides the pty layer. The README notes that node-pty ships no Linux prebuilds, so it compiles from source during install, which is why a build toolchain is a prerequisite rather than an optional extra.

On top of the terminal sits the automation layer. The README describes idle detection with respawn cycling, and auto-resume when a subscription limit resets. Both are policy decisions made by Codeman, not by the underlying CLI. A separate feature, live floating windows for subagents and teammates, depends on Codeman parsing agent output well enough to render a per-subagent view alongside the raw terminal.

Installing Codeman and starting a first session

The documented path is a single curl line for macOS and Linux, with Windows supported through WSL. The installer prompts before every system change, so nothing is installed silently.

curl -fsSL https://getcodeman.com/install | bash

According to the README, this installs Node.js, tmux, and a build toolchain if any are missing, clones the app to `~/.codeman/app`, and builds it. At the end a menu asks whether to run Codeman in the current terminal, install it as a background service via systemd or launchd, or stop. Nothing runs in the background unless you choose that option.

The installer also asks how the dashboard should be reachable, offering Tailscale, any device on your network, or this machine only. The network option binds to `0.0.0.0` and the README says a password is strongly recommended; skipping it requires an explicit confirmation. If you start the server by hand instead, it defaults to loopback.

codeman web
# Open http://localhost:3000 and start your first session

The README gives port 3000 as the default. You need at least one of the seven CLIs installed first; the installer detects whichever are present and, if it finds none, offers to install Claude Code or OpenCode. To keep the server alive after the shell exits, the README documents a detach flag and a status check.

codeman web -d          # detach; logs to ~/.codeman/web.log
codeman web --status    # is it up, and on which pid
codeman web --stop      # graceful SIGTERM; agents keep running in tmux

That last comment is the part worth internalising: stopping the web server does not stop the agents. They continue inside tmux until you kill the sessions themselves.

The network binding decision is the real security surface

Codeman is a terminal in a browser. Anyone who reaches the dashboard reaches a shell running as your user, with your SSH keys and your repository checkouts. The installer treats this accordingly, and the README is direct about the trade-off.

Three options are offered. Tailscale binds to loopback and fronts it with `tailscale serve`, giving an HTTPS URL on your tailnet with a real certificate, and the tailnet membership acts as the login, so no password is needed. Binding to `0.0.0.0` exposes the dashboard to every device on the network and prompts for a password. The loopback option is described as the safest and is what a hand-started `codeman web` uses.

The README notes that skipping the password on a network bind requires an explicit confirmation and ends with a loud warning. That is a reasonable design: the dangerous path exists, but it is not the default and it is not quiet.

There is a gap worth naming. The README does not document TLS termination for the `0.0.0.0` option. On a home LAN that may be acceptable. On a network you do not fully control, the Tailscale path is the one the documentation actually supports end to end, and the plain network bind is the one you should treat as a deliberate risk rather than a convenience.

Multi-user mode and what it does not cover

For small teams, Codeman offers an opt-in multi-user mode. The README documents creating a first admin account and then starting the server with a flag.

codeman users add alice --admin      # create the first admin account
codeman web --multiuser              # named logins + per-user case spaces

The stated behaviour is named logins and per-user workspace separation. What the README does not document is any notion of roles beyond the `--admin` flag on account creation, or any audit trail of who ran which agent command. If your reason for wanting multi-user mode is compliance rather than convenience, the documented feature set does not reach that far.

This is also where the tmux model creates a subtlety. Sessions are tmux sessions on one host under one Unix user, unless the deployment isolates them further. Per-user case spaces are a UI and data separation, and the README does not describe OS-level isolation between users. Treat multi-user mode as a way to stop teammates from stepping on each other's work, not as a security boundary between them.

Where Codeman is the wrong tool

The clearest mismatch is editor-centric work. If your loop is open a file, ask the agent about that file, apply the diff, Codeman's browser terminal is a worse interface than the editor plugin you already have. The README's own emphasis is unattended runs, not interactive pair editing.

A second mismatch is the install footprint. The README is explicit that node-pty has no Linux prebuilds and compiles from source, so the installer pulls in Node.js, tmux, and a build toolchain. On a locked-down corporate machine where you cannot install packages, the installer will abort: the README states that without a terminal attached, steps that would change the system abort with instructions instead of running silently, and that `CODEMAN_NONINTERACTIVE=1` approves them for automation. That variable is for CI, not for getting around a policy you do not control.

The third is the automation itself. Idle detection with respawn cycling means Codeman will re-prompt an agent that has gone quiet. That is the feature, and it is also the failure mode. An agent that is stuck in a loop, or waiting on a decision you have not made, gets pushed forward rather than left alone. The README documents the behaviour and the conditions under which it triggers; it does not document a global kill switch for the automation layer separate from stopping the server. If you want an agent to stop and wait for you, this is the wrong tool.

One more boundary: the README notes that Gemini CLI is enterprise-only since Google's consumer cutover, and that Antigravity is its successor. Any workflow built on the Gemini CLI entry point inherits that constraint from Google, not from Codeman.

How Codeman differs from Claude Squad and a bare tmux setup

The comparison people search for is Claude Squad alternatives, and the honest answer is that the two sit at different layers. A session multiplexer such as Claude Squad manages several agent instances from a terminal. Codeman manages several agent instances and puts a web dashboard, a phone-optimised terminal, and a scheduling and respawn layer on top. If you live in a terminal and only need to juggle concurrent agents, the multiplexer is less software for the same core job.

The other alternative is doing it yourself with tmux and a reverse proxy. That gets you persistence and remote access, and it is genuinely close for a single user on a trusted network. What it does not get you is the parts Codeman builds on top: idle detection with respawn cycling, auto-resume when a usage limit resets, scheduled jobs, live per-subagent windows, push notifications, and a touch-optimised terminal with local echo. Whether those are worth a Node server and a build step depends entirely on whether you actually run agents unattended.

The distinguishing constraint is the seven-CLI list. Codeman is not tied to one vendor's agent. The README states any combination of Claude Code, OpenCode, Codex, Antigravity, Gemini, Pi, and Grok works, and that the installer detects whichever are present. A tool built around a single CLI cannot make that claim, and in a field where the CLIs change monthly, that breadth is the more durable part of the design.

Maintenance, updates and the MIT licence

Codeman is not archived, and its last push was on 2026-08-27. Releases are frequent: 1.23.0 on 2026-08-25, 1.23.1 on 2026-08-26, and 1.23.2 on 2026-08-27. The `package.json` in the repository shows version 1.28.2, which is ahead of the release list, so the published npm package and the repository head are not necessarily the same commit.

Updating is handled by the installer. The README states that re-running the same one-liner updates a finished install in place, that local changes in `~/.codeman/app` are stashed rather than discarded, and that a running service is restarted and verified. `install.sh update` and `install.sh uninstall` also exist. That is a lower upgrade cost than most self-hosted tools, because there is no separate migration step documented.

The operational cost is the build toolchain. A source build of node-pty means upgrades are not instant, and it means the machine needs a compiler available at update time, not just at first install. If you install as a service, the README notes that `service install` bakes your current PATH into the unit file, which matters because launchd hands a job `/usr/bin:/bin:/usr/sbin:/sbin` and a Homebrew or nvm `node`, `tmux`, or `claude` would otherwise be invisible.

The licence is MIT. That permits commercial use and modification, and it comes with no warranty. The README also states there is no telemetry, which is a factual claim about the software rather than a legal one. One licence-adjacent detail the README calls out: it never copies `CODEMAN_PASSWORD` into the generated unit file, so if the service needs auth you add that yourself. Whether that matters for your deployment is a question for your own review, not something this article can settle.

Editorial conclusion

Adopt Codeman if you already run one or more of the seven supported CLIs on a machine that stays on, and you want the terminal reachable from a phone without exposing it to the internet. Skip it if you work inside a single editor session, if you cannot install tmux or a build toolchain, or if you do not want an agent re-prompting itself while you are away. Before committing, verify three things on your own machine: that the installer detects your CLI, that a session survives a browser reload, and that `codeman web --multiuser` gives each teammate a separate workspace if you plan to share it.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes