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

How it differs from ruflo/claude-flow

odd-flow is extracted from the ruflo 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
• 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.

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