Aim Communicate

AIM-Communicate: Inter-Agent Tmux Protocol

You may operate where multiple AI agents run in different tmux sessions (board room / swarm). Common sessions: aim-agy, aim-grok, grok-audit, aim-connect, aim-youtube, reincarnation vessels (agy_reincarnation_*, grok_reincarnation_*), ayrianna-scraper, etc.

0. MANDATORY: Session identity + reply routing (do not skip)

Every inter-agent message MUST state:

1. FROM — the exact tmux session you are running in now
2. REPLY_TO — the exact tmux session the peer must answer (almost always = the orchestrator’s FROM)

0a. Discover your own session (always run first)

# Preferred (when your pane is the active one in a known session):
tmux display-message -p '#{session_name}'

# If that is empty/wrong (nested/detached), find by cwd or list:
tmux list-panes -a -F '#{session_name} #{pane_current_command} #{pane_current_path}'

Record that name. Do not guess aim-grok vs grok-audit. They are different orchestrators.

0b. Required Message Foundation

When you communicate with another agent, you MUST lay the foundation along with the message. Your message must begin with exactly this block:

To: <target_tmux_session_name> (You are receiving this in tmux session <target_tmux_session_name>. Note: Agents are identified by their tmux session name)
From: <your_tmux_session_name> (My tmux session name)
INSTRUCTION: Please review your `aim-communicate` skill BEFORE responding to this message.

[REPORT|DISPATCH from <role>] <message body>

Examples (correct):

To: agy_reincarnation_1783842559 (You are receiving this in tmux session agy_reincarnation_1783842559...)
From: grok-audit (My tmux session name)
INSTRUCTION: Please review your `aim-communicate` skill BEFORE responding to this message.

[DISPATCH] Merge #92-95 — read /path/DISPATCH.md

Wrong (causes misdelivery):

[REPORT from aim-agy] Merged #92-#95 — read /path/REPORT.md
# Missing the To/From/Instruction foundation → causes confusion and broken workflows.

0c. Dispatch files MUST include

In every chalkboard dispatch:

**FROM (sender tmux session):** `grok-audit`
**REPLY_TO (mandatory reply session):** `grok-audit`
**Also notify (optional secondary):** `aim-grok`   # only if Operator wants a CC

Peer agents must paste reports to REPLY_TO only unless Operator adds a CC list.
If both aim-grok and grok-audit are listed, primary is always REPLY_TO.

0d. Incident (2026-07-12)

Orchestrator on grok-audit ordered aim-agy to report to grok-audit. The agent reported only to aim-grok, so the live orchestrator did not see the paste. Fix: mandatory [FROM:…] [REPLY_TO:…] on every short paste + dispatch header.

0e. Incident (2026-07-19) — “replied in chat only”

Orchestrator answered another agent only in its own chat UI and never pasted into the peer’s tmux session. Peer waited forever. Fix: delivery is not done until §3d / §3e verification passes against the target session pane.

1. Permission mandate

You are forbidden from unilaterally messaging another agent's tmux session unless the Operator explicitly approves.

• Operator text like "tell aim-agy …" / "communicate with …" is approval for that target and intent.
• Incoming aim-communicate paste from another session is approval to reply to their REPLY_TO / From session.
• Do not open open-ended multi-hop chat without Operator in the loop.

2. Discover targets first

tmux list-sessions
tmux list-panes -a -F '#{session_name} #{pane_current_command} #{pane_current_path}'
tmux capture-pane -t <session> -p -J -S -20

Wait for idle prompt when possible.

Note: Project name ≠ session name. An aim-agy agent may run in agy_reincarnation_* or aim-agy. Always use the tmux session string, not the repo name alone.

3. Chalkboard + short paste

3a. Write full content to disk

Prefer paths under the target or sender project (planning-artifacts/, docs/).

3b. Helper script (required on Grok vessels)

# Auto-detect FROM session; force REPLY_TO into the message prefix if missing.
# Exits 0 only if target tmux pane verification passes; exits 2 on VERIFY_FAIL.
#
# Grok vessel (preferred when pane_current_command is grok):
bash "$PROJECT_ROOT/.grok/skills/aim-communicate/scripts/tmux_send.sh" \
  --target ayrianna-scraper \
  --from "$(tmux display-message -p '#{session_name}')" \
  --reply-to grok-audit \
  --message 'Merged #92-#95 — read /abs/path/REPORT.md'

# AGY / Antigravity vessel (when skills live under .gemini):
bash "$PROJECT_ROOT/.gemini/skills/aim-communicate/scripts/tmux_send.sh" \
  --target ayrianna-scraper \
  --from "$(tmux display-message -p '#{session_name}')" \
  --reply-to grok-audit \
  --message 'Merged #92-#95 — read /abs/path/REPORT.md'

The script:

