DEV Community: Mozi Mohidien

Bot-to-Bot Messaging Without a Message Broker: Building a Local Inbox Bus for Claude Agents

Mozi Mohidien — Wed, 22 Jul 2026 09:39:01 +0000

Bot-to-Bot Messaging Without a Message Broker: Building a Local Inbox Bus for Claude Agents

by Mozi Mohidien

Telegram's Bot API is one-way. A bot can receive messages from users and reply to them. It cannot send messages to another bot. There is no API call for "bot A sends a message to bot B."

In a multi-bot architecture where bots need to collaborate — one bot asking another for context, one bot routing a task to a specialist — this is a real problem. The usual answer is a message broker: Redis pub/sub, RabbitMQ, something with a queue. That works but adds infrastructure to a system that is already running eight processes on a single machine.

The simpler answer: a file-based inbox per bot, with atomic writes and a watcher that drains it on every poll cycle.

The Design

Each bot has an inbox directory at sessions/[name]/inbox/. A message is a JSON file dropped into that directory. The bot's watcher script scans the inbox on every 30-second poll, checks whether the bot is idle, and injects waiting messages via tmux send-keys.

No broker. No daemon. No network calls. The filesystem is the queue. The watcher is the consumer.

Three properties matter:

Atomic writes. Messages are written to a .tmp file first, then moved into the inbox directory. mv within the same filesystem is atomic. The receiving bot either sees a complete message file or nothing — never a partial write.

Idle injection only. The watcher checks whether the bot's Claude process is at a ready prompt before injecting. If Claude is mid-task, the message stays in the inbox and gets delivered on the next poll cycle. This prevents injecting a new task into an already-running one.

Offline delivery. The inbox persists on disk. If a bot is down when a message arrives, the message sits in the inbox until the bot restarts. The next drain cycle delivers it.

send.sh

send.sh takes four arguments: sender bot name, recipient bot name, message content, and an optional reply_to message ID.

#!/bin/bash
FROM="$1"
TO="$2"
CONTENT="$3"
REPLY_TO="${4:-}"

INBOX="/Users/mozimohidien/mozi/second_brain/sessions/$TO/inbox"
TS="$(date +%s%N)"
ID="${TS}-$$-${RANDOM}"
MSG="$INBOX/${ID}.msg"
TMP="$INBOX/${ID}.tmp"

mkdir -p "$INBOX"

ESC_CONTENT="$(printf '%s' "$CONTENT" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')"
printf '{ "id": "%s", "from": "%s", "to": "%s", "ts": "%s", "content": %s }\n' \
  "$ID" "$FROM" "$TO" "$TS" "$ESC_CONTENT" > "$TMP"
mv "$TMP" "$MSG"

echo "$ID"

The message filename encodes a timestamp, PID, and random number. This prevents collisions if two bots send to the same recipient simultaneously. The timestamp ensures messages drain in arrival order.

python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))' JSON-encodes the content string, handling quotes, newlines, and special characters. This matters when message content contains multi-line prompts or code.

send.sh prints the message ID to stdout. The sender can capture it for reply routing.

drain.sh

drain.sh is sourced by every bot's watch.sh. It runs on each poll cycle, after the bot's health check.

Pseudocode:

