odd-flow

Agent orchestration for Claude Code. Swarms, memory, hooks, and MCP tools — hardened and minimal.

What is odd-flow?

odd-flow is a focused agent coordination package for Claude Code. It provides:

• Swarm orchestration — spawn and coordinate multiple AI agents in hierarchical or mesh topologies
• Persistent vector memory — HNSW-indexed semantic search with sql.js backend (4-9ms queries)
• Self-learning hooks — pattern recognition and Q-learning routing that improves over time
• MCP server — 100+ tools exposed via Model Context Protocol (stdio transport)
• Session management — save, restore, and resume agent sessions
• Hive mind consensus — Byzantine fault-tolerant coordination across agents
• Security scanning — built-in AIDefence integration for prompt injection detection
• Embeddings — ONNX-powered 384-dim vector embeddings with hyperbolic geometry support
• Watchdog — three-tier agent liveness monitoring (Witness → Deacon → Dogs) with automatic termination and orphan task recovery
• Session recovery — periodic checkpointing of full swarm state for crash recovery
• Merge queue — conflict detection when multiple agents modify overlapping files or contracts
• Escalation routing — automatic severity classification (P0 halt / P1 pause / P2 log) with regex-based pattern matching
• Capacity governance — dynamic agent scaling based on workload, idle detection, and configurable limits

How it differs from odd-flow/odd-flow

odd-flow is extracted from the odd-flow v3 codebase with a security-first approach:

Quick start

As an MCP server for Claude Code

claude mcp add odd-flow -- npx -y odd-flow

This registers odd-flow as an MCP tool provider. Claude Code will then have access to all orchestration tools (swarm, memory, agents, hooks, etc.).

As a CLI

npx odd-flow init
npx odd-flow swarm init --topology hierarchical
npx odd-flow agent spawn -t coder --name my-agent
npx odd-flow memory store --key "pattern" --value "auth uses JWT refresh tokens"
npx odd-flow memory search --query "authentication"

Global install

npm install -g odd-flow
odd-flow doctor --fix

Core commands

MCP tools

When running as an MCP server, odd-flow exposes tools in these categories:

• agent_* — spawn, list, terminate, health-check agents
• swarm_* — init, status, shutdown swarms
• memory_* — store, search, retrieve, list, delete, stats
• task_* — create, update, complete, cancel, list tasks
• session_* — save, restore, list, delete sessions
• hooks_* — lifecycle hooks, intelligence, workers, routing
• hive-mind_* — init, join, broadcast, consensus
• workflow_* — create, execute, pause, resume workflows
• embeddings_* — generate, search, compare embeddings
• config_* — get, set, list, reset configuration
• claims_* — claim, release, steal, rebalance work items
• analyze_* — diff stats, risk assessment, reviewer suggestions
• progress_* — check, sync, watch, summary
• refinery_* — submit changesets, check merge queue status, resolve conflicts
• escalation_* — report problems, check escalation status, resolve/reclassify events
• scheduler_* — check capacity status and scaling reports
• security_* — scan for prompt injection and manipulation
• system_* — health, status, metrics, info

Memory system

odd-flow uses HNSW (Hierarchical Navigable Small World) indexing for fast semantic search over stored memories:

# Store a memory with tags
odd-flow memory store --key "auth-pattern" --value "JWT with refresh token rotation" --namespace patterns --tags "auth,jwt"

# Semantic search (returns ranked results)
odd-flow memory search --query "how does authentication work" --namespace patterns --limit 5

# List all memories in a namespace
odd-flow memory list --namespace patterns

The memory backend uses sql.js (SQLite compiled to WASM) with 384-dimensional embeddings. Query latency is typically 4-9ms.

Swarm orchestration

Swarms coordinate multiple agents working on a shared task:

# Initialise a hierarchical swarm (queen + workers)
odd-flow swarm init --topology hierarchical --max-agents 8 --strategy specialized

# Check swarm status
odd-flow swarm status

# Shutdown
odd-flow swarm shutdown

Supported topologies:

• hierarchical — queen coordinator delegates to specialised workers
• mesh — peer-to-peer, every agent communicates directly
• ring — sequential message passing
• star — central hub with spokes

Self-learning hooks

Hooks observe agent behaviour and learn patterns over time:

# View learned patterns
odd-flow hooks intelligence stats

