GitHub - registered2nd/Claudeman: Manage Claude Code in Tmux Sessions in a modern WebUI

The missing control plane for Claude Code

24/7 Autonomous Sessions • Live Agent Visualization • Zero-Lag Input Overlay • Mobile-First UI • Respawn Controller • Multi-Session Dashboard • Ralph Loop Tracking

Quick Start

Requirements: Node.js 18+, Claude CLI, tmux (apt install tmux / brew install tmux)

npm install -g claudeman
claudeman web
# Open http://localhost:3000 — press Ctrl+Enter to start your first session

npm install -g installs the claudeman CLI globally. It does not start a service — you run claudeman web to start the web server. Stop it with Ctrl+C.

Full installer (auto-installs dependencies)

If you don't have Node.js or tmux yet, the install script handles everything:

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

This installs Node.js, tmux, and Claude CLI if missing, clones Claudeman to ~/.claudeman/app, builds it, and optionally sets up a systemd service (Linux) for auto-start. After install, run claudeman web.

Run as a background service

Linux (systemd):

# The install script offers this automatically, or set it up manually:
mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/claudeman-web.service << EOF
[Unit]
Description=Claudeman Web Server
After=network.target

[Service]
Type=simple
ExecStart=$(which node) $(which claudeman) web
Restart=always
RestartSec=10

