Claude Code Monitor

Monitor multiple Claude Code sessions in real-time from your terminal or smartphone.

Terminal UI

Monitor sessions with keyboard navigation

Mobile Web

Control from your phone (same Wi-Fi required)

✨ Features

| Terminal (TUI) | Mobile Web | |----------------|------------| | Real-time session monitoring | Monitor from your smartphone | | Quick tab focus with keyboard | Remote terminal focus | | Vim-style navigation | Send messages to terminal | | Simple status display | Real-time sync via WebSocket |

• 🔌 Serverless - File-based state management, no API server required
• ⚡ Easy Setup - One command ccm for automatic setup and launch
• 🔒 Secure - No external data transmission, token-based mobile auth

📋 Requirements

Note: This tool is macOS only due to its use of AppleScript for terminal control.

• macOS
• Node.js >= 18.0.0
• Claude Code installed

🚀 Quick Start

Install

npm install -g claude-code-monitor

Run

ccm

On first run, it automatically sets up hooks and launches the monitor.

Mobile Access

1. Press h to show QR code (default port: 3456)
2. Scan with your smartphone (same Wi-Fi required)

If port 3456 is in use, an available port is automatically selected.

📖 Usage

Commands

| Command | Alias | Description | |---------|-------|-------------| | ccm | - | Launch monitor (auto-setup if needed) | | ccm watch | ccm w | Launch monitor | | ccm serve | ccm s | Start mobile web server only | | ccm setup | - | Configure Claude Code hooks | | ccm list | ccm ls | List sessions | | ccm clear | - | Clear all sessions |

Keybindings

| Key | Action | |-----|--------| | ↑ / k | Move up | | ↓ / j | Move down | | Enter / f | Focus selected session | | 1-9 | Quick select & focus | | h | Show/Hide QR code | | c | Clear all sessions | | q / Esc | Quit |

Status Icons

| Icon | Status | Description | |------|--------|-------------| | ● | Running | Claude Code is processing | | ◐ | Waiting | Waiting for user input | | ✓ | Done | Session ended |

📱 Mobile Web Interface

Monitor and control Claude Code sessions from your smartphone.

Features

• Real-time session status via WebSocket
• View latest Claude messages
• Focus terminal sessions remotely
• Send text messages to terminal (multi-line supported)
• Swipe-to-close gesture on modal
• Warning display for dangerous commands

Security

Important: Your smartphone and Mac must be on the same Wi-Fi network.

• Token Authentication - A unique token is generated for authentication
• Local Network Only - Not accessible from the internet
• Do not share the URL - Treat it like a password

Warning: Avoid using on public Wi-Fi networks (cafes, airports, etc.). Other users on the same network could potentially access your monitor. Use only on trusted private networks.

🖥️ Supported Terminals

| Terminal | Focus Support | Notes | |----------|--------------|-------| | iTerm2 | ✅ Full | TTY-based targeting | | Terminal.app | ✅ Full | TTY-based targeting | | Ghostty | ⚠️ Limited | App activation only |

Other terminals can use monitoring, but focus feature is not supported.

🔧 Troubleshooting

Sessions not showing

1. Run ccm setup to verify hook configuration
2. Check ~/.claude/settings.json for hook settings
3. Restart Claude Code

Focus not working

1. Verify you're using a supported terminal
2. Check System Preferences > Privacy & Security > Accessibility

Reset data

ccm clear

🔒 Security

Warning: This tool is designed for use on trusted private networks only.

Never use on public Wi-Fi (cafes, airports, hotels, co-working spaces, etc.). Other users on the same network could potentially intercept the authentication token and gain control of your terminal sessions, including the ability to execute arbitrary commands.

• No data sent to external servers - All data stays on your machine
• Hook registration modifies ~/.claude/settings.json
• Focus feature uses AppleScript for terminal control
• Mobile Web uses token authentication on local network only
• Server-side validation blocks dangerous shell commands

📦 Programmatic Usage

import { getSessions, focusSession } from 'claude-code-monitor';

const sessions = getSessions();
if (sessions[0]?.tty) {
  focusSession(sessions[0].tty);
}

⚠️ Disclaimer

This is an unofficial community tool and is not affiliated with Anthropic. "Claude" and "Claude Code" are trademarks of Anthropic.

🐛 Issues

Found a bug? Open an issue

🤝 Contributing

Contributions are welcome! Please open an issue or submit a PR.

📝 Changelog

See CHANGELOG.md for details.

📄 License

MIT