🌐 clawsomeflow.com · 📖 Docs
English · 简体中文
A harness for long-running, multi-party work — humans, machines, and any agent platform in one controllable flow.
Production work is never “AI-only”. Someone has to touch the physical world, approve an irreversible action, or make a judgment call. Teams also span machines and tools — not a single laptop or a single chat. ClawsomeFlow treats people, remote ClawsomeFlow instances, custom webhooks, and CLI agents as first-class executors in the same DAG: reusable, observable, checkpointable, and cost-aware.
Works with OpenClaw, Hermes, Claude Code, Codex, Cursor and other CLI agents — and with any system you already run via a simple webhook contract.
Quick Start · Docs · News · Who Should Try It · Core Features · External Nodes · How It Works · Why ClawsomeFlow · Contributor Local Deploy · Roadmap · Community
📰 News
- 2026-06-02: ClawsomeFlow public release 🎉
🎯 Who Should Try It?
- Operators building AI-native businesses where work crosses people, tools, and machines — not just a coding sandbox;
- Teams that need human checkpoints, irreversible approvals, or real-world steps inside an otherwise automated flow;
- Builders who want OpenClaw / Hermes / Claude / Codex / Cursor (and custom agent stacks) collaborating in one graph;
- Anyone tired of one long chat context for complex, multi-week work — and who wants reusable, auditable, cost-controlled runs.
✨ Core Features
ClawsomeFlow is a harness: it keeps long-cycle, multi-executor work stable — so capability scales without the process collapsing into an unreviewable chat transcript.
| 🤝 Human + machine + any agent platform | 🔗 Cross-machine collaboration | 🧩 Bring your own executor |
|---|---|---|
| People, local agents, remote ClawsomeFlow, and custom systems sit in the same DAG with the same dependency and completion semantics. | Delegate a subtask to another machine’s Flow; stitch results back as upstream context. | A minimal webhook contract — or a custom agent platform you build yourself — plugs in without rewriting the scheduler. |
| ♻️ Reusable & reliably repeatable | 🎛️ Controllable process | 💸 Cost-aware by design |
|---|---|---|
| Define a Flow once; re-run with parameters. Same structure, stable output — not a one-off prompt. | Human checkpoints, selective re-run of subtasks, complaint/improve loops. You steer; the harness remembers. | Split work across nodes so each executor sees a short, relevant context — far cheaper than one mega-agent carrying the whole project. |
| ⏪ Rollback & repo safety | 👁 Observable end-to-end | 🌱 Self-improving runs |
|---|---|---|
| Worktree isolation plus a built-in cross-process repo lock so parallel edits don’t corrupt the baseline; merges and results stay reviewable and revertible. | Every dispatch, hand-off, and failure is a RunEvent — live board, edge inbox messages, full replay. | Not happy? Complain; the system reworks and records the lesson for the next run. |
| ⏳ Built for long cycles | 🏢 Beyond coding |
|---|---|
| Flows can span hours to weeks: human wait times, remote jobs, and multi-specialty hand-offs without losing the thread. | Market, ops, content, support, engineering — any specialty that can report a result can be a node. |
🛠️ How It Works
From a sentence to a shipped result. You stay in charge of the goal; ClawsomeFlow handles the coordination, the parallelism, and the recovery when things go wrong.
- Describe your goal — Compose a Flow as a graph: local agents, humans, webhooks, and remote ClawsomeFlow nodes as needed.
- Executors run their part — The harness dispatches ready nodes (parallel where possible), isolates agent workspaces, and waits on people or remote systems without losing the thread.
- Watch, steer, recover — Live board (including inbox hand-offs on dependency edges), checkpoints, selective re-run, retry/skip/abort.
- Converge & deliver — A leader summarizes into one reviewed result; history stays auditable and improvable.
🧪 Developer Mode
Developer mode offers software-development collaboration projects a more flexible way to collaborate.
- Upstream context for every subtask: for each direct dependency, a subtask is injected with the upstream agent id, worktree path, branch and base branch, so it can flexibly build on that work — inspect it, merge that branch, or raise a PR for it — driven entirely by your task description.
- Cross-branch collaboration in plain language: in a downstream task, just write "merge upstream agent X's worktree branch into branch Y" or "open a PR for X".
- Built-in lock = absolute parallel-merge reliability: many branches can develop and merge in parallel without ever racing or corrupting the repo. Whether the scheduler or an agent merges, every merge is serialized on the same lock — you can even direct cross-branch merges or PRs in plain language without risk.
- Per-subtask auto-merge control: each subtask can independently toggle auto-merge into the baseline branch.
- Unique worktree per agent: each agent creates its own worktree and independent branch from the baseline branch.
- PR-friendly flow: for subtasks you want to land via PR or manual review, turn auto-merge OFF.
🤖 Supported Agents
| Agent | Kind | Runtime | Status |
|---|---|---|---|
| OpenClaw | openclaw |
TUI | ⭐ Deeply adapted |
| Hermes | hermes |
TUI | ⭐ Deeply adapted |
| Claude Code | claude |
TUI | ✅ Full support |
| Codex | codex |
TUI | ✅ Full support |
| Cursor | cursor |
TUI | ✅ Full support |
| OpenCode | opencode |
TUI | Testing |
| Gemini CLI | gemini |
TUI | Testing |
| Kimi CLI | kimi |
TUI | Testing |
| Qwen Code | qwen |
TUI | Testing |
| Qoder CLI | qoder |
TUI | Testing |
| CodeBuddy Code | codebuddy |
TUI | Testing |
| Pi | pi |
TUI | Testing |
| nanobot | nanobot |
TUI | Testing |
| External executor | external |
Human / Webhook / Remote ClawsomeFlow | ✅ Full support |
🌐 External Execution Nodes
Real work always leaves the “AI-only” box: a person must inspect hardware, approve a payment, or decide under ambiguity; another system must run a black-box step; another machine already hosts the right Flow. External nodes put those executors in the same DAG as your agents — same dependencies, same hand-off of completion summaries.
In the Flow editor: Owner source → External execution, then pick an owner kind:
| Owner kind | Who runs it | How the result returns |
|---|---|---|
| Human | A person on the Run page | Submit on the todo card |
| Remote ClawsomeFlow | A Flow on another machine | Peer finishes → result comes back |
| Generic interface (webhook) | Your HTTP service | Receive task package → callback when done |
Remote ClawsomeFlow (copy-paste wiring — no hand-typed CLI)
- Peer: open the target Flow's editor and click Copy remote call info next to the title — you get a JSON blob (Flow ID, param fields, pairing credential). Send it to the origin.
- Origin: in the subtask pick Remote ClawsomeFlow, paste the blob into Remote Flow call info, fill in the remote base URL yourself (a host:port the origin service process can reach directly, e.g.
http://192.168.1.10:17017— not an SSH-tunnel forwarded127.0.0.1port), then save the subtask — Flow ID / credential are registered automatically; the secret is stored locally, never in the Flow spec.
Nothing extra to configure across machines — both ends are plain, fully symmetric ClawsomeFlow services (no hub). Security model: remotes can reach only the /api/external collaboration surface (one-time ticket / pairing-credential auth); the WebUI and every other API accept loopback connections only, enforced by source IP — administer remotely over an SSH tunnel (ssh -L 17017:127.0.0.1:17017). Full loopback lockdown: csflow external expose off.
Params flow automatically (only when the remote Flow declares param fields): upstream tasks are then asked to report values for them; you may also type known values on the node (they override upstream). Unfilled fields take the union of upstream reports; anything still empty is sent as 参数为空. If the remote Flow has no param fields, no special handling is applied.
Generic interface (webhook)
On ClawsomeFlow: pick Generic interface (webhook) and set your endpoint URL. If the partner must reach you from another host, set the callback base URL (/api/external is already open by default):
csflow external callback-url http://<origin-host>:17017
On your system: accept the task POST, then when done:
POST {callbackUrl}
Authorization: Bearer {callbackToken}
{"status": "success", "summary": "what you delivered"}
Two JSON messages — that’s the whole integration.
🤔 Why ClawsomeFlow?
The hard part of agentic work is rarely “the model isn’t smart enough”. It’s that collaboration has no harness: process lives in a prompt, context balloons, humans and other machines can’t join cleanly, and long projects become unreviewable.
ClawsomeFlow’s bet is simple: put coordination in a durable harness — open executors (human / remote / webhook / any agent CLI), short per-node context, checkpoints, locks, observability, and reuse — so capability can grow without the process falling apart.
| Typical “one agent + one chat” | ClawsomeFlow | |
|---|---|---|
| Who can execute | Mostly the model in front of you | Humans, remote instances, webhooks, many agent platforms |
| Long projects | Context rot; hard to pause / resume safely | Flows built for long cycles + human wait + re-run |
| Cost | One context carries everything | Split nodes → shorter contexts, lower token spend |
| Control | Hope the prompt holds | Checkpoints, selective re-run, complaint loop, rollback |
| Concurrency | Easy to step on the same repo | Worktree isolation + built-in repo lock |
| Scope | Coding demos | Cross-specialty, end-to-end operational flows |
You own the goal. ClawsomeFlow keeps the multi-party execution under control.
🚀 Quick Start
Before you start — make sure your agent CLIs work. ClawsomeFlow drives external agent CLIs (
claude,codex,hermes, …) and agents inherit your global CLI authentication. So first install and log in to each CLI you plan to use and confirm it runs on its own (e.g.claude -p hi,hermeschat,codex). If a CLI isn't authenticated, agents using it will stall on a login prompt. For Hermes you can also set the model/provider/key per agent in Settings → Model. If you hit auth errors, verify the CLI's own model/provider config first.Qoder / CodeBuddy need a one-time auth: CodeBuddy via
codebuddy→ interactive login; Qoder viaexport QODER_PERSONAL_ACCESS_TOKEN=…(orqodercli→/login). ClawsomeFlow auto-seeds their folder-trust config (trustAll/trustDirectories) so unattended runs don't stall on the "trust this folder?" prompt — no action needed there.
Install
Linux/macOS
curl -fsSL https://clawsomeflow.com/install.sh | bash
Common Commands
Most of the time you only need these three:
csflow start # start the service, print the console URL
csflow status # is it running? version, mode, paths
csflow upgrade # update to the latest release (flows/runs/settings preserved)
A few more for day-to-day use:
# Lifecycle
csflow stop
csflow doctor # health check (deps + config + gateway)
csflow uninstall --yes # stop service + unregister OpenClaw (keep data)
csflow uninstall --purge-data # full wipe: type PURGE to confirm (irreversible)
# Flow / Run
csflow flows list
csflow runs start <flow-id> --input k=v # trigger a run with parameter fields
csflow runs list
csflow runs abort <run-id>
# Agent governance
csflow agents list
# Creating agents and chatting with them is done in the Web UI ("My Team"),
# not the CLI.
# MCP: let an agent drive Flows remotely (via its own channels, e.g. Telegram)
csflow mcp install --platform hermes --agent <id> # per-agent (Hermes; omit --agent for the default profile)
csflow mcp install --platform codex # global (codex/claude/cursor/gemini/opencode)
csflow mcp print-config --platform openclaw # snippet to paste for unsupported platforms
Every command accepts --help. Full CLI reference: https://clawsomeflow.com/docs/
🔌 MCP: drive Flows from an agent
Run ClawsomeFlow as an MCP server. Point one of your agents at it and — through that agent's own channels (Feishu, Telegram, …) — you can, in plain language, ask which Flows exist, run one, and get the leader's final work report back. A typical loop: you send a file + a request over Telegram → the agent picks the right Flow and runs it → reads the leader report → replies over Telegram.
Talking to your agent (examples)
- "What ClawsomeFlow flows can I run?"
- "Run the XXXX task."
- "Show me the run result."
- "Cancel the XXX run."
The agent organizes the inputs itself from your request, so you rarely name fields explicitly — describe the task and let it map your words onto the Flow's parameters.
Register it with your agent
csflow mcp install --platform hermes # Hermes: default profile
csflow mcp install --platform hermes --agent <id> # Hermes: a specific agent profile
csflow mcp install --platform codex # global platforms (see table)
csflow mcp uninstall --platform codex # remove it again
| Platform | Scope | Config written |
|---|---|---|
hermes |
per-agent (--agent <id>; omit → default profile) |
~/.hermes/…/config.yaml mcp_servers |
claude |
global | ~/.claude.json mcpServers |
cursor |
global | ~/.cursor/mcp.json mcpServers |
gemini |
global | ~/.gemini/settings.json mcpServers |
codex |
global | ~/.codex/config.toml [mcp_servers.*] |
opencode |
global | ~/.config/opencode/opencode.json mcp |
openclaw, kimi, qwen, nanobot |
manual | print-config only (paste into the platform's own MCP config) |
Writes are non-destructive (existing servers and other keys are preserved) and idempotent. install skips a platform whose CLI isn't on PATH unless you pass --force.
Manual configuration
For any platform, print a ready-to-paste snippet instead of writing files:
csflow mcp print-config --platform claude # JSON: { "mcpServers": { "clawsomeflow": … } }
csflow mcp print-config --platform codex # TOML: [mcp_servers.clawsomeflow]
csflow mcp print-config --platform hermes # YAML: mcp_servers: …
The server entry is always the same command — register it manually if your platform isn't listed:
{
"mcpServers": {
"clawsomeflow": { "command": "csflow", "args": ["mcp", "serve"] }
}
}
Note: the ClawsomeFlow service must be running (csflow start) to use MCP.
👩💻 Contributor Local Deploy and Test
For contributors iterating on source code, use the isolated developer entrypoint:
bash scripts/deploy-contributor.sh
Default behavior of deploy-contributor.sh:
- Uses isolated data/runtime under
~/.clawsomeflow-dev(does not reuse~/.clawsomeflow). - Starts backend on
17117and Vite on5174. - Keeps ClawTeam runtime isolated via
~/.clawsomeflow-dev/.clawteam-data.
bash scripts/deploy-contributor.sh is recommended for day-to-day source testing because it keeps regular user service state isolated.
Example with custom profile/ports:
CSFLOW_DEV_HOME=~/.clawsomeflow-dev-alice \
CSFLOW_DEV_BACKEND_PORT=18117 \
CSFLOW_DEV_FRONTEND_PORT=5184 \
bash scripts/deploy-contributor.sh
Running the test suite
Run all tests inside Docker — a separate filesystem and network namespace mean a
test can never touch your real ~/.clawsomeflow / ~/.openclaw or a running
gateway:
scripts/test-in-docker.sh # full backend suite
scripts/test-in-docker.sh -q backend/tests/test_api_guard.py # subset (args → pytest)
Requires Docker and a local ClawTeam checkout (a sibling ../ClawTeam, or set
CLAWTEAM_SRC=/path/to/ClawTeam). Do not run pytest directly on a host
that has a csflow/openclaw service running — it would reach the real gateway on
:18789.
Stop the contributor service
To stop the contributor profile started by deploy-contributor.sh, use the
dedicated stop script:
bash scripts/stop-contributor.sh
Do not use csflow stop for the contributor profile — that targets
the end-user service. If you used a custom profile, pass the same env overrides:
CSFLOW_DEV_BACKEND_PORT=18117 CSFLOW_DEV_FRONTEND_PORT=5184 \
bash scripts/stop-contributor.sh
🗺️ Roadmap
| Phase | Content | Status |
|---|---|---|
| P0 | Agent Store — a shareable marketplace for ready-made Agents, Teams and Flow templates: install, reuse, and contribute domain experts in one click. | 🚧 In progress |
| P1 | Broader Agent platform support — onboard more CLI Agent runtimes and keep pace with emerging ecosystems, so any Agent can join the same graph. | 🚧 In progress |
| P2 | Mobile console — a mobile-friendly console to monitor and intervene in Runs anywhere. | 💡 Exploring |
| P3 | Cloud & SSH Agents — drive Agents on remote / cloud hosts over SSH, scaling collaboration beyond a single machine. | 💡 Exploring |
🙏 Acknowledgements
- [ClawTeam] — the spark that inspired this project. Thank you for showing what Agent self-organization can be.
- Our Agent platform teammates — the real "team members" that do the actual work inside every Flow: Claude, OpenClaw, Codex, Gemini, and the growing roster of CLI Agents. ClawsomeFlow is only as clawsome as the Agents it coordinates.
💬 Community
If ClawsomeFlow helps you coordinate your Agent team, please give us a ⭐ Star — it genuinely keeps us going.
Got questions about using ClawsomeFlow, or curious about building an OPC (One-Person Company)? Come hang out with us — join our Discord server or scan the QR code below to join our WeChat discussion group:
📄 License
MIT
1 maintainer
Metadata
1 maintainer
Release files for clawsomeflow 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| clawsomeflow-0.2.0.tar.gz | 1.4 MB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| clawsomeflow-0.2.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.5 MB
Release files / clawsomeflow-0.2.0.tar.gz
| Download URL | clawsomeflow-0.2.0.tar.gz |
|---|---|
| Size | 1.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c87840f1f08e6104be1a9f97e6d9d218e74ad18a7e4d81f9af2686d2504ae272
|
|
BLAKE2b-256 checksum How to use checksums |
3e998044b19e24b83864d58034a6e4c4a1739e3b93aa84dfd53755ba10f56642
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.0rc1
|
Release files / clawsomeflow-0.2.0-py3-none-any.whl
| Download URL | clawsomeflow-0.2.0-py3-none-any.whl |
|---|---|
| Size | 1.1 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
be2ca2bb4ce41cac5b5502b973ab1ee1d1804fff41e0da4d334ae8668faeb7c0
|
|
BLAKE2b-256 checksum How to use checksums |
97006f90a8082933f48aed10a87d63943a9a4b56ea286e2e45020753941f5f04
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.0rc1
|
Security for clawsomeflow 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
