<p align="center"> <img src="docs/images/codeman-title.svg" alt="Codeman" height="60"> </p> <h2 align="center">The missing control plane for AI coding agents</h2> <p align="center"> <em>Agent Visualization • Zero-Lag Input Overlay • Mobile-First UI • Respawn Controller • Multi-Session Dashboard </em> </p> <p align="center"> <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-1e3a5f?style=flat-square" alt="License: MIT"></a> <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-18%2B-22c55e?style=flat-square&logo=node.js&logoColor=white" alt="Node.js 18+"></a> <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.9-3b82f6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript 5.9"></a> <a href="https://fastify.dev/"><img src="https://img.shields.io/badge/Fastify-5.x-1e3a5f?style=flat-square&logo=fastify&logoColor=white" alt="Fastify"></a> <img src="https://img.shields.io/badge/Tests-1435%20total-22c55e?style=flat-square" alt="Tests"> </p> <p align="center"> <img src="docs/images/subagent-demo.gif" alt="Codeman — parallel subagent visualization" width="900"> </p>

Quick Start - Installation

curl -fsSL https://raw.githubusercontent.com/Ark0N/Codeman/master/install.sh | bash

This installs Node.js and tmux if missing, clones Codeman to ~/.codeman/app, and builds it.

Install from a fork or specific branch:

curl -fsSL https://raw.githubusercontent.com/<user>/Codeman/<branch>/install.sh | \
  CODEMAN_REPO_URL=https://github.com/<user>/Codeman.git \
  CODEMAN_BRANCH=<branch> bash

The installer supports these environment variables:

| Variable | Default | Description | |----------|---------|-------------| | CODEMAN_REPO_URL | upstream Codeman | Custom git repository URL | | CODEMAN_BRANCH | master | Git branch to install | | CODEMAN_INSTALL_DIR | ~/.codeman/app | Custom install directory | | CODEMAN_SKIP_SYSTEMD | 0 | Skip systemd service setup prompt | | CODEMAN_NODE_VERSION | 22 | Node.js major version to install | | CODEMAN_NONINTERACTIVE | 0 | Skip all prompts (for CI/automation) |

You'll need at least one AI coding CLI installed — Claude Code or OpenCode (or both). After install:

codeman web
# Open http://localhost:3000 — press Ctrl+Enter to start your first session

<details> <summary><strong>Run as a background service</strong></summary>

Linux (systemd):

mkdir -p ~/.config/systemd/user && printf '[Unit]\nDescription=Codeman Web Server\nAfter=network.target\n\n[Service]\nType=simple\nExecStart=%s %s/dist/index.js web\nRestart=always\nRestartSec=10\n\n[Install]\nWantedBy=default.target\n' "$(which node)" "$HOME/.codeman/app" > ~/.config/systemd/user/codeman-web.service && systemctl --user daemon-reload && systemctl --user enable --now codeman-web && loginctl enable-linger $USER

macOS (launchd):

mkdir -p ~/Library/LaunchAgents && printf '<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0"><dict><key>Label</key><string>com.codeman.web</string><key>ProgramArguments</key><array><string>%s</string><string>%s/dist/index.js</string><string>web</string></array><key>RunAtLoad</key><true/><key>KeepAlive</key><true/><key>StandardOutPath</key><string>/tmp/codeman.log</string><key>StandardErrorPath</key><string>/tmp/codeman.log</string></dict></plist>\n' "$(which node)" "$HOME/.codeman/app" > ~/Library/LaunchAgents/com.codeman.web.plist && launchctl load ~/Library/LaunchAgents/com.codeman.web.plist

</details> <details> <summary><strong>Windows (WSL)</strong></summary>

wsl bash -c "curl -fsSL https://raw.githubusercontent.com/Ark0N/Codeman/master/install.sh | bash"

Codeman requires tmux, so Windows users need WSL. If you don't have WSL yet: run wsl --install in an admin PowerShell, reboot, open Ubuntu, then install your preferred AI coding CLI inside WSL (Claude Code or OpenCode). After installing, http://localhost:3000 is accessible from your Windows browser.

</details>

Mobile-Optimized Web UI

The most responsive AI coding agent experience on any phone. Full xterm.js terminal with local echo, swipe navigation, and a touch-optimized interface designed for real remote work — not a desktop UI crammed onto a small screen.