[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable --now claudeman-web
loginctl enable-linger $USER  # survive logout

macOS (launchd):

mkdir -p ~/Library/LaunchAgents
cat > ~/Library/LaunchAgents/com.claudeman.web.plist << EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.claudeman.web</string>
    <key>ProgramArguments</key>
    <array>
        <string>$(which node)</string>
        <string>$(which claudeman)</string>
        <string>web</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/claudeman.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/claudeman.log</string>
</dict>
</plist>
EOF

launchctl load ~/Library/LaunchAgents/com.claudeman.web.plist

Windows (WSL)

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

Claudeman 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 Claude CLI inside WSL: curl -fsSL https://claude.ai/install.sh | bash. After installing, http://localhost:3000 is accessible from your Windows browser.

Live Agent Visualization

Watch Claude's background agents work in real-time. Claudeman monitors every Task tool invocation 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 Claude Code remotely (VPN, Tailscale, SSH tunnel), every keystroke normally takes 200-300ms to round-trip. Claudeman implements a Mosh-inspired local echo system that makes typing feel instant regardless of latency.

A pixel-perfect DOM overlay inside xterm.js renders keystrokes at 0ms. Background forwarding silently sends every character to the PTY in 50ms debounced batches, so Tab completion, Ctrl+R history search, and all shell features work normally. When the server echo arrives 200-300ms later, the overlay seamlessly disappears and the real terminal text takes over — the transition is invisible.

Ink-proof architecture — lives as a <span> at z-index 7 inside .xterm-screen, completely immune to Ink's constant screen redraws (two previous attempts using terminal.write() failed because Ink corrupts injected buffer content)
Font-matched rendering — reads fontFamily, fontSize, fontWeight, and letterSpacing from xterm.js computed styles so overlay text is visually indistinguishable from real terminal output
Full editing — backspace, retype, paste (multi-char), cursor tracking, multi-line wrap when input exceeds terminal width
Persistent across reconnects — unsent input survives page reloads via localStorage
Enabled by default — works on both desktop and mobile, during idle and busy sessions

Extracted as a standalone library: xterm-zerolag-input — see Published Packages.

Mobile-Optimized Web UI

The most responsive Claude Code experience on any phone. Full xterm.js terminal with local echo, swipe navigation, and a touch-optimized interface designed for real remote work.

Terminal Apps	Claudeman Mobile
200-300ms input lag over remote	Local echo — instant feedback
Tiny text, no context	Full xterm.js terminal, responsive layout
No session management	Swipe between sessions, status badges
No notifications	Push alerts for approvals and idle
Manual reconnect after drops	tmux persistence — sessions survive anything
No agent visibility	Background agents in real-time
Copy-paste slash commands	One-tap `/init`, `/clear`, `/compact` buttons

Swipe navigation — left/right on the terminal to switch sessions (80px threshold, 300ms)
Keyboard accessory bar — /init, /clear, /compact quick-action buttons appear above the virtual keyboard with confirmation dialogs for destructive commands
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

claudeman 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.

Respawn Controller

The core of autonomous work. When Claude goes idle, the Respawn Controller detects it, sends a continue prompt, cycles /clear -> /init for fresh context, and resumes — running 24+ hours completely unattended.

WATCHING → IDLE DETECTED → SEND UPDATE → /clear → /init → CONTINUE → WATCHING

Multi-layer idle detection — completion messages, AI-powered idle check, output silence, token stability
Circuit breaker — prevents respawn thrashing when Claude is stuck (CLOSED -> HALF_OPEN -> OPEN states, tracks consecutive no-progress and repeated errors)
Health scoring — 0-100 health score with component scores for cycle success, circuit breaker state, iteration progress, and stuck recovery
Built-in presets — solo-work (3s idle, 60min), subagent-workflow (45s, 240min), team-lead (90s, 480min), ralph-todo (8s, 480min), overnight-autonomous (10s, 480min)

Multi-Session Dashboard

Run 20 parallel sessions with full visibility — real-time xterm.js terminals at 60fps, per-session token and cost tracking, tab-based navigation, and one-click management.

Persistent Sessions

Every session runs inside tmux — sessions survive server restarts, network drops, and machine sleep. Auto-recovery on startup with dual redundancy. Ghost session discovery finds orphaned tmux sessions. Claude knows it's managed and won't kill its own session.

Smart Token Management

Threshold	Action	Result
110k tokens	Auto `/compact`	Context summarized, work continues
140k tokens	Auto `/clear`	Fresh start with `/init`

Notifications

Real-time desktop alerts when sessions need attention — permission_prompt and elicitation_dialog trigger critical red tab blinks, idle_prompt triggers yellow blinks. Click any notification to jump directly to the affected session. Hooks auto-configured per case directory.

Ralph / Todo Tracking

Auto-detects Ralph Loops, <promise> tags, TodoWrite progress (4/9 complete), and iteration counters ([5/50]) with real-time progress rings and elapsed time tracking.

Run Summary

Click the chart icon on any session tab to see a timeline of everything that happened — respawn cycles, token milestones, auto-compact triggers, idle/working transitions, hook events, errors, and more.

Zero-Flicker Terminal

Claude Code uses Ink (React for terminals) which redraws the entire screen on every state change. Claudeman implements a 6-layer anti-flicker pipeline for smooth 60fps output across all sessions:

PTY Output → 16ms Server Batch → DEC 2026 Wrap → SSE → Client rAF → xterm.js (60fps)

SSH Alternative (`sc`)

If you prefer SSH (Termius, Blink, etc.), the sc command is a thumb-friendly session chooser:

sc              # Interactive chooser
sc 2            # Quick attach to session 2
sc -l           # List sessions

Single-digit selection (1-9), color-coded status, token counts, auto-refresh. Detach with Ctrl+A D.

Keyboard Shortcuts

Shortcut	Action
`Ctrl+Enter`	Quick-start session
`Ctrl+W`	Close session
`Ctrl+Tab`	Next session
`Ctrl+K`	Kill all sessions
`Ctrl+L`	Clear terminal
`Ctrl+Shift+R`	Restore terminal size
`Ctrl/Cmd +/-`	Font size
`Escape`	Close panels

API

Sessions

Method	Endpoint	Description
`GET`	`/api/sessions`	List all
`POST`	`/api/quick-start`	Create case + start session
`DELETE`	`/api/sessions/:id`	Delete session
`POST`	`/api/sessions/:id/input`	Send input

Respawn

Method	Endpoint	Description
`POST`	`/api/sessions/:id/respawn/enable`	Enable with config + timer
`POST`	`/api/sessions/:id/respawn/stop`	Stop controller
`PUT`	`/api/sessions/:id/respawn/config`	Update config

Ralph / Todo

Method	Endpoint	Description
`GET`	`/api/sessions/:id/ralph-state`	Get loop state + todos
`POST`	`/api/sessions/:id/ralph-config`	Configure tracking

Subagents

Method	Endpoint	Description
`GET`	`/api/subagents`	List all background agents
`GET`	`/api/subagents/:id`	Agent info and status
`GET`	`/api/subagents/:id/transcript`	Full activity transcript
`DELETE`	`/api/subagents/:id`	Kill agent process

System

Method	Endpoint	Description
`GET`	`/api/events`	SSE stream
`GET`	`/api/status`	Full app state
`POST`	`/api/hook-event`	Hook callbacks
`GET`	`/api/sessions/:id/run-summary`	Timeline + stats

Architecture

flowchart TB
    subgraph Claudeman["CLAUDEMAN"]
        subgraph Frontend["Frontend Layer"]
            UI["Web UI<br/><small>xterm.js + Agent Windows</small>"]
            API["REST API<br/><small>Fastify</small>"]
            SSE["SSE Events<br/><small>/api/events</small>"]
        end

        subgraph Core["Core Layer"]
            SM["Session Manager"]
            S1["Session (PTY)"]
            S2["Session (PTY)"]
            RC["Respawn Controller"]
        end

        subgraph Detection["Detection Layer"]
            RT["Ralph Tracker"]
            SW["Subagent Watcher<br/><small>~/.claude/projects/*/subagents</small>"]
        end

        subgraph Persistence["Persistence Layer"]
            SCR["Mux Manager<br/><small>(tmux)</small>"]
            SS["State Store<br/><small>state.json</small>"]
        end

        subgraph External["External"]
            CLI["Claude CLI"]
            BG["Background Agents<br/><small>(Task tool)</small>"]
        end
    end

    UI <--> API
    API <--> SSE
    API --> SM
    SM --> S1
    SM --> S2
    SM --> RC
    SM --> SS
    S1 --> RT
    S1 --> SCR
    S2 --> SCR
    RC --> SCR
    SCR --> CLI
    SW --> BG
    SW --> SSE

Development

npm install
npx tsx src/index.ts web    # Dev mode
npm run build               # Production build
npm test                    # Run tests

See CLAUDE.md for full documentation.

Published Packages

`xterm-zerolag-input`

Instant keystroke feedback overlay for xterm.js. Eliminates perceived input latency over high-RTT connections by rendering typed characters immediately as a pixel-perfect DOM overlay. Zero dependencies, configurable prompt detection, full state machine with 78 tests.

npm install xterm-zerolag-input

Full documentation

License

MIT — see LICENSE

Track sessions. Visualize agents. Control respawn. Let it run while you sleep.

Name		Name	Last commit message	Last commit date
Latest commit History 680 Commits
agent-teams		agent-teams
docs		docs
mobile-test		mobile-test
packages/xterm-zerolag-input		packages/xterm-zerolag-input
scripts		scripts
src		src
test		test
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
install.sh		install.sh
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

The missing control plane for Claude Code

Quick Start

Live Agent Visualization

Zero-Lag Input Overlay

Mobile-Optimized Web UI

Respawn Controller

Multi-Session Dashboard

Persistent Sessions

Smart Token Management

Notifications

Ralph / Todo Tracking

Run Summary

Zero-Flicker Terminal

SSH Alternative (`sc`)

Keyboard Shortcuts

API

Sessions

Respawn

Ralph / Todo

Subagents

System

Architecture

Development

Published Packages

`xterm-zerolag-input`

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

License

registered2nd/Claudeman

Folders and files

Latest commit

History

Repository files navigation

The missing control plane for Claude Code

Quick Start

Live Agent Visualization

Zero-Lag Input Overlay

Mobile-Optimized Web UI

Respawn Controller

Multi-Session Dashboard

Persistent Sessions

Smart Token Management

Notifications

Ralph / Todo Tracking

Run Summary

Zero-Flicker Terminal

SSH Alternative (sc)

Keyboard Shortcuts

API

Sessions

Respawn

Ralph / Todo

Subagents

System

Architecture

Development

Published Packages

xterm-zerolag-input

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

SSH Alternative (`sc`)

`xterm-zerolag-input`

Packages