messenger (Inter-session Communication)

messenger enables fire-and-forget messaging between Claude Code sessions running in tmux. Send prompts, delegate tasks, and orchestrate multiple sessions from a single terminal.

Note: For reply functionality with response waiting, use sesh-messenger.

Installation

gitlab-install @session-tools/session-messenger

Quick Start

# Discover running Claude sessions
messenger discover

# List discovered sessions
messenger list

# Send a prompt to another session (fire-and-forget)
messenger send worker-1 "Implement the login API"

# Type only (don't press Enter)
messenger send worker-1 --no-submit "Draft message"

# Approve permission request
messenger approve worker-1

CLI Commands

Session Discovery

Command	Description
messenger discover	Auto-discover running Claude Code sessions
messenger list	List all registered sessions
messenger register <name> <tmux-id>	Manually register a session
messenger unregister <name>	Remove a session from registry

Messaging

Command	Description
messenger send <session> <prompt>	Send message (fire-and-forget, submits by default)
messenger send <session> --no-submit <prompt>	Type only (don't press Enter)
messenger send <session> --from <session> <prompt>	Specify sender session (for inbox queuing)

Permission Approval

Command	Description
messenger approve <session>	Approve permission (default: Yes)
messenger approve <session> 1	Approve with Yes
messenger approve <session> 2	Approve with Yes + don't ask again

Inbox Management

Command	Description
messenger inbox	View your inbox
messenger inbox <session>	View session's inbox
messenger inbox --count	Get unread count only
messenger inbox --clear	Clear all messages in inbox
messenger inbox --watch	Watch inbox and notify periodically
messenger inbox --watch --notify-interval <s>	Set notification interval (default: 60s)

Event Management

Command	Description
messenger event list	List events
messenger event latest [session]	Get latest event

Configuration

Command	Description
messenger config	Show current configuration

Exit Codes

Code	Meaning
0	Success
1	Error
5	Rejected (session waiting for permission)
6	Queued to inbox (target busy)

How It Works

Session Discovery

When you run messenger discover:

1. Lists all tmux sessions
2. Captures each session's screen content
3. Detects Claude Code patterns (claude.com, ? for shortcuts, etc.)
4. Registers discovered sessions with short names

Prefix Handling

Many tools prefix tmux session names (e.g., logsession-v2-my-task). Messenger automatically strips configured prefixes:

# Now "logsession-v2-my-task" is registered as "my-task"
messenger send my-task "Hello"  # → sends to logsession-v2-my-task

Inbox System

When a target session is busy (e.g., Claude is processing), messages are queued to the inbox:

# Check if you have messages
messenger inbox --count

# Read your messages
messenger inbox

# Clear inbox after reading
messenger inbox --clear

tmux Integration

Messenger uses tmux commands internally:

• tmux send-keys -l - Input text (without Enter)
• tmux send-keys Enter - Press Enter
• tmux capture-pane - Read screen content
• tmux has-session - Check session exists

Usage Examples

Basic Messaging

# Send message (fire-and-forget, submits automatically)
messenger send worker "Do the task"

# Type only (don't submit)
messenger send worker --no-submit "Draft message"

Permission Management

# Approve permission with default (Yes)
messenger approve worker

# Approve with "Yes + don't ask again"
messenger approve worker 2

Inbox Usage

# View my inbox
messenger inbox

# Just get count
messenger inbox --count

# View worker's inbox
messenger inbox worker

# Watch for new messages
messenger inbox --watch --notify-interval 30

Manager-Worker Pattern

Orchestrate parallel work across multiple sessions:

# From manager session, delegate to workers
messenger send worker-1 "Implement feature A"
messenger send worker-2 "Implement feature B"
messenger send worker-3 "Write documentation"

Session Collaboration

Pass work between sessions:

# Session A completes, hands off to Session B
messenger send session-b "Tests are ready. Please review and merge."

Safe Review Before Execute

For sensitive operations, use --no-submit:

# Input text but don't press Enter
messenger send production --no-submit "DROP TABLE users"

# Switch to production session manually to review before pressing Enter

Integration with logsession

# Start sessions with logsession
logsession start manager-1 --detach
logsession start worker-1 --detach
logsession start worker-2 --detach

# Discover and message
messenger discover
messenger send worker-1 "Start working on auth module"

File Locations

~/.messenger/
└── logs/                # Messenger logs

Version Info

• Current Version: 3.0.3
• License: SSPL-1.0
• Repository: GitLab