<table> <tr> <td align="center" width="33%"><img src="docs/screenshots/mobile-landing-qr.png" alt="Mobile — landing page with QR auth" width="260"></td> <td align="center" width="33%"><img src="docs/screenshots/mobile-session-idle.png" alt="Mobile — idle session with keyboard accessory" width="260"></td> <td align="center" width="33%"><img src="docs/screenshots/mobile-session-active.png" alt="Mobile — active agent session" width="260"></td> </tr> <tr> <td align="center"><em>Landing page with QR auth</em></td> <td align="center"><em>Keyboard accessory bar</em></td> <td align="center"><em>Agent working in real-time</em></td> </tr> </table> <table> <tr> <th>Terminal Apps</th> <th>Codeman Mobile</th> </tr> <tr><td>200-300ms input lag over remote</td><td><b>Local echo — instant feedback</b></td></tr> <tr><td>Tiny text, no context</td><td>Full xterm.js terminal</td></tr> <tr><td>No session management</td><td>Swipe between sessions</td></tr> <tr><td>No notifications</td><td>Push alerts for approvals and idle</td></tr> <tr><td>Manual reconnect</td><td>tmux persistence</td></tr> <tr><td>No agent visibility</td><td>Background agents in real-time</td></tr> <tr><td>Copy-paste slash commands</td><td>One-tap <code>/init</code>, <code>/clear</code>, <code>/compact</code></td></tr> <tr><td>Password typing on phone</td><td><b>QR code scan — instant auth</b></td></tr> </table>

Secure QR Code Authentication

Typing passwords on a phone keyboard is miserable. Codeman replaces it with cryptographically secure single-use QR tokens — scan the code displayed on your desktop and your phone is authenticated instantly.

Each QR encodes a URL containing a 6-character short code that maps to a 256-bit secret (crypto.randomBytes(32)) on the server. Tokens auto-rotate every 60 seconds, are atomically consumed on first scan (replays always fail), and use hash-based Map.get() lookup that leaks nothing through response timing. The short code is an opaque pointer — the real secret never appears in browser history, Referer headers, or Cloudflare edge logs.

The security design addresses all 6 critical QR auth flaws identified in "Demystifying the (In)Security of QR Code-based Login" (USENIX Security 2025, which found 47 of the top-100 websites vulnerable): single-use enforcement, short TTL, cryptographic randomness, server-side generation, real-time desktop notification on scan (QRLjacking detection), and IP + User-Agent session binding with manual revocation. Dual-layer rate limiting (per-IP + global) makes brute force infeasible across 62^6 = 56.8 billion possible codes. Full security analysis: docs/qr-auth-plan.md

Touch-Optimized Interface

Keyboard accessory bar — /init, /clear, /compact quick-action buttons above the virtual keyboard. Destructive commands (/clear, /compact) require a double-press to confirm — first tap arms the button, second tap executes — so you never fire one by accident on a bumpy commute
Swipe navigation — left/right on the terminal to switch sessions (80px threshold, 300ms)
Smart keyboard handling — toolbar and terminal shift up when keyboard opens (uses visualViewport API with 100px threshold for iOS address bar drift)
Safe area support — respects iPhone notch and home indicator via env(safe-area-inset-*)
44px touch targets — all buttons meet iOS Human Interface Guidelines minimum sizes
Bottom sheet case picker — slide-up modal replaces the desktop dropdown
Native momentum scrolling — -webkit-overflow-scrolling: touch for buttery scroll

codeman web --https
# Open on your phone: https://<your-ip>:3000

localhost works over plain HTTP. Use --https when accessing from another device, or use Tailscale (recommended) — it provides a private network so you can access http://<tailscale-ip>:3000 from your phone without TLS certificates.

Live Agent Visualization

Watch background agents work in real-time. Codeman monitors agent activity and displays each agent in a draggable floating window with animated Matrix-style connection lines back to the parent session.

Floating terminal windows — draggable, resizable panels for each agent with a live activity log showing every tool call, file read, and progress update as it happens
Connection lines — animated green lines linking parent sessions to their child agents, updating in real-time as agents spawn and complete
Status & model badges — green (active), yellow (idle), blue (completed) indicators with Haiku/Sonnet/Opus model color coding
Auto-behavior — windows auto-open on spawn, auto-minimize on completion, tab badge shows "AGENT" or "AGENTS (n)" count
Nested agents — supports 3-level hierarchies (lead session -> teammate agents -> sub-subagents)

Zero-Lag Input Overlay

When accessing your coding agent remotely (VPN, Tailscale, SSH tunnel),

Codeman

Install / Use

README