Development

Development

Repository Layout

opencode-omoc-swarm/
├── plugins/
│   ├── omoc-swarm.ts           ← main plugin (all 8 tools)
│   ├── registry.ts             ← persistent swarm registry
│   ├── registry.test.ts        ← unit tests for registry
│   ├── registry-roundtrip.test.ts  ← roundtrip serialization tests
│   ├── state.ts                ← event log + memory + path reservation
│   └── migration.test.ts       ← migration tests
├── bin/
│   └── oc-swarm                ← tmux launcher script
├── scripts/
│   ├── oc-swarm-smoke.test.sh  ← dependency smoke test
│   └── oc-swarm-e2e.test.sh    ← live E2E test suite
├── templates/
│   ├── bin/opencode            ← wrapper for per-project bin/
│   └── .envrc                  ← direnv config
├── lib/
│   └── observe.ts              ← observability CLI implementation
├── types/
│   └── ...                     ← shared TypeScript types
├── benchmarks/
│   └── ...                     ← performance benchmarks
├── governance/
│   └── ...                     ← repo governance config
├── platforms/
│   └── registry.json           ← platform registry
├── n8n-workflows/
│   └── inbound-intake.json     ← n8n workflow for intake automation
├── package.json
├── tsconfig.json
└── bun.lock

---

Running Tests

# Unit tests (registry, state)
bun run plugins/registry.test.ts
bun run plugins/registry-roundtrip.test.ts

# Smoke test (checks dependencies)
bash scripts/oc-swarm-smoke.test.sh

# Live E2E tests (requires opencode on PATH)
bun run test:e2e

# All CI checks
bun run ci

# All CI + E2E
bun run ci:with-e2e

Note: Live E2E tests skip gracefully if opencode is not available on PATH.

---

Observability & Eval

bun run observe stats
bun run observe history <swarmId>
bun run observe export <swarmId> json
bun run memory list
bun run eval

---

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feat/my-feature
3. Make changes to plugins/omoc-swarm.ts (and registry.ts / state.ts as needed)
4. Add tests in plugins/*.test.ts
5. Run the full test suite: bun run ci
6. Open a Pull Request

Code Style

• TypeScript strict mode
• No external runtime dependencies (only @opencode-ai/sdk and @opencode-ai/plugin)
• All tool parameters must use schema.* from the plugin SDK
• Every tool must append an event via appendSwarmEvent

Adding a New Tool

"swarm.mytool": tool({
  description: "What this tool does.",
  args: {
    id: schema.string().min(1).optional().describe("Optional swarm id"),
    // ... other args
  },
  async execute(args: any, context: any) {
    const result = await resolveSwarm(client, args.id, context.sessionID, context.directory, context.worktree);
    if ("error" in result) return result.error;

    await appendSwarmEvent(context.directory, {
      type: "swarm.mytool",
      swarmId: result.swarmId,
      sessionID: context.sessionID,
      data: { /* ... */ },
    });

    return "result string";
  },
}),

---

Known Limitations

• Queue runner support is not implemented
• Title parsing is only a legacy discovery fallback; registry state is the source of truth for agent identity
• swarm.max requires a git repository — bare repos and non-git directories are not supported
• The selector in MAX mode sees unified diffs only, not full file content; very large changes may degrade selector quality