claudeman

Manage multiple Claude Code sessions using tmux.

Features

• Multi-session TUI - Monitor all Claude sessions in a terminal UI with real-time status updates
• Remote control via Telegram - Control sessions from anywhere via Telegram bot
• Claude suggestions - When Claude provides a suggestion after completing work, it appears as a button in Telegram for instant application
• Permission prompts as buttons - Prompts appear as interactive Telegram buttons showing tool type, command, and description
• Multi-session status - /status shows summary with drill-down buttons for multiple sessions, full log for single session

Install

npm install -g claudeman

Requires: Node.js >= 18, tmux, Claude Code CLI

Usage

claudeman                      # Open TUI
claudeman new <name>           # Create session in current directory
claudeman new <name> -c <path> # Create session at specific path
claudeman new <name> --attach  # Create and immediately attach
claudeman list                 # List all sessions
claudeman attach <name>        # Attach to session
claudeman kill <name>          # Kill session
claudeman status-json          # Output sessions status as JSON

TUI (Text User Interface)

Launch with claudeman (no arguments).

Navigation

• j / ↓ - Move down
• k / ↑ - Move up
• 1-99 - Jump directly to session number (type digits within 1 second)
• r - Refresh session list

Actions

• Enter - Attach to selected session
• p - Toggle preview (shows session output without attaching)
• d - Toggle auto-detach (auto-detach when Claude starts working after you attach)
• n - Toggle desktop notifications (notify when session finishes working)
• t - Toggle Telegram bot (if configured)
• q - Quit

Status Indicators

• working (yellow) - Claude is actively processing
• needs attention (green) - Claude is waiting for input

Telegram Bot

Control your Claude Code sessions remotely via a Telegram bot. Get notified when a session needs attention, view prompt options as inline buttons, and reply directly from Telegram.

Setup

1. Create a bot with @BotFather on Telegram and copy the bot token
2. Get your chat ID from @userinfobot
3. Run setup:

claudeman tg-setup

This saves your bot token, chat ID, and a projects directory (used by /clone) to ~/.claudeman/telegram.json.

Running the bot

The Telegram bot auto-starts when you open the TUI (claudeman) if configured. You can toggle it on/off with t in the TUI.

You can also run it standalone:

claudeman tg

The bot polls sessions every 2 seconds and sends you a Telegram message whenever a session transitions from working to needing attention.

Bot commands

| Command | Description | |---------|-------------| | /start | Show help and available commands | | /status | Show all sessions with status. Single session: shows full output. Multiple sessions: shows summary with buttons to drill down | | /create <path> | Create a new session at the given path (supports ~ for home directory) | | /clone <git_url> | Clone a repo into your projects directory and create a session |

Interacting with sessions

• Inline buttons - When a session shows a prompt with options, tap a button to respond
• Reply to a message - Reply to any session message to send text input to that session
• Direct messages - Send a message without replying to send to the most recent session (or one awaiting custom input)
• Custom input - Some prompts offer a "Type something else" or "Other" option; tap it, then send your text (no need to reply)

How notifications work

The bot polls sessions every 2 seconds. When a session transitions from working → needs attention, you receive a Telegram message with:

• Session name
• Latest Claude output (solution)
• Permission prompt buttons (if any)

Advanced Commands

These commands are primarily for development and debugging:

claudeman snapshot <name>          # Capture current tmux pane output
claudeman snapshot-parse <name>    # Parse and display working status + solution
claudeman snapshot-test <name>     # Save snapshot + parsed output to JSON
claudeman snapshot-fixture <name>  # Save as test fixture in tests/fixtures/

Configuration Files

All configuration is stored in ~/.claudeman/:

• sessions.json - Session metadata (name, cwd, creation time)
• telegram.json - Telegram bot config (token, chatId, projectsDir)
• tg.pid - PID lock file for Telegram bot (prevents multiple instances)
• tg-messages.json - Maps Telegram message IDs to session names (last 500)

License

MIT