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
• --skip-verify - Skip delivery verification (verification is on by default)

Examples:

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

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

send doesn't wait for a reply. It pastes the message, presses Enter once and checks that the message left the input box. If it didn't, it prints Not delivered and exits 3.

Exit Codes:

• 0 - Success
• 1 - Error
• 3 - Not delivered (the message stayed in the input box or never appeared)
• 5 - Rejected (target waiting on a permission/selection dialog; nothing typed)
• 6 - Target is busy (another imessenger command holds its input)

cancel

Interrupt a session (sends Escape).

imessenger cancel <session>

To give it a new task, send it right after:

imessenger cancel worker1
imessenger send worker1 "Stop that, do this instead"

pending

Show the permission/selection dialogs open in sessions (read-only).

imessenger pending [session|pattern ...]

key

Answer an open dialog in a session by pressing keys. Read the dialog first (for example with imessenger pending): option numbers and meanings differ per dialog. Keys are sent in order and no Enter is added.

imessenger key <session> <key...> [--expect "<option text>"]

• Key names such as Up, Down, Enter, Escape, Tab are pressed as keys; anything else (e.g. 2, y) is typed as text.
• --expect "<text>" - Check the chosen option's text first; if it doesn't match, the confirming key is not sent (exit 8).

Examples:

imessenger key worker1 2 --expect "Yes"                 # Claude Code: pick option 2
imessenger key worker1 Down Enter --expect "Yes, I trust" # menu without numbers
imessenger key codex-worker y                            # Codex: 'y', no Enter
imessenger key worker1 Escape                            # close (reject) the dialog

If smon escalated a dialog, only smon and the configured approvers may answer it; others get exit 10.

노트

imessenger approve and imessenger approve-key are deprecated. They still work but print a warning; use imessenger key.

list

List all sessions.

imessenger list

discover

Auto-discover sessions.

imessenger discover

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 ────│
   │                          │