claude-flow

Flow-Agent

Flow-Agent is a personal successor to the Claude-Flow orchestration platform. It keeps the formidable multi-agent foundation built by the Claude-Flow team and evolves it into a provider-neutral toolkit that emphasises predictable operations, testability, and enterprise deployment story. Day-to-day workflows remain compatible with the existing CLI and MCP integrations while branding, documentation, and roadmap now reflect the Flow-Agent identity.

Flow-Agent would not exist without the pioneering work of the Claude-Flow project. This repository retains their implementation history and pays explicit acknowledgement to the original maintainers for designing the architecture we continue to iterate on.

What’s Included

• Swarm and Hive-Mind coordination – orchestrate specialised agents, share memory, and resume long running workstreams.
• Multi-provider LLM runtime – Anthropic Claude, OpenAI GPT and Codex, Google Gemini, Cohere, and Ollama adapters with stream support, cost tracking, and thread persistence.
• Extensible tool surface – 80+ MCP tools, hook system for automation, and PreToolUse modifiers for command safety and routing.
• Workspace intelligence – permission-aware spawning, trust validation, and consistent sandbox options for local or cloud execution.
• Parity remediation tracking – Codex parity rebuild plan, smoke tests, and documentation status to make gaps explicit while we close them.

Project Status

• Repository lineage: forked from Claude-Flow v2.5.0-alpha.140.
• CLI packages: published as flow-agent (legacy claude-flow entry points remain for backwards compatibility).
• Documentation: most guides have been refreshed for the Flow-Agent voice; historical parity claims now link to docs/CODEX_PARITY_REBUILD.md for their current status.

Getting Started

Prerequisites

• Node.js 22 or newer (22+ recommended)
• pnpm, npm, or yarn
• For Claude-based workflows, install @anthropic-ai/claude-code

Install & Initialise

# Install from the published alpha channel
npx flow-agent@alpha init --force

# Inspect available commands
npx flow-agent@alpha --help

# Launch a quick swarm coordination session
npx flow-agent@alpha swarm "Draft release notes for Flow-Agent"

# Start a persistent hive-mind workspace
npx flow-agent@alpha hive-mind spawn "Implement Codex parity smoke tests" --claude

Legacy scripts installed as claude-flow continue to work, forwarding to the Flow-Agent toolchain.

Core Concepts

Area	Description
Swarm	Fire-and-forget multi-agent runs for focused objectives.
Hive-Mind	Stateful, resumable orchestration with memory persistence.
Providers	Plug-in layer for LLM backends; Codex support now includes streaming, tooling flags, and smoke-testing hooks.
Hooks & MCP tools	Automation primitives for build, deployment, and knowledge workflows.
Memory	SQLite-backed store for task, conversation, and artefact history.

Feature Highlights

• Plan & Apply Tooling – out-of-the-box plan actions, apply-patch helpers, and sandbox propagation across threads.
• Automation Executors – run structured workflows (automation run-workflow, automation mle-star) with provider-aware spawning.
• Parity Monitoring – docs/CODEX_PARITY_REBUILD.md tracks the Codex remediation backlog; smoke tests (CODEX_SMOKE_TEST=1 pnpm test:codex:smoke) exercise real binaries behind a feature flag.
• Documentation Set – architecture briefs, quick references, and coordination guides have been updated to refer to Flow-Agent while citing Claude-Flow as the originating design.

Development Workflow

npm install
npm build
npm lint
npm test

Targeted tests:

# Unit and integration tests covering the Codex provider
npm test -- src/__tests__/unit/codex-event-translation-unit.test.ts src/__tests__/integration/codex-provider-integration.test.js

# Optional smoke test (requires CODEX CLI on PATH)
CODEX_SMOKE_TEST=1 npm test:codex:smoke

Roadmap

1. Publish the Flow-Agent CLI package and binary wrappers.
2. Finish Codex parity rebuild and document validated provider coverage.
3. Expand MCP tooling catalogue with cross-provider telemetry.
4. Stabilise automation templates for CI/CD pipelines.

Roadmap items are tracked in docs/CODEX_PARITY_REBUILD.md, docs/CODEX_PARITY_UPDATE.md, and project issues as they migrate to the Flow-Agent namespace.

Contributing

We welcome contributions that improve robustness, parity, and documentation clarity. When opening a pull request:

1. Follow the established coding standards (TypeScript, two-space indentation, explicit exports).
2. Run npm lint, npm typecheck, and the relevant Jest suites.
3. Update parity trackers or docs when behaviour changes.

Attribution