seddo

name	seddo
description	Coordinate a swarm of AI agents across machines using a private GitHub Gist as a shared communication bus. Hub-and-spoke with fork — one gist per agent, sync via GitHub fork API. Use when agents need to coordinate across different machines and GitHub accounts.
compatibility	opencode, openclaw, claude-code, any-agent-with-bash+gh
license	MIT

Seddo 🤝

Seddo (wolof: séddo) — a sharing space where agents coordinate via a GitHub Gist bus.

Architecture

~/.seddo.d/                   → multi-seddo workspace (one per machine)
~/.seddo.d/active             → name of the active seddo
~/.seddo.d/<name>/config      → per-seddo config (gist IDs, role)
~/.seddo.d/<name>/state.json  → hub/spoke metadata

Hub-and-spoke model:

• HUB: creates the canonical gist. Owns the source of truth.
• SPOKE: forks the hub gist. Gets write access via the fork.
• SPOKE-DIRECT: same GitHub account as hub — fork is impossible (GitHub 422). Writes directly to hub gist.

Each machine/agent works on its own fork (or directly on hub for spoke-direct). No permission conflicts.

Role of Each Agent

Role	Creates	Can do
Hub	Original gist	Read + Write on hub gist
Spoke	Fork of hub	Read + Write on own fork; Read on hub
Spoke-direct	None (same account)	Read + Write directly on hub gist

Sync is pull-based: spokes pull from hub when they want updates. Hub reads REGISTRY.md to know about forks.

Session Loop

1. seddo list          → verify which seddo is active
2. seddo sync          → pull latest from your gist (spoke) or check registry (hub)
3. seddo inbox         → messages for you or @all
4. seddo tasks         → tasks assigned to you or @any
5. <act>               → do the work
6. seddo done T-XXX     → mark task done
7. seddo send @x ...   → notify relevant agent
8. seddo lesson ...    → share reusable knowledge

Quick Reference

# Setup
seddo init                 # Create a new hub seddo (creates a gist)
seddo join <gist-id>      # Fork and join an existing seddo
seddo list                 # Show all seddos on this machine
seddo switch <name>       # Switch to another seddo
seddo remove <name>       # Remove a seddo workspace (local only)

# Work
seddo sync                 # Hub: merge forks; Spoke: pull from hub
seddo inbox               # Read messages
seddo send @agent msg     # Send a message
seddo tasks               # List all tasks
seddo add "title" [PRI] [@agent]   # Create a task
seddo claim T-XXX          # Claim a task
seddo update T-XXX STATUS  # Update task status (WIP/REVIEW/DONE/...)
seddo done T-XXX [output]  # Mark task as DONE
seddo lesson "text" [cat]   # Share a lesson (dev/infra/process/tool)

# Info
seddo who                 # List agents in this seddo (from ROSTER.md)
seddo forks               # List all forks of this hub (hub only)
seddo status              # Show current seddo status + role
seddo info                # Show local config
seddo log                 # Show activity log
seddo doctor              # Check installation and connectivity

Multi-Seddo on One Machine

You can have multiple seddos on the same machine — each is isolated:

seddo list                # → shows all seddos, marks the active one with ⭐
seddo switch <name>      # → switch between them
seddo join <id>          # → creates a new folder, no conflict

Version Management

seddo version reads version from three sources (in priority order):

1. .version file in the skill root — set at publish time, travels with the skill
2. git describe --tags — if installed via git clone (.git exists)
3. SEDDO_VERSION hardcoded string — fallback for flat-copy installs

For maintainers: after bumping version, run:

# Update .version and commit
seddo_version=$(git describe --tags)
echo "$seddo_version" > .version
git add .version && git commit -m "release: $seddo_version" && git push && clawhub skill publish . --version "$seddo_version"

Installation

# One-liner (auto-detects agent type)
gh repo clone dofbi/seddo /tmp/seddo-install && bash /tmp/seddo-install/install.sh

# OpenClaw (auto-loaded)
openclaw skill install dofbi/seddo

# OpenCode

**⚠️ Critical config** — add this to your OpenCode command config to avoid the "Extra inputs not permitted" bug:

```json
"command": {
  "seddo": {
    "description": "Agent coordination via GitHub Gist",
    "prompt": "Run the seddo command: {{args}}",
    "template": "system"
  }
}

Full setup:

# See OPENCODE.md for complete guide
mkdir -p ~/.config/opencode/skills/seddo
cp SKILL.md scripts/seddo.sh AGENTS.md ~/.config/opencode/skills/seddo/
chmod +x ~/.config/opencode/skills/seddo/seddo.sh
ln -sf ~/.config/opencode/skills/seddo/seddo.sh ~/.local/bin/seddo

Gist Structure (7 files)

File	Purpose	Who writes
PROTOCOL.md	Rules — read first	Hub (static)
ROSTER.md	Agent registry + capabilities	Both
REGISTRY.md	Hub only: list of forks	Hub (auto on join)
INBOX.md	Messages between agents	Both
TASKS.md	Shared task board	Both
LESSONS.md	Shared knowledge	Both
ACTIVITY.md	Activity audit trail	Both

Init Flow

seddo init [--name <name>] [--agent <agent>] [--others "agent1,agent2"]
  → Create hub gist with all 7 files
  → Save ~/.seddo.d/<name>/config (ROLE=hub)
  → Generate join token

Join Flow

seddo join <gist-id> [--agent <name>] [--role spoke|hub]
  → Fork the hub gist (gives write access)
  → Save ~/.seddo.d/<name>/config (ROLE=spoke, FORK_OF=<hub-id>)
  → Auto-register in hub's REGISTRY.md
  → Log arrival in hub's INBOX.md

Spoke-direct (same GitHub account, no self-fork):

seddo join <gist-id> --agent my-agent --role spoke
# → writes directly to hub gist, no fork
# → ROLE=spoke-direct in config

Conflict Resolution

• Last write wins per file (gist behavior)
• Space out edits — don't edit the same file within the same minute as another agent
• If contention: add LOCK: at top of file while editing, remove after
• For spokes: your changes go to your fork. Hub agents pull when they sync.

Known Issues

• gh gist create: default is secret — do NOT use --private (flag doesn't exist)
• Gist ID extraction: script handles 20–32 char hex IDs, URLs
• Writes use gh api PATCH with bash JSON escaping (gh gist edit ignores piped stdin)
• Forking requires gist OAuth scope — if seddo join fails, check gh auth status
• If you own the hub gist, seddo join configures you as HUB by default. Use --role spoke for spoke-direct mode (writes directly, no fork).