atm-0.1.7 is not a library.

Agent Tmux Monitor (ATM)

⚠️ Warning: This software was vibe coded by Claude while the author nodded along approvingly. It works surprisingly well, but if it summons a daemon (the other kind), you're on your own.

Real-time monitoring for Claude Code agents across tmux sessions.

Know what your AI agents are doing, before they hit limits.

ATM Screenshot

Overview

Agent Tmux Monitor provides a centralized, real-time dashboard for monitoring multiple Claude Code sessions. If you're running several Claude Code agents across tmux windows, ATM gives you instant visibility into:

Context usage - See which sessions are approaching context limits
Agent status - Know when agents are thinking, waiting for permission, or idle
Cost tracking - Monitor spending across all sessions
Session navigation - Jump directly to any tmux session with a keypress

Features

Real-time updates - Status refreshes every ~300ms via Claude Code hooks
Keyboard-driven interface - Familiar TUI with vim-style navigation
Split-pane layout - Overview panel + detailed session view
Context progress bars - Visual indicators for context window usage
Tmux integration - Press Enter to jump directly to any session
Zero impact - Non-blocking hooks that never slow down Claude Code
Graceful degradation - Works even when daemon is temporarily unavailable

Installation

Quick Install (Recommended)

curl -sSL https://raw.githubusercontent.com/damelLP/agent-tmux-monitor/main/scripts/install.sh | sh

This downloads pre-built binaries, installs them to ~/.local/bin, and configures Claude Code hooks automatically.

Using Cargo

If you have Rust installed:

# From source
cargo install atm

# Or with pre-built binaries (faster)
cargo binstall atm

Then configure the hooks:

atm setup

Manual Installation

Download the latest release for your platform from GitHub Releases

Extract and install:

tar xzf atm-<target>.tar.gz
cd atm-*
cp atm atmd atm-hook ~/.local/bin/
chmod +x ~/.local/bin/atm*

Configure Claude Code hooks:
```
atm setup
```

Verify Installation

# Check binaries are installed
which atm atmd

# Check daemon status
atmd status

Quick Start

Launch ATM:
```
atm
```
(The daemon starts automatically if it's not already running)
Start using Claude Code - sessions will automatically appear as you work.

Usage

Keyboard Controls

Key	Action
`j` / `↓`	Move selection down
`k` / `↑`	Move selection up
`Enter`	Jump to selected tmux session
`Tab`	Toggle between panels
`q`	Quit
`?`	Show help

Daemon Commands

# Start daemon in background
atmd start -d

# Start daemon in foreground (for debugging)
atmd start

# Check daemon status
atmd status

# Stop daemon
atmd stop

TUI Options

# Launch with default settings
atm

# Pick mode - select a session and exit (useful for scripting)
atm --pick

# Show version
atm --version

# Show help
atm --help

Tmux Popup Integration

Run ATM in a tmux popup for quick session switching without leaving your current window:

# Add this to your ~/.tmux.conf
bind-key a display-popup -E -w 80% -h 60% "atm --pick"

Now press <prefix>-a to pop up ATM, select a session, and jump directly to it. The popup closes automatically after selection.

Tip: Adjust -w (width) and -h (height) percentages to your preference.

Configuration

Claude Code Hooks

ATM integrates with Claude Code via hooks. The atm setup command automatically adds these to ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "*",
      "hooks": [{ "type": "command", "command": "atm-hook" }]
    }],
    "PostToolUse": [{
      "matcher": "*",
      "hooks": [{ "type": "command", "command": "atm-hook" }]
    }],
    "StatusLine": [{
      "hooks": [{ "type": "command", "command": "atm-hook" }]
    }]
  }
}

Daemon Socket

The daemon listens on a Unix socket at /tmp/atm.sock. This can be customized via environment variable:

ATM_SOCKET=/path/to/custom.sock atmd start -d

Architecture

ATM consists of three components:

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Claude Code   │────▶│      atmd       │◀────│       atm       │
│   (+ hooks)     │     │    (daemon)     │     │      (TUI)      │
└─────────────────┘     └─────────────────┘     └─────────────────┘
        │                       │                       │
        │  atm-hook script      │  Unix socket          │  Real-time
        │  reports events       │  /tmp/atm.sock        │  display
        ▼                       ▼                       ▼

atm-hook - Shell script that reports Claude Code events to the daemon
atmd - Background daemon that maintains session registry and broadcasts updates
atm - Terminal UI that connects to daemon and displays session status

Session Lifecycle

Claude Code starts → atm-hook sends registration to daemon
Status updates every ~300ms via StatusLine hook
Tool usage reported via PreToolUse/PostToolUse hooks
Session marked stale after 90s of inactivity
Stale sessions cleaned up automatically

Requirements

System Requirements

OS: Linux or macOS (Windows not currently supported)
Terminal: Any terminal with 256-color support
tmux: Required for session jump functionality

Runtime Dependencies

socat - For Unix socket communication (install via package manager)
jq - For JSON parsing in hook scripts (install via package manager)

Install on Ubuntu/Debian:

sudo apt install socat jq

Install on macOS:

brew install socat jq

Install on Arch Linux:

sudo pacman -S socat jq

Troubleshooting

Daemon won't start

Check if another instance is running:

atmd status
# If stuck, manually remove socket
rm /tmp/atm.sock

Sessions not appearing

Verify hooks are configured:

cat ~/.claude/settings.json | jq '.hooks'

Check that atm-hook is in PATH:
```
which atm-hook
```

Test hook manually:

echo '{"hook_type": "StatusLine"}' | atm-hook

TUI shows "Daemon Disconnected"

Start or restart the daemon:

atmd start -d

High CPU usage

This shouldn't happen with normal usage. If it does:

Check number of active sessions (atmd status)
Restart daemon (atmd stop && atmd start -d)
File a bug report with logs from ~/.local/state/atm/atm.log

Uninstalling

# Stop daemon
atmd stop

# Remove hooks and binaries
atm uninstall

# Or manually:
rm ~/.local/bin/atm ~/.local/bin/atmd ~/.local/bin/atm-hook
# Remove hooks from ~/.claude/settings.json

Contributing

Contributions are welcome!

Building from Source

# Clone repository
git clone https://github.com/damelLP/agent-tmux-monitor.git
cd agent-tmux-monitor

# Build
cargo build --release

# Run tests
cargo test --all

# Binaries are in target/release/
./target/release/atmd start -d
./target/release/atm

Project Structure

agent-tmux-monitor/
├── Cargo.toml           # Workspace root, defines both binaries
├── crates/
│   ├── atm-core/        # Shared domain types and logic
│   ├── atm-protocol/    # Wire protocol definitions
│   ├── atm/             # TUI application
│   └── atmd/            # Daemon server
├── scripts/
│   ├── install.sh       # Installation script
│   └── atm-hook         # Claude Code hook script
└── docs/                # Documentation

License

MIT License - see LICENSE for details.

Acknowledgments

Built with ratatui for the terminal UI
Async runtime powered by tokio
Born from the chaos of managing too many AI agents at once

atm 0.1.7