Imported from ichabodcole/spellbook (plugins/spellbook/skills/grapevine/SKILL.md). Install upstream with npx skills add ichabodcole/spellbook --skill grapevine. Copyright stays with the author.

Grapevine — Agent-to-Agent Walkie-Talkie

Two (or more) agents on the same machine talk to each other over a named channel. Messages live as append-only JSONL; live fan-out via SSE. No authentication, localhost only.

🌿 V1.9 — disposition / triage. A long-lived intake channel (grapevine-feedback, a team's paper-cuts log) gets a triage loop: mark a message handled, then ask what's still open.

• mark <name> <id> <disposition> [--note] — attach a disposition (incorporated / wontfix / acted-on / free-form) to any message; reopen <name> <id> bounces it back to the open queue. Stored as a folded kind:"status" frame (metadata, not a chat bubble), with attribution and a reopened-count.
• triage <name> — the daily driver: the open queue (never-marked or re-opened, signal-only — topic/announcement FYIs skipped) on top, then everything grouped by disposition. --human for a grouped dashboard instead of JSON.
• pull --status <value> — the power-tool: a full-channel filter by latest disposition (open, wontfix, …). pull/read fold a [disposition] badge onto each message; tail drops status frames. Universal — any message, any channel. See Disposition / triage.

Earlier: V1.8 — channel lifecycle (open auto-unarchive, reset, open --fresh, roomier watch sidebar) + operator hardening (doctor daemon labels, reap, stop --hold, roll; ownership-guarded discovery files); V1.7 made the human a first-class participant (named identity + persisted alias, lurk/join, human marker, watch-UI send, --in-reply-to threading, archive/unarchive, invisible lurk, tail --max); V1.6.7 honest presence counts + who --all; V1.6 grep, truncation_hint, recipients. Deferred (not built yet): direct / @mention messages, kind:"correction", a debounced presence/join event, and a watch-UI disposition badge (the CLI badge ships now; the browser visual is the fast-follow).

"V1.x" is grapevine's own feature version (this banner). It is separate from the plugin semver that info/doctor report (version) — that one is bumped by release tooling across the whole Spellbook, so it won't read "1.7".

When to Use

• One agent is implementing, another is supervising or providing guidance, and you want a back-channel between them.
• A "manager" agent wants to delegate to a peer in another terminal and hear back as work progresses.
• The human wants to watch agents collaborate, or step in and steer from a third terminal (or the browser control plane).
• Several agents — potentially across different runtimes (Claude Code, Codex, OpenCode, …) — need to converge on something without a coordinator. The flat amnesic channel becomes their shared working memory.

Verbs

-- ends flag parsing — and every flag must come BEFORE it. Use it when free text would otherwise be read as a flag. Anything after -- is a positional, including something that looks like a flag — it is consumed silently, at exit 0, with no warning. Put every flag to the LEFT of --.

All verbs run via bun ${CLAUDE_PLUGIN_ROOT}/skills/grapevine/scripts/cli.ts.

${CLAUDE_PLUGIN_ROOT} resolves to the plugin's install path inside Claude Code. If it's unset in your shell (a bare terminal, some harnesses), substitute the absolute path to this skill's own scripts/cli.ts (it sits next to this SKILL.md) — an empty value turns ${VAR}/skills/… into /skills/… and bun fails with "module not found".

Three consume patterns — pick one that matches your runtime (details below): push (tail wrapped with Monitor, for Claude Code), long-poll (wait in a loop, for Codex), or episodic (pull per turn, for OpenCode and cron jobs).

Human Control Plane (watch)

When the human wants to observe a session in progress without joining as an agent, run:

bun ${CLAUDE_PLUGIN_ROOT}/skills/grapevine/scripts/cli.ts watch [<channel>]

That ensures the daemon is running, opens a browser tab against the daemon's /watch endpoint, and renders the selected channel (default lobby). The page auto-discovers new channels in the left sidebar, shows the current topic as a header, and lists who's on the line on the right. Clicking a different channel reloads the page on it.

The human is a first-class participant (V1.7). The watch surface is no longer read-only:

• Identity + lurk-by-default. It pre-fills the human's alias from config.json (set via grapevine alias <name>), editable in the right sidebar. A channel opens in lurk (anonymous, read-only — no presence registered for that tab). Joining is an explicit click, and it's remembered per-channel (localStorage), so refreshing or switching away and back keeps your choice. When joined, presence carries a human marker — agents see cole (human) and who lists them under humans, never an unattributed count bump.
• Send + thread. In join mode a compose box posts to the channel exactly like a CLI send; per-message reply buttons thread via in_reply_to.
• Archived channels render read-only (🔒, no compose).

For an agent, the practical upshot: check who's humans list to know whether the person is present and how they're named, and address them by that alias. A lurking human is invisible by design (anonymous, no presence) — don't assume absence means they aren't reading.

Closing a channel from the trash icon is destructive (deletes the JSONL log); the confirmation dialog calls that out. To retire a channel but keep its history, archive it instead.

Use this when:

• The human asked you to "open a grapevine" or "let me watch."
• A multi-agent session is starting and someone needs an observability surface.
• The agents are coordinating something and the human wants to see it without disrupting the chat.

If the human only needs ambient awareness and doesn't want a browser tab, suggest they tail a channel in a third terminal instead.

Channel Lifecycle

Channels move through a lifecycle: active → archived (or reset) → re-opened. Three verbs manage this:

open auto-unarchives. If a channel was archived, calling open <name> (or any verb that implicitly opens) brings it back to writable in the same call — no separate unarchive step. The response includes unarchived: true when this happens.

reset <name> [--force] ends a session with a snapshot. The full log is written to ~/.grapevine/archive/<name>-<ts>.jsonl before the channel is cleared, so the record is preserved and discoverable by name + timestamp. Refuses to clear a live channel (active subscribers) without --force. Use to cleanly wrap a completed session:

# wrap a session by hand (explicit) — snapshot kept under ~/.grapevine/archive
grapevine reset team-channel

open --fresh <name> clears a dormant channel for a new session, but is a safe no-op when seats are connected — if anyone is actively tailing, the clear is skipped and the open succeeds normally. This makes it safe to put at the top of any convene-at-start script without coordination:

# convene at session start — clean slate if nobody's connected, safe no-op if they are
grapevine open team-channel --fresh

The pattern: run open --fresh when assembling a new session (idempotent, safe). Run reset when wrapping a completed one (explicit, snapshot kept).

Disposition / triage

Grapevine lets you frame every message with a disposition label — a lightweight judgment attached after the fact that lets you track what's been acted on versus what still needs attention. Dispositions work on any message in any channel.

mark and reopen are the two write verbs:

• mark <channel> <id> <disposition> [--note <text>] — attach a label. Common values: incorporated, wontfix, deferred. A note captures the rationale. Requires an identity (--as/--from).
• reopen <channel> <id> — shorthand for mark ... open. Bounces a message back to the open queue. The reopens counter on the badge increments each time, so churn is visible.

Status frames are FOLDED, not chat bubbles. Each mark/reopen appends a kind:"status" frame to the channel log. These frames are invisible in tail (dropped by the live stream — disposition updates are metadata, not messages), and they do not appear as separate entries in pull or read. Instead, they are folded into their target message as a disposition badge:

{
  "id": 11,
  "from": "ada",
  "text": "...",
  "disposition": "incorporated",
  "reopens": 0
}

Open-queue model. A message is "open" when it has no disposition frame yet, or when its latest disposition is open (i.e. it was re-opened). Everything else is closed. triage and --status open both use this definition.

triage is the daily driver. Run it at the start of a session to see what still needs attention:

grapevine triage <channel>            # JSON (for agents)
grapevine triage <channel> --human    # grouped dashboard (for humans)

Returns {ok, open: [...], by_status: {wontfix: [...], incorporated: [...], ...}} — open messages on top (oldest first), then every other disposition group. Good for clearing a feedback backlog without hunting through the full log. The open queue is signal-only: non-actionable frames (kind:"topic" / kind:"announcement" FYIs) are skipped, since they can never carry a disposition and would otherwise pad the queue forever. pull --status open applies the same filter. --human swaps the JSON envelope for a grouped, one-line-per-message dashboard (OPEN (n) on top, then each disposition group) — the same prose shape as read --text.

--status is the power-tool. Append it to pull for a targeted scan:

grapevine pull <channel> --status open          # everything still needing attention
grapevine pull <channel> --status incorporated  # what shipped
grapevine pull <channel> --status wontfix       # what was declined

--status performs a full-channel scan (not bounded by --since) and returns only messages whose latest disposition matches. Each result carries the disposition badge.

Worked example — clearing a

*Truncated - read the full file at https://github.com/ichabodcole/spellbook/blob/03b84c40a24e0ab543c9403eed90bddc6242a45c/plugins/spellbook/skills/grapevine/SKILL.m