██████╗ ██████╗ ███████╗███╗ ██╗ ██████╗ ██████╗ ██████╗ ███████╗
██╔═══██╗██╔══██╗██╔════╝████╗ ██║██╔════╝██╔═══██╗██╔══██╗██╔════╝
██║ ██║██████╔╝█████╗ ██╔██╗ ██║██║ ██║ ██║██║ ██║█████╗
██║ ██║██╔═══╝ ██╔══╝ ██║╚██╗██║██║ ██║ ██║██║ ██║██╔══╝
╚██████╔╝██║ ███████╗██║ ╚████║╚██████╗╚██████╔╝██████╔╝███████╗
╚═════╝ ╚═╝ ╚══════╝╚═╝ ╚═══╝ ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝
██████╗ ██████╗ ███╗ ██╗███████╗██╗ ██████╗
██╔════╝██╔═══██╗████╗ ██║██╔════╝██║██╔════╝
██║ ██║ ██║██╔██╗ ██║█████╗ ██║██║ ███╗
██║ ██║ ██║██║╚██╗██║██╔══╝ ██║██║ ██║
╚██████╗╚██████╔╝██║ ╚████║██║ ██║╚██████╔╝
╚═════╝ ╚═════╝ ╚═╝ ╚═══╝╚═╝ ╚═╝ ╚═════╝
"These are intelligent and structured group dynamics that emerge not from a leader, but from the local interactions of the elements themselves." — Daniel Shiffman, The Nature of Code
A swarm of agents that learns from its mistakes.
An OpenCode configuration that turns Claude into a multi-agent system. You describe what you want. It decomposes the work, spawns parallel workers, tracks what strategies work, and adapts. Anti-patterns get detected. Proven patterns get promoted. Confidence decays unless revalidated.
Built on joelhooks/swarmtools - multi-agent orchestration with outcome-based learning.
Important
This is an OpenCode config, not a standalone tool. Everything runs inside OpenCode. The CLIs (swarm, semantic-memory, cass) are backends that agents call - not meant for direct human use.
git clone https://github.com/joelhooks/opencode-config ~/.config/opencode
cd ~/.config/opencode && bun installNote
These CLIs are backends that OpenCode agents call. You install them, but the agents use them.
# Swarm orchestration (required) - agents call this for coordination
npm install -g opencode-swarm-plugin
swarm --version # 0.30.0+
# Ollama for embeddings (required for semantic features)
brew install ollama # or: curl -fsSL https://ollama.com/install.sh | sh
ollama serve
ollama pull nomic-embed-text
# Semantic memory (optional but recommended)
npm install -g semantic-memory
semantic-memory check
# Cross-agent session search (optional but recommended)
npm install -g cass-search
cass index
cass --version # 0.1.35+swarm doctorWarning
All commands run inside OpenCode, not in your terminal. The swarm CLI is a backend that agents call - it's not meant for direct human use.
Start OpenCode, then type:
/swarm "Add user authentication with OAuth"
Watch it decompose → spawn workers → coordinate → verify → learn.
The agent orchestrates everything. You just describe what you want.
| Tool | Version | Install Command |
|---|---|---|
| swarm | 0.30.0 | npm i -g opencode-swarm-plugin |
| semantic-memory | latest | npm i -g semantic-memory |
| cass | 0.1.35 | npm i -g cass-search |
| ollama | 0.13.1 | brew install ollama |
Embedding model: nomic-embed-text (required for semantic-memory and pdf-brain)
# Kernel cloud browser (Playwright in the cloud)
opencode mcp auth kernel
# Snyk security scanning
snyk auth"Elaborate feedback on errors has repeatedly been found to be more effective than knowledge of results alone." — Jeroen van Merriënboer, Ten Steps to Complex Learning
┌─────────────────────────────────────────────────────────────────┐
│ LEARNING PIPELINE │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ CASS │───▶│ Decompose │───▶│ Execute │ │
│ │ (history) │ │ (strategy) │ │ (workers) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │ │
│ │ ▼ │
│ │ ┌─────────────┐ │
│ │ │ Record │ │
│ │ │ Outcome │ │
│ │ └─────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ PATTERN MATURITY │ │
│ │ candidate → established → proven → deprecated │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ • Confidence decay (90-day half-life) │
│ • Anti-pattern inversion (>60% failure → AVOID) │
│ • Implicit feedback (fast+success vs slow+errors) │
│ │
└─────────────────────────────────────────────────────────────────┘
Every task execution feeds the learning system:
- Fast + success → pattern gets promoted
- Slow + retries + errors → pattern gets flagged
- >60% failure rate → auto-inverted to anti-pattern
- 90-day half-life → confidence decays unless revalidated
CASS searches across ALL your AI agent histories before solving problems:
- Indexed agents: Claude Code, Codex, Cursor, Gemini, Aider, ChatGPT, Cline, OpenCode, Amp, Pi-Agent
- Semantic + full-text search - find past solutions even if phrased differently
Semantic Memory persists learnings across sessions with vector search:
- Architectural decisions (store the WHY, not just WHAT)
- Debugging breakthroughs (root cause + solution)
- Project-specific gotchas (domain rules that tripped you up)
┌─────────────────────────────────────────────────────────────────┐
│ COORDINATOR vs WORKER │
├─────────────────────────────────────────────────────────────────┤
│ │
│ COORDINATOR (Expensive, Long-Lived) │
│ ┌──────────────────────────────────────┐ │
│ │ • Sonnet context ($$$) │ │
│ │ • NEVER edits code │ │
│ │ • Decomposes + orchestrates │ │
│ │ • Monitors progress │ │
│ └──────────────────────────────────────┘ │
│ │ │
│ ├─── spawns ───┐ │
│ │ │ │
│ ┌──────────────────▼───┐ ┌────────▼──────────┐ │
│ │ WORKER (Disposable) │ │ WORKER │ │
│ │ ┌─────────────────┐ │ │ ┌───────────────┐│ │
│ │ │ Focused context │ │ │ │ Focused ctx ││ │
│ │ │ Executes task │ │ │ │ Executes task ││ │
│ │ │ Checkpointed │ │ │ │ Checkpointed ││ │
│ │ │ Tracks learning │ │ │ │ Tracks learn ││ │
│ │ └─────────────────┘ │ │ └───────────────┘│ │
│ └──────────────────────┘ └───────────────────┘ │
│ │
│ Result: 70% cost reduction, better recovery, learning signals │
│ │
└─────────────────────────────────────────────────────────────────┘
Workers get disposable context. Coordinator context stays clean. Parallel work doesn't blow the context window.
███████╗██╗ ██╗ █████╗ ██████╗ ███╗ ███╗
██╔════╝██║ ██║██╔══██╗██╔══██╗████╗ ████║
███████╗██║ █╗ ██║███████║██████╔╝██╔████╔██║
╚════██║██║███╗██║██╔══██║██╔══██╗██║╚██╔╝██║
███████║╚███╔███╔╝██║ ██║██║ ██║██║ ╚═╝ ██║
╚══════╝ ╚══╝╚══╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚═╝
Built on joelhooks/swarmtools - the core innovation.
Hive (git-backed work tracker):
- Atomic epic + subtask creation
- Status tracking (open → in_progress → blocked → closed)
hive_create,hive_create_epic,hive_query,hive_close,hive_sync
Agent Mail (multi-agent coordination):
- File reservation system (prevent edit conflicts)
- Message passing between agents
- Context-safe inbox (max 5 messages, bodies excluded by default)
swarmmail_init,swarmmail_send,swarmmail_reserve,swarmmail_release
Swarm Tools (orchestration):
- Strategy selection + decomposition validation
- Progress tracking (25/50/75% checkpoints)
- Completion verification gates (UBS + typecheck + tests)
swarm_decompose,swarm_validate_decomposition,swarm_complete,swarm_record_outcome
┌────────────────────┬──────────────────────────────────────────────┐
│ /swarm <task> │ Decompose → spawn parallel agents → merge │
│ /swarm-status │ Check running swarm progress │
│ /swarm-collect │ Collect and merge swarm results │
│ /parallel "a" "b" │ Run explicit tasks in parallel │
│ │ │
│ /debug-plus │ Debug + prevention pipeline + swarm fix │
│ /fix-all │ Survey PRs + cells, dispatch agents │
│ /iterate <task> │ Evaluator-optimizer loop until quality met │
└────────────────────┴──────────────────────────────────────────────┘
Full command list: /commit, /pr-create, /worktree-task, /handoff, /checkpoint, /retro, /review-my-shit, /sweep, /focus, /rmslop, /triage, /estimate, /standup, /migrate, /repo-dive.
12 MCP tools built for this config:
Multi-language bug detection (JS/TS, Python, C++, Rust, Go, Java, Ruby):
- Null safety, XSS, injection, async/await race conditions, memory leaks
ubs_scan(staged=true) # Before commit
ubs_scan(path="src/") # After AI generates codecass_search(query="authentication error", limit=5)
cass_search(query="useEffect cleanup", agent="claude", days=7)semantic-memory_store(information="OAuth tokens need 5min buffer", tags="auth,tokens")
semantic-memory_find(query="token refresh", limit=5)
semantic-memory_find(query="token refresh", expand=true) # Full contentrepo-autopsy_*- Deep GitHub repo analysis (AST grep, blame, hotspots, secrets)repo-crawl_*- GitHub API exploration (README, files, search)pdf-brain_*- PDF & Markdown knowledge base (URLs supported,--expandfor context)typecheck- TypeScript check with grouped errorsgit-context- Branch, status, commits in one call
| Server | Purpose |
|---|---|
| next-devtools | Next.js dev server integration (routes, errors, build) |
| chrome-devtools | Browser automation, DOM inspection, network monitoring |
| context7 | Library documentation lookup (npm, PyPI, Maven) |
| fetch | Web fetching with markdown conversion |
| snyk | Security scanning (SCA, SAST, IaC, containers) |
| kernel | Cloud browser automation, Playwright, app deployment |
┌─────────────────┬───────────────────┬────────────────────────────────┐
│ Agent │ Model │ Purpose │
├─────────────────┼───────────────────┼────────────────────────────────┤
│ swarm/planner │ claude-sonnet-4-5 │ Strategic task decomposition │
│ swarm/worker │ claude-sonnet-4-5 │ Parallel task implementation │
│ explore │ claude-haiku-4-5 │ Fast search (read-only) │
│ archaeologist │ claude-sonnet-4-5 │ Codebase exploration (r/o) │
│ beads │ claude-haiku │ Issue tracker (locked down) │
│ refactorer │ default │ Pattern migration │
│ reviewer │ default │ Code review (read-only) │
└─────────────────┴───────────────────┴────────────────────────────────┘
"Legacy code is simply code without tests." — Michael Feathers, Working Effectively with Legacy Code
| Skill | When to Use |
|---|---|
| testing-patterns | Adding tests, breaking dependencies, characterization tests |
| swarm-coordination | Multi-agent decomposition, parallel work |
| cli-builder | Building CLIs, argument parsing, subcommands |
| learning-systems | Confidence decay, pattern maturity |
| skill-creator | Meta-skill for creating new skills |
| system-design | Architecture decisions, module boundaries |
skills_use(name="testing-patterns")
skills_use(name="cli-builder", context="building a new CLI tool")Tip
testing-patterns includes 25 dependency-breaking techniques from Feathers' Working Effectively with Legacy Code. Gold for getting gnarly code under test.
| File | Topics |
|---|---|
tdd-patterns.md |
RED-GREEN-REFACTOR, characterization tests |
error-patterns.md |
Known error signatures + solutions |
prevention-patterns.md |
Debug-to-prevention workflow |
nextjs-patterns.md |
RSC, caching, App Router gotchas |
effect-patterns.md |
Services, Layers, Schema, error handling |
testing-patterns.md |
Test strategies, mocking, fixtures |
typescript-patterns.md |
Type-level programming, inference, narrowing |
Load via @knowledge/file-name.md references when relevant.
┌─────────────────────────────────────────────────────────────────┐
│ ~/.config/opencode │
├─────────────────────────────────────────────────────────────────┤
│ command/ 25 slash commands (/swarm, /debug, etc.) │
│ tool/ 12 custom MCP tools (cass, ubs, etc.) │
│ plugin/ swarm.ts (orchestration) │
│ agent/ specialized subagents (worker, planner...) │
│ knowledge/ context files (tdd, effect, nextjs, etc.) │
│ skills/ 7 injectable knowledge packages │
│ opencode.jsonc main config (models, MCP servers, perms) │
│ AGENTS.md workflow instructions + tool preferences │
└─────────────────────────────────────────────────────────────────┘
- joelhooks/swarmtools - The swarm orchestration core
- nexxeln/opencode-config -
/rmslop, notify plugin, Effect-TS patterns - OpenCode - The foundation
MIT
"One person's pattern can be another person's primitive building block." — Eric Evans, Domain-Driven Design