@claude-flow/plugin-gastown-bridge
WASM-Accelerated Bridge to Steve Yegge's Gas Town Multi-Agent Orchestrator
Introduction
The Gas Town Bridge Plugin brings Steve Yegge's powerful Gas Town multi-agent orchestrator to Claude Flow V3. Gas Town introduces battle-tested concepts for durable workflow execution that complement Claude Flow's swarm intelligence.
What is Gas Town?
Gas Town is a 75,000-line Go codebase that implements:
- Beads - Git-backed issue tracking with graph semantics
- Formulas - TOML-defined workflows (convoy, workflow, expansion, aspect)
- Convoys - Work-order tracking for "slung" work between agents
- GUPP - Gastown Universal Propulsion Principle for crash-resilient execution
- Molecules/Wisps - Chained work units for durable, resumable workflows
Why This Plugin?
| Challenge |
Solution |
| Gas Town is Go-only |
CLI bridge wraps gt and bd commands |
| Go can't compile to WASM (syscalls) |
Hybrid architecture: CLI for I/O, WASM for compute |
| Formula parsing is slow in JS |
Rust→WASM provides 352x speedup |
| Graph operations bottleneck |
WASM DAG ops are 150x faster |
Features
🚀 WASM-Accelerated Computation
| Operation |
JavaScript |
WASM |
Speedup |
| Formula parse (TOML→AST) |
53ms |
0.15ms |
352x |
| Variable cooking |
35ms |
0.1ms |
350x |
| Batch cook (10 formulas) |
350ms |
1ms |
350x |
| DAG topological sort |
75ms |
0.5ms |
150x |
| Cycle detection |
45ms |
0.3ms |
150x |
| Critical path analysis |
120ms |
0.8ms |
150x |
| Pattern search (HNSW) |
5000ms |
5ms |
1000x-12500x |
🔗 20 MCP Tools
┌─────────────────────────────────────────────────────────────┐
│ MCP Tool Categories │
├─────────────────┬─────────────────┬─────────────────────────┤
│ Beads (5) │ Convoy (3) │ Formula (4) │
│ ├─ create │ ├─ create │ ├─ list │
│ ├─ ready │ ├─ status │ ├─ cook (WASM) │
│ ├─ show │ └─ track │ ├─ execute │
│ ├─ dep │ │ └─ create │
│ └─ sync │ │ │
├─────────────────┼─────────────────┼─────────────────────────┤
│ Orchestration │ WASM (5) │ │
│ ├─ sling │ ├─ parse │ │
│ ├─ agents │ ├─ resolve │ │
│ └─ mail │ ├─ cook_batch │ │
│ │ ├─ match │ │
│ │ └─ optimize │ │
└─────────────────┴─────────────────┴─────────────────────────┘
🛡️ Security-First Design
- Input Validation: Zod schemas for all parameters
- Command Injection Prevention: Allowlist-only CLI execution
- Path Traversal Protection: Strict path validation
- No Shell Execution: Uses
execFile with shell: false
🔄 Bidirectional Sync
Seamlessly sync between Gas Town's Beads and Claude Flow's AgentDB:
┌──────────────┐ SyncBridge ┌──────────────┐
│ │ ←───────────────→ │ │
│ Beads │ Conflict Res. │ AgentDB │
│ (JSONL) │ • beads-wins │ (SQLite) │
│ │ • newest-wins │ │
│ │ • merge │ │
└──────────────┘ └──────────────┘
Enhancement & Comparison
Gas Town vs Claude Flow V3
| Feature |
Gas Town |
Claude Flow V3 |
With This Plugin |
| Issue Tracking |
Beads (Git-backed) |
AgentDB |
Unified sync |
| Workflows |
TOML Formulas |
TypeScript |
Both supported |
| Agent Roles |
Mayor, Polecats, Crew |
Hierarchical swarm |
Interoperable |
| Crash Recovery |
GUPP hooks |
Session persistence |
Combined |
| Work Distribution |
Slinging |
Task orchestration |
Bridge via sling tool |
| Pattern Search |
N/A |
HNSW (slow JS) |
HNSW WASM (1000x faster) |
Performance Comparison
| Metric |
Pure JavaScript |
This Plugin (WASM) |
Improvement |
| Formula parse |
53ms |
0.15ms |
352x faster |
| 100-node DAG sort |
75ms |
0.5ms |
150x faster |
| Pattern search (10k) |
5000ms |
5ms |
1000x faster |
| Memory usage |
48MB |
12MB |
4x reduction |
| Startup time |
850ms |
120ms |
7x faster |
Architecture Comparison
| Approach |
Pros |
Cons |
This Plugin |
| Full TypeScript Port |
Native, no deps |
75k lines to port |
❌ |
| Go→WASM Compile |
Reuse code |
Syscalls block it |
❌ |
| Pure CLI Bridge |
Simple |
Slow for compute |
Partial ✓ |
| Hybrid CLI+WASM |
Best of both |
Two codebases |
✅ Selected |
Installation
# Install via Claude Flow CLI (recommended)
npx claude-flow@latest plugins install -n @claude-flow/plugin-gastown-bridge
# Or install directly via npm
npm install @claude-flow/plugin-gastown-bridge
# Prerequisites: Gas Town and Beads CLI (optional - for full CLI integration)
# See: https://github.com/steveyegge/gastown
go install github.com/steveyegge/gastown/cmd/gt@latest
go install github.com/steveyegge/beads/cmd/bd@latest
Usage
Basic Setup
import { GasTownBridgePlugin } from '@claude-flow/plugin-gastown-bridge';
// Initialize the plugin
const plugin = new GasTownBridgePlugin({
gtPath: '/usr/local/bin/gt', // Optional: path to gt CLI
bdPath: '/usr/local/bin/bd', // Optional: path to bd CLI
wasmEnabled: true, // Enable WASM acceleration
});
// Register with Claude Flow
await claudeFlow.registerPlugin(plugin);
Using MCP Tools
// Create a bead (issue)
const bead = await plugin.tools.gt_beads_create({
title: 'Implement feature X',
description: 'Full description here',
priority: 2,
labels: ['feature', 'v3'],
});
// List ready beads (no blockers)
const ready = await plugin.tools.gt_beads_ready({
limit: 10,
rig: 'main',
});
// Cook a formula (WASM-accelerated, 352x faster)
const cooked = await plugin.tools.gt_formula_cook({
formula: 'implement-feature',
vars: {
feature_name: 'Authentication',
target_module: 'src/auth',
},
});
// Sling work to an agent
await plugin.tools.gt_sling({
bead_id: 'gt-abc123',
target: 'polecat',
formula: 'code-review',
});
WASM-Accelerated Operations
// Parse formula (352x faster than JS)
const ast = await plugin.tools.gt_wasm_parse_formula({
content: `
[formula]
name = "deploy-service"
type = "convoy"
[[legs]]
id = "build"
title = "Build the service"
`,
});
// Resolve dependencies (150x faster)
const sorted = await plugin.tools.gt_wasm_resolve_deps({
beads: beadList,
action: 'topo_sort',
});
// Batch cook formulas (352x faster)
const cooked = await plugin.tools.gt_wasm_cook_batch({
formulas: formulaList,
vars: [{ env: 'prod' }, { env: 'staging' }],
});
// Find similar patterns (1000x-12500x faster)
const matches = await plugin.tools.gt_wasm_match_pattern({
query: 'authentication flow',
candidates: formulaNames,
k: 5,
});
Sync Between Beads and AgentDB
// Sync beads to AgentDB
await plugin.tools.gt_beads_sync({
direction: 'push',
rig: 'main',
namespace: 'project-x',
});
// Pull from AgentDB to Beads
await plugin.tools.gt_beads_sync({
direction: 'pull',
conflictStrategy: 'newest-wins',
});
// Bidirectional sync
await plugin.tools.gt_beads_sync({
direction: 'both',
conflictStrategy: 'merge',
});
Tutorial
📖 Tutorial 1: Your First Gas Town Integration
Step 1: Verify Prerequisites
# Check Gas Town CLI
gt --version
# Check Beads CLI
bd --version
# Both should output version numbers
Step 2: Initialize Plugin in Your Project
// claude-flow.config.ts
import { defineConfig } from 'claude-flow';
import { GasTownBridgePlugin } from '@claude-flow/plugin-gastown-bridge';
export default defineConfig({
plugins: [
new GasTownBridgePlugin({
wasmEnabled: true,
}),
],
});
Step 3: Create Your First Bead
const bead = await claudeFlow.mcp.call('gt_beads_create', {
title: 'Hello Gas Town',
description: 'My first bead from Claude Flow!',
priority: 3,
labels: ['tutorial'],
});
console.log(`Created bead: ${bead.id}`);
// Output: Created bead: gt-a1b2c3
Step 4: List Ready Work
const ready = await claudeFlow.mcp.call('gt_beads_ready', {
limit: 5,
});
console.log('Ready beads:', ready.beads.map(b => b.title));
📖 Tutorial 2: Working with Formulas
Understanding Formula Types
| Type |
Purpose |
Example |
convoy |
Multi-leg work orders |
Feature implementation |
workflow |
Step-by-step processes |
CI/CD pipeline |
expansion |
Generate multiple beads |
Test suite creation |
aspect |
Cross-cutting concerns |
Logging, metrics |
Creating a Custom Formula
// Create a code review formula
await claudeFlow.mcp.call('gt_formula_create', {
name: 'code-review-flow',
type: 'workflow',
steps: [
{
id: 'checkout',
title: 'Checkout branch',
description: 'Clone and checkout the PR branch',
},
{
id: 'lint',
title: 'Run linters',
description: 'Execute ESLint and Prettier',
needs: ['checkout'],
},
{
id: 'test',
title: 'Run tests',
description: 'Execute test suite',
needs: ['checkout'],
},
{
id: 'review',
title: 'Code review',
description: 'Manual code review',
needs: ['lint', 'test'],
},
],
vars: {
branch: { type: 'string', required: true },
reviewer: { type: 'string', default: 'auto' },
},
});
Cooking a Formula (WASM-Accelerated)
// Cook the formula with variables
const cooked = await claudeFlow.mcp.call('gt_formula_cook', {
formula: 'code-review-flow',
vars: {
branch: 'feature/auth',
reviewer: '@alice',
},
});
// cooked.steps now have variables substituted
console.log(cooked.steps[3].description);
// Output: "Manual code review by @alice"
📖 Tutorial 3: Convoy Management
What is a Convoy?
A convoy is a "work order" that tracks a set of related beads through their lifecycle. Think of it as a sprint or milestone.
Creating a Convoy
// Create convoy for a feature
const convoy = await claudeFlow.mcp.call('gt_convoy_create', {
name: 'v2.0-release',
description: 'Version 2.0 release convoy',
issues: ['gt-abc1', 'gt-abc2', 'gt-abc3'],
});
console.log(`Convoy created: ${convoy.id}`);
Tracking Convoy Progress
// Check convoy status
const status = await claudeFlow.mcp.call('gt_convoy_status', {
convoy_id: convoy.id,
detailed: true,
});
console.log(`Progress: ${status.progress}%`);
console.log(`Completed: ${status.completed}/${status.total}`);
Optimizing Convoy Execution (WASM)
// Get optimal execution order (150x faster with WASM)
const optimized = await claudeFlow.mcp.call('gt_wasm_optimize_convoy', {
convoy_id: convoy.id,
strategy: 'parallel', // or 'serial', 'hybrid'
});
console.log('Execution plan:', optimized.plan);
// Output shows which beads can run in parallel
📖 Tutorial 4: Slinging Work to Agents
Gas Town Agent Roles
| Role |
Purpose |
mayor |
Coordinator, assigns work |
polecat |
General worker agents |
crew |
Specialized team members |
refinery |
Processing and transformation |
witness |
Verification and validation |
deacon |
Administrative tasks |
dog |
Guard duties, security |
Slinging Work
// Sling a bead to a polecat for coding
await claudeFlow.mcp.call('gt_sling', {
bead_id: 'gt-abc123',
target: 'polecat',
formula: 'implement-feature',
});
// The work is now "on the polecat's hook"
// GUPP: "If work is on your hook, YOU MUST RUN IT"
Listing Available Agents
const agents = await claudeFlow.mcp.call('gt_agents', {
rig: 'main',
role: 'polecat',
include_inactive: false,
});
agents.forEach(agent => {
console.log(`${agent.name}: ${agent.status} (${agent.workload} tasks)`);
});
📖 Tutorial 5: Beads-AgentDB Synchronization
Sync Strategies
| Strategy |
Use Case |
push |
Export beads to AgentDB |
pull |
Import from AgentDB to Beads |
both |
Bidirectional sync |
Conflict Resolution
| Resolution |
Behavior |
beads-wins |
Beads data overwrites AgentDB |
agentdb-wins |
AgentDB data overwrites Beads |
newest-wins |
Most recent modification wins |
merge |
Combine non-conflicting fields |
manual |
Queue conflicts for manual resolution |
Example: Production Sync Workflow
// Morning: Pull overnight changes from shared AgentDB
await claudeFlow.mcp.call('gt_beads_sync', {
direction: 'pull',
rig: 'production',
conflictStrategy: 'newest-wins',
});
// During work: Push local changes
await claudeFlow.mcp.call('gt_beads_sync', {
direction: 'push',
rig: 'production',
namespace: 'team-alpha',
});
// End of day: Full bidirectional sync
const result = await claudeFlow.mcp.call('gt_beads_sync', {
direction: 'both',
conflictStrategy: 'merge',
});
console.log(`Synced: ${result.pushed} pushed, ${result.pulled} pulled`);
console.log(`Conflicts: ${result.conflicts.length}`);
📖 Tutorial 6: WASM Performance Optimization
When to Use WASM Tools
| Use WASM |
Use CLI |
| Parsing formulas |
Creating beads |
| Graph operations |
File I/O |
| Pattern matching |
SQLite queries |
| Batch processing |
Agent communication |
Batch Processing for Maximum Performance
// Instead of this (slow):
for (const formula of formulas) {
await claudeFlow.mcp.call('gt_formula_cook', {
formula: formula.name,
vars: formula.vars,
});
}
// Do this (352x faster):
const results = await claudeFlow.mcp.call('gt_wasm_cook_batch', {
formulas: formulas.map(f => f.name),
vars: formulas.map(f => f.vars),
});
Profiling WASM Performance
// All WASM tools return timing metrics
const result = await claudeFlow.mcp.call('gt_wasm_parse_formula', {
content: formulaToml,
});
console.log(`Parse time: ${result.durationMs}ms`);
// Output: Parse time: 0.14ms
API Reference
Plugin Configuration
interface GasTownBridgeConfig {
/** Path to gt CLI (default: auto-detect) */
gtPath?: string;
/** Path to bd CLI (default: auto-detect) */
bdPath?: string;
/** Enable WASM acceleration (default: true) */
wasmEnabled?: boolean;
/** Default rig for operations */
defaultRig?: string;
/** Sync conflict resolution strategy */
conflictStrategy?: 'beads-wins' | 'agentdb-wins' | 'newest-wins' | 'merge' | 'manual';
/** CLI execution timeout in ms (default: 30000) */
timeout?: number;
}
Tool Reference
See MCP Tools Documentation for complete API reference.
Architecture
┌─────────────────────────────────────────────────────────────────────┐
│ Claude Flow V3 Plugin Host │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────┐ ┌─────────────────────────────────────┐ │
│ │ CLI Bridge │ │ WASM Computation Layer │ │
│ │ (I/O Operations) │ │ (352x faster) │ │
│ │ │ │ │ │
│ │ • gt commands │ │ ┌──────────────┐ ┌──────────────┐ │ │
│ │ • bd commands │ │ │ gastown- │ │ ruvector- │ │ │
│ │ • File read/write │ │ │ formula-wasm │ │ gnn-wasm │ │ │
│ │ • SQLite queries │ │ │ │ │ │ │ │
│ │ │ │ │ • TOML parse │ │ • DAG ops │ │ │
│ │ [Node.js FFI] │ │ │ • Variable │ │ • Topo sort │ │ │
│ │ │ │ │ cooking │ │ • Cycle │ │ │
│ └─────────────────────┘ │ │ • Molecule │ │ detection │ │ │
│ │ │ generation │ │ • Critical │ │ │
│ │ └──────────────┘ │ path │ │ │
│ │ └──────────────┘ │ │
│ │ │ │
│ │ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ micro-hnsw- │ │ ruvector- │ │ │
│ │ │ wasm │ │ learning-wasm│ │ │
│ │ │ │ │ │ │ │
│ │ │ • Pattern │ │ • SONA │ │ │
│ │ │ search │ │ patterns │ │ │
│ │ │ • 1000x+ │ │ • MoE routing│ │ │
│ │ │ speedup │ │ • EWC++ │ │ │
│ │ └──────────────┘ └──────────────┘ │ │
│ │ │ │
│ │ [wasm-bindgen interface] │ │
│ └─────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Related Resources
Contributing
See CONTRIBUTING.md for development setup and guidelines.
License
MIT License - see LICENSE for details.
Built with ❤️ by the Claude Flow Team