function drain_bot_inbox() {
    INBOX = "sessions/$BOT_NAME/inbox"

    if inbox is empty:
        return

    # Check pane readiness
    PANE_CONTENT = tmux capture-pane -t $SESSION -p

    if PANE_CONTENT matches /(esc to interrupt|working\.\.\.|tokens used|numbered dialog \[1\]|\[y\/n\])/i:
        # Bot is busy — leave messages for next cycle
        return

    # Process messages in order (sorted by filename = arrival order)
    for MSG_FILE in sorted(inbox/*.msg):
        CONTENT = parse JSON content field from MSG_FILE
        FROM = parse JSON from field
        ID = parse JSON id field

        # Build the injected prompt
        PROMPT = "[BOT-BUS] Message from $FROM (id: $ID):\n\n$CONTENT\n\n[Reply via: send.sh $BOT_NAME $FROM \"your reply here\" $ID]"

        # Inject into the tmux session
        tmux send-keys -t $SESSION "$PROMPT" Enter

        # Delete the message file
        rm -f $MSG_FILE

        # Wait for Claude to start processing before injecting the next message
        sleep 3

        # Re-check pane — if Claude started a task, stop draining
        PANE_CONTENT = tmux capture-pane -t $SESSION -p
        if PANE_CONTENT matches /(esc to interrupt|working)/i:
            break
    end
}

The readiness check is the critical piece. Claude's pane shows different text depending on state:

Ready for input: shows the prompt cursor
Mid-task: shows "esc to interrupt" or streaming output
Usage modal: shows numbered options

The drain function only injects when the pane is at a clean prompt. Everything else means Claude is busy. Messages queue and deliver on the next cycle.

Reply Routing

When drain.sh injects a message, it appends instructions for the receiving bot:

[BOT-BUS] Message from oper8 (id: 1720000000000-1234-5678):

I need the learning context for Mozi's current AI module — specifically what he's covered so far and what's next on the path. I'm briefing a client on Mozi's technical background.

[Reply via: send.sh life_tutor oper8 "your reply here" 1720000000000-1234-5678]

The receiving bot sees this as an ordinary prompt. It reads the instructions, forms a response, and calls send.sh as directed. The reply lands in the sender's inbox, with reply_to set to the original message ID so the sender can correlate it.

This requires Claude to follow the reply instruction reliably. In practice it does — the instruction is explicit and the format is consistent. The occasional failure (Claude answers but doesn't send the reply) is handled by the sender timing out and either re-sending or handling the missing reply gracefully.

A Real Usage Example: oper8 → life_tutor

Scenario: the oper8 bot is preparing a client briefing for a prospect interested in Mozi's technical background. It needs to know what Mozi has been studying in AI recently.

Step 1: oper8 sends a message to life_tutor

send.sh oper8 life_tutor "I need Mozi's current learning context — what AI topics has he covered recently and what is he working on next? I'm briefing Nexus Capital on his technical background."

This writes a file to /Users/mozimohidien/mozi/second_brain/sessions/life_tutor/inbox/1720000120000-4521-8833.msg:

{
  "id": "1720000120000-4521-8833",
  "from": "oper8",
  "to": "life_tutor",
  "ts": "1720000120000",
  "content": "I need Mozi's current learning context — what AI topics has he covered recently and what is he working on next? I'm briefing Nexus Capital on his technical background."
}

Step 2: life_tutor's watcher drain detects the message

On the next 30-second poll, drain_bot_inbox runs. The pane check passes (life_tutor is idle). The drain function reads the message and injects:

[BOT-BUS] Message from oper8 (id: 1720000120000-4521-8833):

I need Mozi's current learning context — what AI topics has he covered recently and what is he working on next? I'm briefing Nexus Capital on his technical background.

[Reply via: send.sh life_tutor oper8 "your reply here" 1720000120000-4521-8833]

Step 3: life_tutor processes and replies

Claude (life_tutor session) receives the prompt, reads LEARNING_PATH.md, forms a summary, and executes the reply:

send.sh life_tutor oper8 "Mozi completed the core Claude API module last week — tool use, multi-turn conversations, context management. Currently working through the agent orchestration patterns module. Next up: MCP server design and multi-agent coordination. Strong foundations; actively building production systems on top." 1720000120000-4521-8833

Step 4: oper8's watcher delivers the reply

The reply lands in /Users/mozimohidien/mozi/second_brain/sessions/oper8/inbox/1720000180000-7722-3341.msg. On oper8's next poll, the drain delivers it. The oper8 Claude session receives the context and continues building the client briefing.

Total latency: under 60 seconds (two watcher cycles maximum). No external infrastructure. No broker to maintain or fail.

Idle Safety in Practice

A bot injected mid-task causes immediate problems. Claude is streaming output for one task and suddenly receives a new prompt — the context merges, the outputs collide, both tasks produce garbage.

The readiness regex catches the common cases:

esc to interrupt — Claude is actively working
working... — task in progress indicator
tokens used — post-response summary, Claude may still be settling
Numbered dialog [1] — modal or confirmation prompt, not safe to inject
[y/n] — Claude is asking a yes/no question

If any of these appear in the captured pane content, the drain stops and all messages wait for the next cycle.

The sleep 3 between messages gives Claude time to start processing the first injected message before the next one arrives. Without it, two messages can land in the same prompt buffer and Claude reads them as one.

Failure Modes

Message never delivered. Check if the target bot's inbox directory exists and is writable. Check that drain_bot_inbox is being called in the target's watch.sh. Confirm the pane readiness check is not stuck (e.g., pane permanently showing "esc to interrupt" because Claude froze mid-task).

Duplicate delivery. The rm -f $MSG_FILE after injection handles this — once delivered, the file is gone. If you see duplicates, the delete is failing silently. Add error checking around the rm.

Garbled content. The python3 JSON encoding in send.sh handles most special characters. The failure mode is content that breaks JSON — usually an unescaped backslash or a very long string. Test with echo "$ID" | python3 -m json.tool if messages are arriving malformed.

Reply never received. Claude processed the message and answered but did not call send.sh. This happens when the injected instructions are too buried in a long conversation context. Keep the [Reply via: ...] instruction at the end of the injection, not the beginning — Claude reads to completion before acting.

Scaling the Pattern

Eight bots, any one of which can message any other. The inbox pattern scales without modification. Adding a new bot means creating its inbox directory. Nothing else changes.

The watcher architecture already handles the drain — it is part of every bot's standard watch.sh. The send and drain scripts are utilities shared across all sessions.

The pattern also composes with the screen lock and agent spawning patterns. A bot that needs to do something requiring screen access checks the lock, acquires it, does the work, releases it, and reports back via send.sh — all within the same architecture, no new infrastructure required.

For a system running entirely on a local machine, this is the right level of complexity: just enough to make bots collaborate reliably, nothing more.

The Orchestrator Pattern for Claude Agents: Delegating Everything, Owning Nothing

Mozi Mohidien — Wed, 22 Jul 2026 09:32:25 +0000

The Orchestrator Pattern for Claude Agents: Delegating Everything, Owning Nothing

by Mozi Mohidien

The most common mistake when building multi-agent systems with Claude is turning the orchestrator into a worker. It reads files. It edits code. It calls APIs directly. Within twenty turns, the orchestrator's context is bloated with tool output noise, the session is slow, and every response costs more than it should.

The fix is a strict rule: the orchestrator never acts. It only plans, delegates, and reviews.

The Core Rule

The orchestrator does exactly three things:

Understand the task and break it down
Brief and spawn agents to execute
Review what comes back and surface the result to the user (or re-brief if it's wrong)

Everything else — file edits, terminal commands, API calls, deployments, web searches, browser navigation — goes through a spawned agent. The orchestrator touches nothing directly.

This sounds simple. It requires discipline to maintain, because the temptation to "just do it inline" is constant. One inline file read feels harmless. Ten turns later, the session context contains 40KB of raw file content that gets re-read on every subsequent turn.

Why Context Cost Matters More Than You Think

For Fable (claude-fable-5), cost hits from two directions.

Input: every turn re-reads the entire session context. A conversation that has accumulated tool outputs from twelve previous turns re-reads all of that on turn thirteen. Context does not get cheaper as the session grows — it gets more expensive per turn.

Output: Fable's thinking tokens bill as output. Even a short response with a thinking budget burns output tokens. The longer the session, the more the model thinks to navigate the accumulated context.

This is why the orchestrator rule has financial weight, not just architectural weight. An orchestrator that stays clean — no inline tool calls, no accumulated raw output — keeps per-turn cost low throughout the session. An orchestrator that acts directly starts cheap and gets expensive fast.

Handling Context Overflow

Sessions eventually get long. The right response is not to keep going — it is to hand off cleanly and restart.

The pattern:

Append relevant updates to the brain files (MOZI.md, operate_with_intelligence.md, the relevant brief — whichever apply)
Write HANDOFF.md — the baton pass document
Touch a signal file that the watcher daemon is polling
The watcher sees the signal file, kills the current session, starts a fresh one

# Trigger the restart
touch ~/mozi/second_brain/.restart_laptop

The watcher picks this up within 30 seconds. The new session starts with zero tool noise in context. Brain files carry forward the relevant state.

HANDOFF.md: Baton Pass, Not Log

HANDOFF.md has one job: give the next session exactly what it needs to continue, nothing more.

Hard constraints: under 30 lines, three fields only.

# Handoff

## Done this session
- Rebuilt the oper8 bot start.sh after model env var broke Telegram server mode
- Updated LEARNING_PATH.md with new MCP module completion
- Cleaned stale files from /mozi/university/

## Next step
Deploy the updated general_fable bot and verify it processes messages

## Urgent
None

That is the entire document. No audit lists. No issue inventories. No historical context. No "also worth noting" sections.

The reason for the constraint: HANDOFF.md gets read on every session start. Every line is input tokens. A 200-line HANDOFF becomes a tax on every single turn of the next session. Keep it short.

The next session overwrites it entirely. It is never accumulated. It is never a log of what has happened over time. It tells the next session exactly one thing: where to pick up.

The Quality Gate

The orchestrator is the last reviewer before output reaches the user. If an agent's output is incomplete, wrong, or mediocre, the user should never see it.

When an agent returns:

Read the output critically
Ask: does this fully achieve what was asked?
If yes, surface it
If no: diagnose exactly why it failed, refine the brief, re-spawn

Common failure modes to check for: agent completed the task technically but missed the actual goal; output is correct but needs synthesizing with another agent's output before it's useful; agent hit a blocker and returned a partial result without flagging it clearly.

"I couldn't do it" from an agent is never an acceptable final answer without investigation. The orchestrator probes: what specifically failed? Was it a missing credential? Wrong file path? Tool error? Then it fixes the brief and tries again, or finds a different approach.

Only when all paths are genuinely exhausted does the orchestrator surface to Mozi: here is what was tried, here is the blocker, here is what he needs to do.

Model Selection for Spawned Agents

Not every agent needs the same model. Over-provisioning burns budget. Under-provisioning produces worse results.

The decision matrix:

Haiku — single-file reads, classification, simple lookups, anything with a short deterministic answer
Sonnet — coding, file edits, multi-step execution, most tasks
Opus — complex reasoning, architecture decisions, deep multi-step analysis requiring judgment
Fable — only when the agent itself needs orchestration capability (rare; spawning a Fable agent to orchestrate sub-agents is usually the wrong design)

# Spawning examples

# Quick lookup — haiku
Agent(
    model="haiku",
    description="Look up contact number",
    prompt="Read /Users/mozimohidien/mozi/second_brain/contacts.json and return the phone number for Ayesha Kader."
)

# Code edit — sonnet
Agent(
    model="sonnet",
    description="Edit start.sh model env var",
    prompt="Edit /path/to/sessions/oper8/start.sh. Change ANTHROPIC_MODEL from claude-sonnet-4-6 to claude-fable-5. Test that the file is valid bash syntax after."
)

# Architecture review — opus
Agent(
    model="opus",
    description="Review MCP server design",
    prompt="Review the design of the Telegram bridge MCP server at ~/.claude/plugins/telegram_bridge/server.ts. Identify any race conditions or failure modes in the polling loop."
)

The WhatsApp Flow Example

A concrete example of the full pattern: Mozi says "send a WhatsApp to Bilal saying the meeting is confirmed for Thursday at 3pm."

The orchestrator does not send the message. It does not look up the contact. Here is the flow:

Step 1: Read contacts.json to find Bilal's number. This is a simple lookup — haiku agent.

Agent(haiku): Read contacts.json, return phone number for "Bilal"
Result: +27821234567

Step 2: Brief a sonnet agent with everything it needs. No back-and-forth.

Agent(
    model="sonnet",
    description="Send WhatsApp to Bilal",
    prompt="""
    Send a WhatsApp message to +27821234567 (Bilal).
    Message: "Hey — meeting confirmed for Thursday at 3pm."

    Use this approach:
    osascript -e 'open location "whatsapp://send?phone=27821234567&text=Hey%20%E2%80%94%20meeting%20confirmed%20for%20Thursday%20at%203pm."'

    Run it and confirm it opens WhatsApp. Report back with success or failure and the exact error if it fails.
    """
)

Step 3: Review the result. Did WhatsApp open? Did the message send? If yes, tell Mozi it is done. If no, diagnose and try another approach (Playwright, direct API if configured).

The orchestrator never touched the terminal. It never read the contacts file directly. It planned, delegated both tasks cleanly, reviewed results, and reported.

Screen Lock Pattern

Some agents need to control the screen — browser navigation, clicking, form submission. Only one agent can do this at a time or they race each other.

Lock file: /Users/mozimohidien/mozi/second_brain/.screen_agent_active

Acquire before starting screen work:

# Check if another agent has the lock
if [ -f "/Users/mozimohidien/mozi/second_brain/.screen_agent_active" ]; then
    echo "Screen already locked by another agent. Aborting."
    exit 1
fi

# Acquire
touch /Users/mozimohidien/mozi/second_brain/.screen_agent_active

Release when done (always — even on failure):

# Release
rm -f /Users/mozimohidien/mozi/second_brain/.screen_agent_active

The orchestrator must never spawn two screen-active agents simultaneously. Before spawning an agent that needs screen access, check that no other screen agent is running. If the lock file exists, either wait or queue the task.

Cost Discipline Summary

Keep Fable orchestrators cheap:

CLAUDE_CODE_EFFORT_LEVEL=low in every Fable bot's start.sh. Never remove it.
Restart sessions early — after heavy agent cycles, not just when approaching context limits. A short session with a tight handoff costs less per turn than a long one.
No inline tool calls in the orchestrator — keep its context clean.
Write tight briefs. Every line in a CLAUDE.md or HANDOFF.md is re-read on every turn. Ruthlessly cut anything stale.

The orchestrator's job is thinking, not doing. Keep its context lean so the thinking stays sharp.

Running a Fleet of Telegram Bots on Claude Code: Per-Bot Sessions, MCP, and Auto-Restart

Mozi Mohidien — Wed, 22 Jul 2026 09:31:49 +0000

Running a Fleet of Telegram Bots on Claude Code: Per-Bot Sessions, MCP, and Auto-Restart

by Mozi Mohidien

Running one Telegram bot on Claude Code is straightforward. Running eight simultaneously — each with its own model, context, memory, and capabilities — without them trampling each other is an architecture problem most people hit after the second bot.

This article walks through the full stack: session isolation, the MCP plugin, auto-restart via launchd and tmux, and a subtle confirmation prompt bug that will silently break every bot you start without a workaround.

The Problem

Claude Code is a process. It loads context, runs tools, maintains state. If you run two bots in the same session, they share context. They see each other's messages. One bot's tool calls pollute the other's reasoning.

The solution: one bot per Claude Code session. Full isolation. Each bot is its own process, with its own working directory, its own MCP config, its own Telegram token.

But then you have eight processes to start, monitor, and restart. Manually doing that is not a system — it's a chore.

Architecture Overview

Each bot has its own session directory under second_brain/sessions/[name]/. Inside that directory:

start.sh — launches the Claude Code process with the right environment
watch.sh — runs in a loop, monitors the tmux session, restarts if dead
.mcp.json — tells Claude Code which MCP servers to load (Telegram bridge, others)

The Telegram bridge plugin lives at ~/.claude/plugins/telegram_bridge/server.ts. It is shared across all bots — each bot's .mcp.json points to the same file, but passes different environment variables (token, state dir). That is how one plugin supports eight bots without duplication.

Claude Code runs in a special server mode:

claude --dangerously-skip-permissions --dangerously-load-development-channels server:telegram

This mode keeps Claude running as a long-lived process, receiving Telegram messages via the MCP plugin and responding through it. Without server:telegram, Claude exits after each response.

start.sh

Every bot needs its own start.sh. The critical details: the bot token, the state directory (unique per bot — this is where Telegram session data lives), and the model.

#!/bin/bash
export TELEGRAM_BOT_TOKEN="[BOT_TOKEN]"
export TELEGRAM_STATE_DIR="/Users/you/.claude/channels/telegram_[BOTNAME]"
export ANTHROPIC_MODEL="claude-fable-5"
export CLAUDE_CODE_EFFORT_LEVEL=low
cd "/path/to/sessions/[BOTNAME]"
exec claude --dangerously-skip-permissions --dangerously-load-development-channels server:telegram

Two things worth calling out.

First: the model is set via export ANTHROPIC_MODEL=..., not via a --model flag. The --model flag breaks Telegram server mode. Claude Code's server mode has specific initialization behavior that the flag interferes with. Use the environment variable.

Second: CLAUDE_CODE_EFFORT_LEVEL=low for Fable bots. Fable (claude-fable-5) is the most capable but most expensive model. It bills thinking tokens as output. Setting effort to low reduces the thinking budget per turn, which keeps the weekly allocation from draining on routine bot responses. Do not remove this line.

.mcp.json

Each session directory has its own .mcp.json. Claude Code reads this file when it starts and loads the listed MCP servers.

{
  "mcpServers": {
    "telegram": {
      "command": "bun",
      "args": ["run", "/path/to/.claude/plugins/telegram_bridge/server.ts"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "[BOT_TOKEN]",
        "TELEGRAM_STATE_DIR": "/path/to/.claude/channels/telegram_[name]"
      }
    }
  }
}

The plugin is launched via bun. The env block passes the bot-specific token and state directory to the plugin process. The plugin handles everything: long-polling Telegram for new messages, surfacing them to Claude as tool results, and providing a reply tool Claude uses to respond.

Because each bot's .mcp.json passes a different TELEGRAM_STATE_DIR, their session data never collides. Telegram's polling state, message history cursor, and any plugin-side data are fully isolated per bot.

tmux + launchd: The Auto-Restart Pattern

Each bot runs inside a named tmux session. This matters for two reasons: tmux sessions survive terminal disconnects, and tmux send-keys lets a watcher script inject input into the running Claude process without attaching to it.

Nine launchd plists (com.mozi.[name]-watcher) run continuously on startup. Each one runs watch.sh for its corresponding bot. The watcher polls every 30 seconds.

The core loop in watch.sh:

while true; do
    if [ -f "$SIGNAL_FILE" ]; then
        rm -f "$SIGNAL_FILE"
        sleep 60
        $TMUX kill-session -t "$SESSION" 2>/dev/null
        $TMUX new-session -d -s "$SESSION" "$START_CMD"
        sleep 15
        $TMUX send-keys -t "$SESSION" "1" Enter
        sleep 5
        $TMUX send-keys -t "$SESSION" "" Enter
    fi

    if ! $TMUX has-session -t "$SESSION" 2>/dev/null; then
        sleep 5
        if ! $TMUX has-session -t "$SESSION" 2>/dev/null; then
            $TMUX new-session -d -s "$SESSION" "$START_CMD"
            sleep 15
            $TMUX send-keys -t "$SESSION" "1" Enter
        fi
    else
        detect_and_dismiss_usage_modal "$SESSION" "$LOG_FILE"
        drain_bot_inbox
    fi
    sleep 30
done

Two paths: signal file (intentional restart, triggered by another bot or admin command) and crash detection (tmux session gone). Both paths start a new tmux session running start.sh, then wait 15 seconds and send "1" Enter.

That 15-second wait and keypress is the fix to the most important bug in this setup.

The Confirmation Prompt Bug

When Claude Code starts, it shows a confirmation prompt asking whether to proceed in the current mode. Without user input, it sits there. The bot technically starts but never processes any Telegram messages because Claude is waiting for the human to press a key.

The naive fix is skipDangerousModePermissionPrompt: true in settings.json. This does not reliably suppress the prompt in server mode. Do not rely on it.

The actual fix: after starting the tmux session, wait long enough for the prompt to appear (15 seconds covers even slow startup), then send the keypress:

$TMUX new-session -d -s "$SESSION" "$START_CMD"
sleep 15
$TMUX send-keys -t "$SESSION" "1" Enter

tmux send-keys injects input into the pane as if a user typed it. The bot receives the "1" Enter, dismisses the prompt, and starts processing messages.

Without this, you get a bot that shows as running in tmux list-sessions but never responds. It is a silent failure. The logs look clean. Telegram messages arrive and pile up. Nothing processes them.

Usage Limit Modal Auto-Dismiss

Fable bots can hit usage limits mid-session. Claude Code displays an interactive modal asking what to do: continue with Fable, switch to Sonnet, or stop. Without auto-dismissal, the bot freezes until a human intervenes.

The detect_and_dismiss_usage_modal function in watch.sh handles this. It:

Captures the current tmux pane content
Looks for phrases like "limit", "credits", or numbered-option markers
Prefers "Continue with Fable" — extracts the digit from the option line and sends it
Falls back to "Switch to Sonnet" if Fable continuation is unavailable
Falls back to sending "1" if no specific option is recognized
Logs every auto-dismiss event to usage_modal.log with a timestamp

This runs on every poll cycle (every 30 seconds). A modal that appears between poll cycles goes undetected for at most 30 seconds, then gets auto-dismissed. The bot continues without human intervention.

Access Control

Each bot has an access list at ~/.claude/channels/[name]/access.json. This is an allowlist of Telegram user IDs. Messages from users not on the list are silently ignored by the plugin.

The structure is straightforward — a JSON object with an array of permitted user IDs. The plugin checks each incoming message against this list before surfacing it to Claude.

This matters when a bot's token is compromised or shared accidentally. Without the allowlist, anyone who finds the token can interact with your bots and run arbitrary tool calls.

Setup Checklist

Per bot:

[ ] Create sessions/[name]/ directory
[ ] Write start.sh with unique TELEGRAM_BOT_TOKEN, TELEGRAM_STATE_DIR, and correct ANTHROPIC_MODEL
[ ] Copy watch.sh from the canonical template — do not write it from scratch
[ ] Write .mcp.json pointing to the shared plugin with bot-specific env vars
[ ] Create ~/.claude/channels/[name]/access.json with permitted Telegram user IDs
[ ] Create the TELEGRAM_STATE_DIR directory
[ ] Test start.sh manually in a terminal first — confirm Claude starts and the prompt appears
[ ] Verify the "1" keypress dismisses the prompt and the bot logs message receipt

For the watcher:

[ ] Write a launchd plist com.mozi.[name]-watcher that runs watch.sh at startup
[ ] Load with launchctl load ~/Library/LaunchAgents/com.mozi.[name]-watcher.plist
[ ] Confirm it appears in launchctl list | grep mozi

Verify everything works:

[ ] Send a test message from an allowlisted Telegram account
[ ] Confirm the bot replies
[ ] Kill the tmux session manually — confirm the watcher restarts it within 60 seconds
[ ] Check that the restart sends the "1" keypress automatically

Common Failure Modes

Bot starts but never responds. Almost always the confirmation prompt. Attach to the tmux session (tmux attach -t [name]) and look. If you see a prompt waiting for input, the send-keys timing is off. Increase the sleep before the keypress.

Two bots receiving the same messages. TELEGRAM_STATE_DIR is shared or identical. Each bot must have a unique state directory. Check the env in .mcp.json and the export in start.sh.

Bot crashes repeatedly. Check the launchd logs and the tmux pane output before it exits. Most crashes are MCP server startup failures — usually a missing bun in PATH, wrong plugin path, or malformed .mcp.json.

Watcher not restarting dead sessions. Confirm the launchd plist is loaded and running. Check launchctl list com.mozi.[name]-watcher. If the tmux binary path in watch.sh is wrong (common when tmux is installed via Homebrew and PATH differs in launchd context), set an absolute path.

The architecture scales linearly. Each new bot is the same pattern: a directory, three files, one launchd plist. The shared plugin means there is no per-bot plugin code to maintain. The watcher handles failures automatically. Once the pattern is running, adding bot number nine is twenty minutes of work.