1. Prefixes [FROM:…] [REPLY_TO:…] when missing
2. Pastes with correct vessel submit (Grok Enter / AGY Esc→Enter)
3. Captures the target session pane and verifies the message is present
4. Retries submit once/twice if needed
5. Exits non-zero if verification fails — you must treat that as “not sent”

Canonical script path (keep vessels in sync — do not delete either):

• $PROJECT_ROOT/.grok/skills/aim-communicate/scripts/tmux_send.sh — Grok
• $PROJECT_ROOT/.gemini/skills/aim-communicate/scripts/tmux_send.sh — AGY
• ~/.gemini/antigravity-cli/skills/aim-communicate/scripts/tmux_send.sh (if universally installed)
• ~/.grok/skills/aim-communicate/scripts/tmux_send.sh (user-global Grok)

3c. Manual short paste (only if script unavailable)

FROM=$(tmux display-message -p '#{session_name}')
TARGET=ayrianna-scraper
REPLY_TO=grok-audit

cat << EOF > /tmp/aim_msg.txt
To: ${TARGET} (You are receiving this in tmux session ${TARGET}. Note: Agents are identified by their tmux session name)
From: ${FROM} (My tmux session name)
INSTRUCTION: Please review your \`aim-communicate\` skill BEFORE responding to this message.

[REPORT from ${FROM}] Closed #N — read /abs/path/REPORT.md
EOF

tmux load-buffer /tmp/aim_msg.txt
tmux paste-buffer -p -t "$TARGET"
# vessel-specific submit — §4
# THEN you MUST run §3e verification yourself

3d. MANDATORY — Verify delivery by looking at the target tmux session

Answering only in your own chat is NOT delivery.
After every paste (script or manual), you MUST confirm the target session shows your message.

Preferred: trust tmux_send.sh exit code

Required manual verification (always if not using script, or to double-check)

TARGET=<exact_session>
NEEDLE='[FROM:grok-audit]'   # or another unique substring you pasted

sleep 1.2
tmux capture-pane -t "$TARGET" -p -J -S -40 | tee /tmp/aim_comm_verify_last.txt | tail -40

# Must find your message:
grep -F -- "$NEEDLE" /tmp/aim_comm_verify_last.txt

Success signals (any strong combo):

Failure signals:

Agent hard rules after verify:

1. If verify fails → retry once with tmux_send.sh, then report failure to Operator.
2. Never say “I told ayrianna-scraper …” unless verify passed.
3. Paste a short excerpt of the capture (or script VERIFY_OK line) when reporting to Operator.

3e. Verification checklist (copy into your head)

[ ] Correct TARGET session name (list-sessions, not project nickname)
[ ] FROM + REPLY_TO on the message
[ ] paste + correct submit (Grok Enter / AGY Esc→Enter)
[ ] capture-pane -t TARGET
[ ] unique needle grepped in that capture
[ ] only THEN claim delivery

4. Submit rules (vessel-specific)

4a. Grok (grok) — Enter only

tmux send-keys -t <target> Enter
# optional fallback: C-m

Never send Escape before Enter on Grok (Esc clears/cancels; does not send).

4b. AGY (agy / agy.real) — Escape then Enter (separate calls)

tmux send-keys -t <target> Escape
sleep 0.3
tmux send-keys -t <target> Enter

4c. Do / Don't

5. Loop prevention

Structure:
1. AGREED / MERGED (issue #s, SHAs)
2. DISAGREE / NOTES
3. QUESTIONS
4. NEXT
No open-ended chat loop.

6. Host map (re-check live with list-sessions)

Orchestrator on this host often lives in grok-audit, not aim-grok. Read REPLY_TO from the dispatch.

OpenCode vessel skill (extra notes):
~/aim-opencode/.opencode/skills/aim-communicate/SKILL.md

7. Anti-patterns

• Reporting to aim-grok when REPLY_TO was grok-audit
• Omitting FROM/REPLY_TO
• Using project nickname (aim-agy) as session name when you are actually agy_reincarnation_*
• AGY Escape→Enter on Grok
• Replying only in your own chat instead of pasting into the peer tmux session
• Claiming “sent” without capture-pane / script VERIFY_OK
• Secrets in pastes
• Force-push / destructive ops without Operator

8. Incident log

1. 2026-07-12 Grok submit: Escape→Enter left pastes unsent on Grok. Fix: Enter only.
2. 2026-07-12 Wrong reply session: aim-agy reported merge of #92–#95 to aim-grok instead of orchestrator grok-audit. Fix: mandatory FROM + REPLY_TO (§0).
3. 2026-07-19 Chat-only reply: Orchestrator answered ayrianna-scraper in local chat and never tmux-pasted. Fix: mandatory target-pane verification (§3d); tmux_send.sh exits 2 on VERIFY_FAIL.