aim-communicate

Files (2)

• SKILL.md
• tmux_send.sh · scripts/

SKILL.md (first lines)

# 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)

```bash
# 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:

```text
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):**

```text
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):**

```text
[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:

```markdown
**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

```bash
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.

| `pane_current_command` | Vessel | Submit |
|------------------------|--------|--------|
| `grok` | Grok TUI | **Enter only** (§4a) |
| `opencode` | OpenCode TUI | **Enter only** (same as Grok; §4a) |
| `agy` / `agy.real` | Antigravity | **Escape, then Enter** (§4b) |

**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)

```bash
# 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 BrianV1981/aim-skill-library, MIT.

More from BrianV1981/aim-skill-library