parallelism — coord protocol for parallel Yodas¶

How N parallel Yodas stay in touch without Vee in the middle¶

Install · How it works · Scripts · Protocol · License

The llamaclaw ecosystem runs multiple Claude Code sessions (“Yodas”) in parallel — some on Vee’s Mac, some on zeus.local (Pi), some invoked via scheduled agents. Before this repo, coordination was by hand: “Yoda A is working on X, so Yoda B, don’t.” That scales O(N²) in human attention.

This repo is the out-of-band channel. Git is the durable bus; zeus’s ~/coord/poke.log is the real-time bus. Every Yoda publishes + subscribes.

Install¶

One-liner (macOS or Linux)¶

curl -fsSL https://raw.githubusercontent.com/llamaclaw/parallelism/main/install.sh | \
    bash -s -- --yoda-id mac-evening --zeus-host yoda@zeus.local

Installs in order:

Clones the repo to ~/.local/share/llamaclaw-parallelism.
Symlinks the 8 coord-* scripts into ~/.local/bin/ (add to PATH if not there).
Installs the 60-second auto-fetch scheduler — launchd (macOS) or systemd timer (Pi/Linux).
Sets YODA_ID in your shell rc (.bashrc or .zshrc).
Wires SSH ControlMaster for coord-watch (shared connection reuse → 1-2 s poke latency).
Optional: installs the Claude Code UserPromptSubmit hook so recent pokes + commits auto-inject on every message.

Manual install (audit first)¶

git clone https://github.com/llamaclaw/parallelism ~/.local/share/llamaclaw-parallelism
cd ~/.local/share/llamaclaw-parallelism
less install.sh          # verify before running
./install.sh --yoda-id mac-morning --zeus-host yoda@zeus.local --dry-run
./install.sh --yoda-id mac-morning --zeus-host yoda@zeus.local

Uninstall¶

~/.local/share/llamaclaw-parallelism/uninstall.sh

Removes launchd/systemd units, symlinks, and the YODA_ID export. Leaves the repo clone in place (delete manually if desired).

How it works¶

Five layers stacked together:

┌──────────────────────────────────────────────────────────┐
│  Layer 5 — UserPromptSubmit hook                          │
│  Injects last 5 pokes + 8 commits on every Enter press    │
│  (Claude Code sees the coord state without being asked.)  │
├──────────────────────────────────────────────────────────┤
│  Layer 4 — Heartbeat (60 s auto-ping)                     │
│  Every Yoda: coord-heartbeat runs every 60s via scheduler │
│  → writes HB line to zeus + stamps local hearts/<id>      │
│  coord-who reports LIVE / STALE / DEAD on demand.         │
├──────────────────────────────────────────────────────────┤
│  Layer 3 — Real-time poke log (~1–2 s)                    │
│  coord-announce  writes  →  zeus:~/coord/poke.log         │
│  coord-watch     SSH-tails the same file                  │
│  (ControlMaster reuses one SSH conn across all tails.)    │
├──────────────────────────────────────────────────────────┤
│  Layer 2 — Auto-fetch scheduler (60 s)                    │
│  Every Yoda host:  git fetch && pull --rebase  every 1min │
│  Pi: systemd timer · Mac: launchd plist                   │
├──────────────────────────────────────────────────────────┤
│  Layer 1 — Git-as-bus (durable, per-Yoda files)           │
│  claims/<yoda-id>.md  — only that Yoda ever writes to it  │
│  log.md               — append-only, never conflicts      │
└──────────────────────────────────────────────────────────┘

Liveness guarantee: any Yoda missing a heartbeat for >3 minutes is flagged DEAD by coord-who. Their stale claims can be taken over safely. No silent disappearances — every Yoda is actively confirmed every minute.

Why this scales to N Yodas without conflicts: per-Yoda claim files mean no two Yodas write the same file. log.md is append-only so concurrent writes land at different byte offsets and git pull --rebase resolves automatically.

Scripts¶

All in bin/ after install (also usable in-place from ~/.local/share/llamaclaw-parallelism/bin/).

