Oh My Pi

🐝 Swarm Orchestration

2 min read

📋 YAML Skeleton

swarm:
  name: my-pipeline
  workspace: ./workspace
  mode: sequential # sequential | parallel | pipeline
  target_count: 1 # pipeline mode only
  model: provider/model-id
  agents:
    AgentA:
      role: "Identity"
      task: "Action. Read/write under workspace/"
      waits_for: [] # explicit deps

🚀 Operations

  • Run:
    • CLI: omp-swarm run.yaml
    • TUI: /swarm run run.yaml
  • Status:
    • TUI: /swarm status run.yaml
  • Background Run:
    • CLI: nohup omp-swarm run.yaml > run.log 2>&1 & disown
  • Logs:
    • Path: tail -f workspace/.swarm_<name>/logs/orchestrator.log

⚙️ Modes

  • sequential: Chain top-to-bottom (default).
  • parallel: Simultaneous execution.
  • pipeline: Repeats DAG target_count times.
  • DAG Control: Use waits_for: [Agent] or reports_to: [Agent]. Explicit dependencies disable sequential chaining.
  • ⚠️ Parallel Race Conditions: Concurrently executing subagents can trigger filesystem race conditions. To prevent data corruption, parallel subagents must use worktree isolation or file locks:
    • Isolated Worktrees (isolated=True / isolated: true): When spawning subagents programmatically, always pass the isolation flag. This runs each agent in an isolated Git worktree context.
      • Python: parallel([lambda: agent("Plan refactor", isolated=True)])
      • JavaScript: await parallel([() => agent("Plan refactor", { isolated: true })])
    • File Locking: If parallel agents must write to the same files (e.g., workspace/data.json), serialize access using a file locking mechanism.
      • Bash: (flock -x 200; # critical section; read/write) 200>workspace/lockfile

🔄 State

  • Payloads: Managed via filesystem sharing (e.g., workspace/data.json).
  • Resumes: Unsupported. State resets to pending on execution.
  • Reset State: rm -rf workspace/.swarm_<name>/

🛠️ Plugin Eject

Prevent omp update overriding local edits:

cp -r ~/.omp/plugins/node_modules/@oh-my-pi/swarm-extension ~/.omp/extensions/my-swarm
sed -i 's/"@oh-my-pi\/swarm-extension"/"my-swarm"/' ~/.omp/extensions/my-swarm/package.json
ln -s ~/.omp/plugins/node_modules ~/.omp/extensions/my-swarm/node_modules
cd ~/.omp/plugins
bun remove @oh-my-pi/swarm-extension
bun add file:../extensions/my-swarm

🧪 Validations

  • Dry-run check: bash docs/omp/examples/validate-all-examples.sh

Graph View

Backlinks