comm-bridge

name

comm-bridge

description

C4 communication bridge — central gateway for ALL external communication (Telegram, Lark, etc.). Use when replying to users via the "reply via" path, sending proactive messages to external channels, querying recent conversations or checkpoint status (prefer c4-db.js CLI; sqlite3 OK for unsupported queries), fetching conversation history for Memory Sync, or creating checkpoints after sync. Incoming messages are queued by channel bots and delivered to Claude via a PM2 dispatcher daemon. Session-start hooks automatically provide conversation context and can trigger Memory Sync when unsummarized conversations exceed the configured threshold.

Communication Bridge (C4)

Central message hub - ALL communication with Claude goes through C4.

Architecture

Web Console ──┐
Telegram    ───┼──► C4 Bridge ◄──► Claude
Lark        ───┘

Components

Script	Purpose	Reference
c4-receive.js	External → Claude (queue incoming messages)	c4-receive
c4-send.js	Claude → External (route outgoing messages)	c4-send
c4-control.js	System control plane (heartbeat, maintenance)	c4-control
c4-dispatcher.js	PM2 daemon: polls pending queue, delivers to tmux	—
c4-session-init.js	Hook (session start): context + Memory Sync trigger	hooks
c4-fetch.js	Fetch conversations by id range	c4-fetch
c4-db.js	Database module and CLI for querying conversations and checkpoints	c4-db
c4-checkpoint.js	Create/query checkpoints (sync boundaries)	c4-checkpoint

Sending Messages

# Send to Telegram DM
cat <<'EOF' | node ~/zylos/.claude/skills/comm-bridge/scripts/c4-send.js telegram 8101553026
Hello! Quotes, $vars, **markdown** — all safe via stdin.
EOF

# Send to Lark group thread
cat <<'EOF' | node ~/zylos/.claude/skills/comm-bridge/scripts/c4-send.js lark "chat_xxx|type:group|root:msg_yyy"
Report ready.
EOF

Always pipe messages via stdin heredoc — never pass as CLI arguments. See c4-send for full reference. Treat the heredoc wrapper as fixed shell syntax: only the message body goes between the start line and the closing terminator line, and the terminator itself must never be copied into the actual outgoing message.

Database

SQLite at ~/zylos/comm-bridge/c4.db:

• conversations: All messages (in/out) with priority, status, retry tracking
• checkpoints: Recovery points with conversation id ranges
• control_queue: System control messages (heartbeat, maintenance) with priority, ack deadlines, and status lifecycle

Health & Status

The activity monitor writes ~/zylos/activity-monitor/agent-status.json which includes a health field:

Value	Meaning
ok	System healthy, messages accepted normally
recovering	Legacy persisted liveness state; normalized to unavailable at runtime
down	Legacy persisted liveness state; normalized to unavailable at runtime

Fail-open semantics: If the status file is missing or malformed, health is assumed ok — intake is never blocked by a read failure.

When health is not ok, c4-receive.js asks the activity monitor MessageRouter how to route the current message. Unhealthy messages are recorded as delivered and receive an immediate status reply when replies are enabled; --no-reply messages are accepted silently. If the MessageRouter IPC is unavailable, c4-receive.js falls back to the status file with the same delivered/current-message behavior.

Keystroke Delivery

The dispatcher supports [KEYSTROKE] control messages for sending raw keystrokes to the tmux session. This is an ops-level capability — no source gating is applied.

When a control message content starts with [KEYSTROKE], the dispatcher:

• Extracts the key name (e.g., Enter, Tab, Escape)
• Sends it directly via tmux send-keys (no buffer paste, no "Meanwhile" prefix, no verification)
• Auto-acks the control immediately after delivery

Example: the permission auto-approve hook enqueues [KEYSTROKE]Enter at priority 0 with bypass-state to auto-confirm Claude Code's permission prompts.

Any process with access to c4-control.js can enqueue keystroke controls. This mirrors the existing reality that any process can call tmux send-keys directly — the C4 queue adds priority ordering and delivery guarantees, not access control.

Service Management

pm2 status c4-dispatcher
pm2 logs c4-dispatcher
pm2 restart c4-dispatcher