/session-message

Send directed messages between active LLM sessions for real-time coordination. Uses the bus.send() API from ADR-173 for delivery-tracked, session-to-session messaging.

Purpose

Enables LLM sessions to communicate directly with each other through the Inter-Session Message Bus (messaging.db). Messages are delivery-tracked (pending -> delivered -> read) and can be retrieved by the recipient via /session-status --unread or /cxq --bus-unread.

Usage

# Send a message to a specific session
/session-message "codex-41200" "please release lock on paths.py"

# Send with high priority
/session-message "codex-41200" "urgent: task H.13.7 conflict" --priority 3

# Send to all active sessions (broadcast)
/session-message --all "switching to track J work, releasing all H tasks"

# Check sent messages
/session-message --sent

# Check delivery status of sent messages
/session-message --sent --status

Arguments

Argument	Type	Required	Default	Description
`target`	string	Yes*	-	Target session ID (e.g., `codex-41200`, `claude-29583`)
`message`	string	Yes	-	Message content to send
`--priority`	int	No	2	Priority: 0=routine, 1=normal, 2=high, 3=critical
`--all`	flag	No	false	Broadcast to all active sessions
`--sent`	flag	No	false	Show messages sent by this session
`--status`	flag	No	false	Include delivery status (pending/delivered/read)
`--channel`	string	No	`coordination`	Message channel (coordination, task_broadcast, state)

*Required unless --all or --sent is used.

System Prompt

When the user invokes /session-message:

Connect to message bus:

import os, sys
sys.path.insert(0, 'submodules/core/coditect-core')
from scripts.core.session_message_bus import get_session_message_bus

bus = get_session_message_bus()
current_session = f"claude-{os.getpid()}"

Validate target session exists (unless --all):

if not args.all:
    sessions = bus.list_sessions(active_only=True)
    target_exists = any(s.session_id == target for s in sessions)
    if not target_exists:
        print(f"WARNING: Session '{target}' not found in active sessions.")
        print("Active sessions:")
        for s in sessions:
            print(f"  {s.session_id} ({s.llm_vendor}, PID {s.pid})")
        # Still send — session may become active later

Send the message:

if args.all:
    # Broadcast to all active sessions
    sessions = bus.list_sessions(active_only=True)
    for s in sessions:
        if s.session_id != current_session:
            bus.send(
                recipient_id=s.session_id,
                channel=channel,
                payload={"message": message, "from": current_session},
                sender_id=current_session,
                priority=priority
            )
    print(f"Broadcast sent to {len(sessions)-1} session(s)")
else:
    bus.send(
        recipient_id=target,
        channel=channel,
        payload={"message": message, "from": current_session},
        sender_id=current_session,
        priority=priority
    )
    print(f"Message sent to {target}")

Show sent messages (--sent):

if args.sent:
    # Query session_messages where sender_id = current_session
    # and recipient_id is not null (directed messages only)
    # Show: timestamp, recipient, channel, message, status

Output Examples

Send Message

Message sent to codex-41200
  Channel:  coordination
  Priority: 2 (high)
  Content:  "please release lock on paths.py"
  Status:   pending (awaiting delivery)

The recipient will see this message via:
  /session-status --unread
  /cxq --bus-unread

Broadcast

Broadcast sent to 2 session(s)
  Channel:  coordination
  Priority: 2 (high)
  Content:  "switching to track J work, releasing all H tasks"
  Recipients:
    codex-41200 (codex, o3) — pending
    kimi-55100 (kimi, k2) — pending

Target Not Found

WARNING: Session 'codex-41200' not found in active sessions.
Active sessions:
  claude-29583 (claude, opus-4.6) — PILOT
  kimi-55100 (kimi, k2) — PILOT

Message sent anyway (will be available when session registers).

--sent Output

Sent Messages (last 10)
==================================================

2026-02-11T04:15:22Z  codex-41200  coordination  "please release lock"  delivered
2026-02-11T03:58:11Z  kimi-55100   coordination  "task J.15 complete"   read
2026-02-11T03:45:00Z  codex-41200  task_broadcast "claiming H.13.8"     pending

Total: 3 sent messages (1 pending, 1 delivered, 1 read)

When to Use

Use this command when:

Need another LLM session to release a file lock
Coordinating task handoffs between sessions
Alerting other sessions about breaking changes
Requesting status updates from specific sessions
Broadcasting completion of shared dependencies

Common Workflows

Workflow 1: Request Lock Release

# 1. Check who holds the lock
/session-conflicts --all

# 2. Ask them to release
/session-message "codex-41200" "please release lock on session_message_bus.py — I need to edit it for H.13.8"

# 3. Wait and check
/session-status --unread

Workflow 2: Task Handoff

# 1. Announce you're done with a track
/session-message --all "Track H.13 complete. Track J tasks now unblocked."

# 2. Release task claims
# (via Python API: bus.release_task("H.13.8"))

Workflow 3: Urgent Coordination

# Send critical-priority message
/session-message "codex-41200" "CONFLICT: both editing paths.py — please stop" --priority 3

Integration

Feature	API
Send directed message	`bus.send(recipient_id, channel, payload, sender_id, priority)`
Check unread	`bus.get_unread(recipient_id=current_session)`
Mark as delivered	`bus.mark_delivered(message_id)`
Mark as read	`bus.mark_read(message_id)`
Broadcast	`bus.publish(channel, payload)` (undirected)

Error Handling

Error	Cause	Solution
"Not registered"	Sender session not registered	Run /session-register first
"Session not found"	Target session inactive	Message still sent (queued)
"Database locked"	Concurrent access	Auto-retries with busy_timeout=3000ms

Command	Purpose
`/session-status --unread`	View received messages
`/session-conflicts`	Check file/project/task conflicts
`/session-register`	Register session (required for messaging)
`/cxq --bus-unread`	Query unread messages
`/cxq --bus-feed`	Chronological activity timeline

Architecture

Database: ~/.coditect-data/context-storage/messaging.db
Table: session_messages (delivery-tracked, with sender_id/recipient_id)
Python API: scripts/core/session_message_bus.py — send(), get_unread(), mark_delivered(), mark_read()
ADR: ADR-160, ADR-173

Version: 1.0.0 Created: 2026-02-11 Updated: 2026-02-11 Author: Claude Opus 4.6 Track: H (Framework Autonomy) Task: H.13.9

Changelog:

v1.0.0 - Initial release: directed messaging via bus.send(), broadcast support, delivery tracking, --sent status view

Purpose​

Usage​

Arguments​

System Prompt​

Output Examples​

Send Message​

Broadcast​

Target Not Found​

--sent Output​

When to Use​

Common Workflows​

Workflow 1: Request Lock Release​

Workflow 2: Task Handoff​

Workflow 3: Urgent Coordination​

Integration​

Error Handling​

Related Commands​

Architecture​