Skip to main content

imessenger

Inter-session messaging CLI for communication between AI sessions.

Commands​

send​

Send a message to another session.

imessenger send <session> <message>

Options:

  • --from <session> - Specify sender session

Examples:

# Send task to worker
imessenger send worker1 "Implement login API"

# Send status update
imessenger send project-mgr "DONE: Login API implemented"

Exit Codes:

  • 0 - Success
  • 5 - Rejected (target waiting for permission)
  • 6 - Queued to inbox (target busy)

cancel​

Interrupt a session and optionally send a new message.

imessenger cancel <session> [message]

Examples:

# Just interrupt (sends Escape)
imessenger cancel worker1

# Interrupt and send new task
imessenger cancel worker1 "Stop that, do this instead"

approve​

Approve a permission request from a session.

imessenger approve <session> [option]

Options:

  • 1 - Yes (default)
  • 2 - Yes + don't ask again

Examples:

# Basic approval
imessenger approve worker1

# Approve and remember
imessenger approve worker1 2

inbox​

View and manage incoming messages.

imessenger inbox [session]

Subcommands:

imessenger inbox              # View all inbox messages
imessenger inbox pop          # Get and remove oldest message
imessenger inbox --count      # Get message count
imessenger inbox --clear      # Clear inbox

list​

List all sessions.

imessenger list

discover​

Auto-discover sessions.

imessenger discover

process​

Process inbox messages.

imessenger process              # One-shot process all inboxes
imessenger process --watch      # Continuous inbox processing
imessenger process --stop       # Stop running processor

Message Conventions​

Task Assignment​

imessenger send worker1 "TASK: Implement user registration"

Completion Report​

imessenger send mgr "DONE: User registration implemented with tests"

Blocked Status​

imessenger send mgr "BLOCKED: Need database credentials"

Question​

imessenger send mgr "QUESTION: Should we use bcrypt or argon2 for hashing?"

Message Flow​

Manager                    Worker
   │                          │
   │─── TASK: Do X ──────────►│
   │                          │
   │◄── QUESTION: How? ───────│
   │                          │
   │─── Answer: Like this ───►│
   │                          │
   │◄── DONE: X completed ────│
   │                          │