https://github.com/zemse/claudeman
Remote control multiple ClaudeCode sessions using telegram
https://github.com/zemse/claudeman
Last synced: 4 months ago
JSON representation
Remote control multiple ClaudeCode sessions using telegram
- Host: GitHub
- URL: https://github.com/zemse/claudeman
- Owner: zemse
- License: mit
- Created: 2026-01-17T20:39:11.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-02-14T06:34:58.000Z (4 months ago)
- Last Synced: 2026-02-28T09:10:55.047Z (4 months ago)
- Language: TypeScript
- Homepage:
- Size: 1020 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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
```bash
npm install -g claudeman
```
Requires: Node.js >= 18, tmux, Claude Code CLI
## Usage
```bash
claudeman # Open TUI
claudeman new # Create session in current directory
claudeman new -c # Create session at specific path
claudeman new --attach # Create and immediately attach
claudeman list # List all sessions
claudeman attach # Attach to session
claudeman kill # 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](https://t.me/BotFather) on Telegram and copy the bot token
2. Get your chat ID from [@userinfobot](https://t.me/userinfobot)
3. Run setup:
```bash
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:
```bash
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 ` | Create a new session at the given path (supports `~` for home directory) |
| `/clone ` | 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:
```bash
claudeman snapshot # Capture current tmux pane output
claudeman snapshot-parse # Parse and display working status + solution
claudeman snapshot-test # Save snapshot + parsed output to JSON
claudeman snapshot-fixture # 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