Script	Purpose
`coord-claim "<topic>" <ttl-min>`	Claim a scope. Runs a collision scan over recent commits before writing — prompts if a parallel Yoda may have already shipped it. Commits + pushes.
`coord-release "<note>"`	Close a claim. Appends a release event to log.
`coord-check`	Read-only survey. Flags claims past 2× their TTL as `[stale]`. Supports `--mine` and `--json`.
`coord-watch`	Polling system. SSH-tails `~/coord/poke.log` on zeus via ControlMaster (~1–2 s latency). Local-path shortcut when run on zeus itself.
`coord-announce "<msg>"`	Fire a real-time poke to zeus. Best-effort — silently skips if zeus is unreachable (git log is still the source of truth).
`coord-call <topic> --expect N --timeout 10m`	Open a roll-call. Blocks until N Yodas `coord-checkin`. Use when the work would clash badly (refactors, schema changes).
`coord-checkin <call-id>`	Acknowledge a call. Use `--latest` to reply to the most recent open call.
`coord-tally [call-id]`	Show attendance state. `--open` for only open calls; `--all` for full history.
`coord-heartbeat`	Announce liveness. Auto-runs every 60 s via launchd/systemd — every Yoda pings zeus with current state (active claim or `idle`).
`coord-who`	Show which Yodas are live. ✓ LIVE (hb < 90 s) · ~ STALE (< 3 min) · ✗ DEAD (> 3 min). Supports `--live` and `--json`.

Protocol¶

Identity¶

Each Yoda has an ID. Resolution order:

$YODA_ID env var (recommended — set in .bashrc/.zshrc by the installer)
hostname -s fallback
yoda-<pid> last-resort

Typical IDs in Vee’s setup: mac-morning, mac-afternoon, mac-env, zeus, obe24, mac-loadcheck.

On session boot (part of BOOT_LOOP step 8)¶

git pull --quiet                      # absorb others' latest
coord-check                           # see what's being worked on
coord-watch &                         # live-tail for the session

Before significant work (>5 min, user-visible)¶

coord-claim "upgrade esml README" 30  # claim for 30 min

If a parallel-Yoda’s recent commit matches your topic keywords, the script aborts unless you confirm interactively or set COORD_FORCE=1. Rule added 2026-04-17 after three self-duplications in one day (see docs/protocols/collision-scan.md).

When done¶

coord-release "landed at commit abc123"

Roll-call for clashy work¶

# Yoda-A opens a call — blocks for N check-ins.
coord-call "refactor esml.llm provider chain" --expect 2 --timeout 10m

# Yoda-B sees it (via UserPromptSubmit hook or coord-tally --open).
coord-checkin --latest "no overlap on env branch, go ahead"

# Yoda-A exits 0 once quorum is reached. Proceeds.

Exit codes: 0 = quorum reached, 2 = timed out. --expect 0 broadcasts without blocking.

Layout¶

llamaclaw/parallelism/
├── README.md                       # this file
├── install.sh                      # one-command installer (OS-detect + wire everything)
├── uninstall.sh
├── bin/                            # 8 coord-* scripts (user-facing)
├── fetch/                          # 60-s auto-fetch scripts
│   ├── mac-coord-fetch.sh
│   └── llamaclaw-gitsync.sh
├── schedulers/                     # scheduler units — installed by install.sh
│   ├── launchd/com.llamaclaw.coord-fetch.plist
│   └── systemd/llamaclaw-coord-fetch.{service,timer}
├── hooks/
│   └── UserPromptSubmit-coord-status.sh     # Claude Code context injector
├── docs/
│   └── protocols/{claim,polling,roll-call,identity}.md
├── Dockerfile                      # so it gets its GHCR package like every sibling
├── .github/workflows/ci.yml        # shellcheck + dry-run install (macos + ubuntu)
├── CITATION.cff
└── LICENSE                         # GPL-3.0-or-later

Coordination state itself (claims, log) lives in consumer repos — typically yodavision/coordination/ inside llamaclaw/yoda or esml-dev. This repo ships the protocol, not the state.

Design principles¶

Not a locking system. Advisory coordination. Two Yodas could claim the same thing — we trust each other to honor the protocol.
Not real-time everywhere. Git-bus is 30 s–5 min latency. If you need real-time, use coord-announce / coord-watch (SSH poke log).
Not a task queue. Tracks intentions, not work items. Luci’s ~/universe/tasks/ queue on zeus is the real task bus.
Best-effort pokes. coord-announce silently skips if zeus is unreachable — the git log is always the source of truth.

License¶

GPL-3.0-or-later. See LICENSE.