GitHub - Ark0N/Claudeman: Manage Claude Code in GNU Screen Sessions in a modern WebUI

Manage Claude Code sessions better than ever

Autonomous Claude Code work while you sleep
Persistent sessions, Ralph Loop tracking, Respawn Controller, Agent Visualization, Multi-Session Dashboards

What Claudeman Does

🔔 Notification System

Real-time desktop notifications when sessions need attention — never miss a permission prompt or idle session again:

Hook Event	Urgency	Tab Alert	Meaning
`permission_prompt`	Critical	Red blink	Claude needs tool approval
`elicitation_dialog`	Critical	Red blink	Claude is asking a question
`idle_prompt`	Warning	Yellow blink	Session idle, waiting for input
`stop`	Info	—	Response complete

Features:

Browser notifications enabled by default (auto-requests permission)
Click any notification to jump directly to the affected session
Tab blinking alerts: red for action-required, yellow for idle
Notifications include actual context (tool name, command, question text)
Hooks are auto-configured per case directory (.claude/settings.local.json)
Works on HTTP for local use (localhost is a secure context)

💾 Persistent Screen Sessions

Every Claude session runs inside GNU Screen — sessions survive server restarts, network drops, and machine sleep.

# Your sessions are always recoverable
CLAUDEMAN_SCREEN=1
CLAUDEMAN_SESSION_ID=abc-123-def
CLAUDEMAN_SCREEN_NAME=claudeman-myproject

Sessions auto-recover on startup (dual redundancy: state.json + screens.json)
All settings (respawn, auto-compact, tokens) survive server restarts
Ghost session discovery finds orphaned screens
Claude knows it's managed (won't kill its own screen)

🔄 Respawn Controller

The core of autonomous work. When Claude becomes idle, the Respawn Controller kicks in:

WATCHING → IDLE DETECTED → SEND UPDATE → CLEAR → INIT → CONTINUE
    ↑                                                      │
    └──────────────────────────────────────────────────────┘

Multi-layer idle detection (completion messages, output silence, token stability)
Sends configurable update prompts to continue work
Auto-cycles /clear → /init for fresh context
Step confirmation (5s silence) between each command
Keeps working even when Ralph loops stop
Run for 24+ hours completely unattended

# Enable respawn with 8-hour timer
curl -X POST localhost:3000/api/sessions/:id/respawn/enable \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "updatePrompt": "continue improving the codebase",
      "idleTimeoutMs": 5000
    },
    "durationMinutes": 480
  }'

🎯 Ralph / Todo Tracking

Claudeman detects and tracks Ralph Loops and Todos inside Claude Code:

Auto-detects:

Pattern	Example
Promise tags	`<promise>COMPLETE</promise>`
Custom phrases	`<promise>ALL_TASKS_DONE</promise>`
TodoWrite	`- [ ] Task`, `- [x] Done`
Iterations	`[5/50]`, `Iteration 5 of 50`

Tracks in real-time:

Completion phrase detection
Todo progress (4/9 complete)
Progress percentage ring
Elapsed time

👁️ Live Agent Visualization

Watch your agents work in real-time. Claudeman monitors Claude Code's background agents (the Task tool) and displays them in draggable floating windows with Matrix-style connection lines.

┌─────────────────────────────────────────────────────────────┐
│  Session Tab [AGENTS (3)]                                   │
│      │                                                      │
│      │ ╭──────────────────╮  ╭──────────────────╮          │
│      ├─┤ Agent: explore   │  │ Agent: implement │          │
│      │ │ ● active         │  │ ○ completed      │          │
│      │ │ Tool: Grep       │  │ Result: success  │          │
│      │ ╰──────────────────╯  ╰──────────────────╯          │
│      │         ╭──────────────────╮                        │
│      └─────────┤ Agent: test      │                        │
│                │ ◐ idle           │                        │
│                ╰──────────────────╯                        │
└─────────────────────────────────────────────────────────────┘

Features:

Floating windows — Draggable, resizable panels for each agent
Connection lines — Animated green lines linking parent sessions to agent windows
Live activity log — See every tool call, progress update, and message in real-time
Status indicators — Green (active), yellow (idle), blue (completed)
Model badges — Shows Haiku/Sonnet/Opus with color coding
Auto-behavior — Windows auto-open on spawn, auto-minimize on completion
Tab badge — Shows "AGENT" or "AGENTS (n)" count on session tabs

Subagent API:

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

🔍 Project Insights Panel

Real-time visibility into what Claude is reading and searching:

Active Bash tools displayed as they run (file viewers, grep, find)
Clickable file paths — Jump directly to files in Claude Code
Timeout indicators — See how long tools have been running
Smart deduplication — Overlapping file ranges collapsed

Toggle via App Settings → Display → "Show Project Insights Panel"

📊 Smart Token Management

Never hit token limits unexpectedly:

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

# Configure per-session
curl -X POST localhost:3000/api/sessions/:id/auto-compact \
  -d '{"enabled": true, "threshold": 100000}'

🖥️ Multi-Session Dashboard

Run 20 parallel sessions with full visibility:

Real-time xterm.js terminals (60fps streaming)
Per-session token and cost tracking
Tab-based navigation
One-click session management

Monitor Panel — Real-time screen session monitoring with memory, CPU, and process info:

⚡ Zero-Flicker Terminal Rendering

The problem: Claude Code uses Ink (React for terminals), which redraws the entire screen on every state change. Without special handling, you'd see constant flickering — unusable for monitoring multiple sessions.

The solution: Claudeman implements a 6-layer antiflicker system that delivers butter-smooth 60fps terminal output:

PTY Output → 16ms Batch → DEC 2026 Wrap → SSE → rAF Batch → xterm.js → 60fps Canvas

How Each Layer Works

Layer	Location	Technique	Purpose
1. Server Batching	server.ts	16ms collection window	Combines rapid PTY writes into single packets
2. DEC Mode 2026	server.ts	`\x1b[?2026h`...`\x1b[?2026l`	Marks atomic update boundaries (terminal standard)
3. Client rAF	app.js	`requestAnimationFrame`	Syncs writes to 60Hz display refresh
4. Sync Block Parser	app.js	DEC 2026 extraction	Parses atomic segments for xterm.js
5. Flicker Filter	app.js	Ink pattern detection	Buffers screen-clear sequences (optional)
6. Chunked Loading	app.js	64KB/frame writes	Large buffers don't freeze UI

Technical Implementation

Server-side (16ms batching + DEC 2026):

// Accumulate PTY output per-session
const newBatch = existing + data;
terminalBatches.set(sessionId, newBatch);

// Flush every 16ms (60fps) or immediately if >1KB
if (!terminalBatchTimer) {
  terminalBatchTimer = setTimeout(() => {
    for (const [id, data] of terminalBatches) {
      // Wrap with synchronized output markers
      const syncData = '\x1b[?2026h' + data + '\x1b[?2026l';
      broadcast('session:terminal', { id, data: syncData });
    }
    terminalBatches.clear();
  }, 16);
}

Client-side (rAF batching + sync block handling):

batchTerminalWrite(data) {
  pendingWrites += data;

  if (!writeFrameScheduled) {
    writeFrameScheduled = true;
    requestAnimationFrame(() => {
      // Wait up to 50ms for incomplete sync blocks
      if (hasStartMarker && !hasEndMarker) {
        setTimeout(flushPendingWrites, 50);
        return;
      }

      // Extract atomic segments, strip markers, write to xterm
      const segments = extractSyncSegments(pendingWrites);
      for (const segment of segments) {
        terminal.write(segment);
      }
    });
  }
}

Optional flicker filter detects Ink's screen-clear patterns (ESC[2J, ESC[H ESC[J) and buffers 50ms of subsequent output for extra smoothness on problematic terminals.

