@claude-flow/plugin-gastown-bridge

@claude-flow/plugin-gastown-bridge — A Ruflo plugin that lets agents drive the Gas Town orchestrator (beads, convoys, formulas) through validated MCP tools that call the gt and bd CLIs.

Supported environments: Node.js 20+ · ESM and CommonJS · the gt/bd CLIs for live calls

Quickstart

npm install @claude-flow/plugin-gastown-bridge

import { GasTownBridgePlugin, validateBeadId } from '@claude-flow/plugin-gastown-bridge';

const plugin = new GasTownBridgePlugin();
console.log('tools:', plugin.getMCPTools().length);
console.log('bead id:', validateBeadId('gt-abc12'));
try {
  validateBeadId('gt-abc; echo injected');
} catch (err) {
  console.log('rejected:', err.code);
}

Expected output:

tools: 20
bead id: gt-abc12
rejected: GT_INVALID_BEAD_ID

Install it into a Ruflo project with @claude-flow/cli: npx @claude-flow/cli@latest plugins install -n @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?

Features

🚀 WASM-Accelerated Computation

🔗 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

Performance Comparison

Architecture Comparison

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

# Check Gas Town CLI
gt --version

# Check Beads CLI
bd --version

# Both should output version numbers

// 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,
    }),
  ],
});

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

const ready = await claudeFlow.mcp.call('gt_beads_ready', {
  limit: 5,
});

console.log('Ready beads:', ready.beads.map(b => b.title));

// 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' },
  },
});

// 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"

// 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}`);

// 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}`);

// 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

// 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"

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)`);
});

// 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}`);

// 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),
});

// 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

• Gas Town GitHub
• Beads GitHub
• Welcome to Gas Town (Steve Yegge)
• ADR-043: Gas Town Bridge Plugin
• ADR-042: Gas Town Analysis

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT License - see LICENSE for details.

Built with ❤️ by the Claude Flow Team

Built by rUv · ruv.io · Source