# Search for patterns
odd-flow hooks intelligence pattern-search --query "error handling"

# View routing decisions
odd-flow hooks model-stats

The hook system uses Q-learning to optimise model routing (which model handles which task type) based on observed outcomes.

Gastown orchestration (v1.2.0)

Gastown adds five coordination layers that run automatically when a swarm is initialised. They keep multi-agent builds stable without manual intervention.

Watchdog (D1)

Three-tier liveness monitoring — Witness, Deacon, Dogs — that detects unresponsive agents and recovers their work.

• Witness checks heartbeats every 15 seconds. If an agent misses the threshold, it emits agent:unresponsive.
• Deacon tracks consecutive misses per agent: 1 → warning, 2 → wake attempt, 3+ → terminate.
• Dogs handles termination: marks the agent as terminated, creates recovery tasks for any in-progress work, and logs the event.

# Agents send heartbeats while working (MCP tool)
odd-flow agent heartbeat --agent-id my-agent

# Check watchdog state via swarm status
odd-flow swarm status

Watchdog behaviour is configurable:

odd-flow config set --key "watchdog.enabled" --value true
odd-flow config set --key "watchdog.checkInterval" --value 15000
odd-flow config set --key "watchdog.heartbeatThreshold" --value 60000
odd-flow config set --key "watchdog.maxMissedBeats" --value 3

Session recovery (D2)

The CheckpointManager periodically snapshots full swarm state (agents, tasks, config) to .odd-flow/recovery/checkpoint-latest.json. After a crash or session drop, the recovery plan identifies which agents to respawn and which tasks to restart.

odd-flow config set --key "recovery.checkpointInterval" --value 60000
odd-flow config set --key "recovery.staleThreshold" --value 86400000

Merge queue (D3)

The Refinery queues concurrent agent output and detects conflicts before merging:

• File overlap — two agents modifying the same file path
• Contract mismatch — two agents defining the same contract with divergent fields

# Submit agent work (MCP tool)
odd-flow refinery submit --agent-id dev-1 --files '[{"path":"src/api.ts","content":"..."}]'

# Check queue status
odd-flow refinery status

# Resolve a conflict
odd-flow refinery resolve --conflict-id cf-123 --resolution A

Escalation routing (D4)

The EscalationRouter classifies problems by severity using regex pattern matching:

# Report a problem (auto-classified or explicit severity)
odd-flow escalation report --source qa-agent --description "SQL injection in user handler"

# Check open escalations
odd-flow escalation status --severity p0

# Resolve or reclassify
odd-flow escalation resolve --event-id evt-123
odd-flow escalation resolve --event-id evt-456 --reclassify-to p2

Cross-service wiring runs automatically:

• Watchdog terminations → P1 escalation
• Refinery contract conflicts → P0 escalation

Capacity governance (D5)

The Scheduler dynamically scales agents up or down based on workload:

• Scale up when all agents are busy, ready tasks are waiting, and the pool is under maxAgents
• Scale down when an agent has been idle beyond the idleThreshold with no matching work
• Blocked detection when no tasks are ready or in-progress (possible deadlock)

# Check scheduler status
odd-flow scheduler status

# Include capacity report
odd-flow scheduler status --include-report

# Configure
odd-flow config set --key "scheduler.checkInterval" --value 30000
odd-flow config set --key "scheduler.idleThreshold" --value 2
odd-flow config set --key "scheduler.rampUp" --value true

Configuration

# View current config
odd-flow config list

# Set a value
odd-flow config set --key "swarm.maxAgents" --value 12

# Reset to defaults
odd-flow config reset

Configuration is stored in .odd-flow/config.json in the project root with 0o600 file permissions.

Security model

odd-flow was hardened from the odd-flow v3 codebase with these measures:

• Path containment — all file operations validated against project root via validatePath()
• No arbitrary execution — terminal_execute tool removed entirely
• No auto-install — removed silent package installation capability
• File permissions — all state files written with mode: 0o600 (owner read/write only)
• Prototype pollution prevention — filterDangerousKeys() strips __proto__, constructor, prototype from all inputs recursively
• Input sanitisation — CLI flag values sanitised before use in shell commands
• execFileSync over exec — array-based argument passing, no shell interpolation

Requirements

• Node.js >= 18
• Claude Code (for MCP integration)

License

MIT