Result: Watch 20 Claude sessions simultaneously without any visual artifacts, even during heavy tool use.

📈 Run Summary ("What Happened While You Were Away")

Click the chart icon on any session tab to see a complete timeline of what happened:

Tracked Events:

Session start/stop and respawn cycles
Idle/working transitions with durations
Token milestones (every 50k tokens)
Auto-compact and auto-clear triggers
Ralph Loop completions
AI check results (idle detection verdicts)
Hook events (permissions, questions, stops)
Errors, warnings, and stuck-state alerts

Stats at a glance:

Total respawn cycles
Peak token usage
Active vs idle time
Error/warning counts

Installation

macOS & Linux

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

npm (alternative)

npm install -g claudeman

Requirements

Node.js 18+
Claude CLI installed
GNU Screen (apt install screen / brew install screen)

Getting Started

claudeman web
# Open http://localhost:3000
# Press Ctrl+Enter to start your first session

Note: HTTP works fine for local use since localhost is treated as a secure context by browsers. Use --https only when accessing from another machine on your network.

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

Mobile Access (Termius/SSH)

Claudeman Screens (sc) is a mobile-friendly screen session chooser, optimized for Termius on iPhone.

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

Features:

Single-digit selection (1-9) for fast thumb typing
Color-coded status indicators (attached/detached/respawn)
Token count display
Session names from Claudeman state
Pagination for many sessions
Auto-refresh every 60 seconds

Indicators:

Symbol	Meaning
`*` / `●`	Attached (someone connected)
`-` / `○`	Detached (available)
`R`	Respawn enabled
`45k`	Token count

Tip: Detach from a screen with Ctrl+A D

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 Tracking

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

Subagents (Claude Code Background Agents)

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
`GET`	`/api/sessions/:id/subagents`	Subagents for session's working dir

Hooks & Notifications

Method	Endpoint	Description
`POST`	`/api/hook-event`	Hook callbacks `{event, sessionId, data?}` → notifications + tab alerts

Run Summary

Method	Endpoint	Description
`GET`	`/api/sessions/:id/run-summary`	Timeline + stats for "what happened"

Real-Time

Method	Endpoint	Description
`GET`	`/api/events`	SSE stream
`GET`	`/api/status`	Full app state

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["GNU Screen Manager"]
            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

Performance

Optimized for long-running autonomous sessions:

Feature	Implementation
60fps terminal	16ms server batching, `requestAnimationFrame` client
Memory management	Auto-trimming buffers (2MB terminal, 1MB text)
Event debouncing	50-500ms on rapid state changes
State persistence	Debounced writes, dual-redundancy recovery

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.

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 515 Commits
docs		docs
scripts		scripts
src		src
test-results		test-results
test-screenshots		test-screenshots
test		test
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
check-tabs.js		check-tabs.js
install.sh		install.sh
mobile-app-plan.json		mobile-app-plan.json
package-lock.json		package-lock.json
package.json		package.json
respawn-monitor.sh		respawn-monitor.sh
test-links.cjs		test-links.cjs
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

License

Ark0N/Claudeman

Folders and files

Latest commit

History

Repository files navigation

Manage Claude Code sessions better than ever

What Claudeman Does

🔔 Notification System

💾 Persistent Screen Sessions

🔄 Respawn Controller

🎯 Ralph / Todo Tracking

👁️ Live Agent Visualization

🔍 Project Insights Panel

📊 Smart Token Management

🖥️ Multi-Session Dashboard

⚡ Zero-Flicker Terminal Rendering

How Each Layer Works

Technical Implementation

📈 Run Summary ("What Happened While You Were Away")

Installation

macOS & Linux

npm (alternative)

Requirements

Getting Started

Keyboard Shortcuts

Mobile Access (Termius/SSH)

API

Sessions

Respawn

Ralph / Todo Tracking

Subagents (Claude Code Background Agents)

Hooks & Notifications

Run Summary

Real-Time

Architecture

Performance

Development

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Uh oh!

Languages

Packages