Soulflow

SoulFlow — Workflow Framework for OpenClaw

A framework for building custom AI workflows. Each workflow is a series of steps that execute in isolated agent sessions with full tool access. Define your workflow in JSON, invoke it naturally, and let the agents handle the execution.

What you can build:

• Development pipelines (security audits, bug fixes, feature development)
• Content workflows (research → draft → edit → publish)
• Operations automation (deploy → verify → rollback-on-fail)
• Research pipelines (gather → analyze → synthesize → report)
• Any multi-step task that benefits from isolated, focused agent sessions

Ships with 3 example dev workflows to show you how it works. Build your own for anything.

Quick Start

Natural language (easiest): Just tell your agent what you need:

• "Run a security audit on my project at ~/myapp"
• "Fix this bug: users can't login with Google OAuth in ~/webapp"
• "Build a referral system for ~/webapp"

Your agent reads this SKILL.md and invokes SoulFlow automatically.

Command line:

cd ~/.openclaw/workspace/soulflow

# Run a security audit
node soulflow.js run security-audit "Audit the codebase at ~/project for vulnerabilities"

# Fix a bug
node soulflow.js run bug-fix "Login returns 500 when email has uppercase letters in ~/myapp"

# Build a feature
node soulflow.js run feature-dev "Add dark mode toggle to the settings page in ~/myapp"

How It Works

SoulFlow connects to your local OpenClaw gateway via WebSocket and runs each workflow step as an isolated agent session. A dedicated soulflow-worker agent is auto-created with minimal context — no memory bleed from your main agent.

Each step:

1. Gets a fresh session (no context bloat)
2. Receives the task + output from previous steps
3. Has full tool access (read, write, edit, exec, browser)
4. Must complete its work and report results

Auto-notifications (v1.1.0+): When workflows complete, SoulFlow automatically notifies the main agent session with results. No need to manually check status.

Example Workflows (Included)

These are examples to show what's possible. Build your own for any domain.

security-audit

Scan → Prioritize → Fix → Verify Development example: Reads your source files, identifies vulnerabilities by severity, applies fixes, then verifies them.

bug-fix

Triage → Fix → Verify Development example: Investigates the root cause by reading code, applies the fix, then verifies it didn't introduce regressions.

feature-dev

Plan → Implement → Review Development example: Architects the implementation plan, writes the code, then reviews for quality and correctness.

Want content workflows? Research pipelines? Deploy automation? Create your own .workflow.json — see Custom Workflows below.

Commands

node soulflow.js run <workflow> "<task>"    # Run a workflow
node soulflow.js list                       # List available workflows
node soulflow.js runs                       # List past runs
node soulflow.js status [run-id]            # Check run status
node soulflow.js test                       # Test gateway connection

Natural Language (via your agent)

The agent knows how to invoke SoulFlow for you. Just describe what you want:

Security audits:

• "Audit my app for security issues"
• "Check ~/myapp for vulnerabilities"
• "Scan the codebase for security problems"

Bug fixes:

• "Fix this bug: login fails when..."
• "There's a problem with the payment flow"
• "Users are seeing 500 errors when they..."

Features:

• "Build a referral system"
• "Add dark mode to the settings page"
• "Implement OAuth login with Google"

How it works:

1. You tell your agent what you need
2. Your agent reads this SKILL.md
3. Agent invokes node soulflow.js run <workflow> "<task>"
4. SoulFlow runs the workflow and reports back

Pattern matching: The agent matches your message to workflows:

• Security audit → keywords: "audit", "security", "scan", "vulnerabilit"
• Bug fix → keywords: "fix", "bug", "broken", "not working", "error"
• Feature dev → keywords: "build", "add", "implement", "create", "feature"

No workflow matches? Agent will ask which workflow you want or suggest creating a custom one.

Custom Workflows

You can create workflows for ANY task. Define them in JSON and place in the workflows/ directory.

Creating via Chat

Tell your agent:

"Create a SoulFlow workflow for [your use case]"

Examples:

• "Create a workflow for content publishing: research topic → draft article → edit → publish to blog"
• "Create a workflow for deployment: run tests → build → deploy → verify health checks → rollback if failed"
• "Create a workflow for weekly reports: gather metrics → analyze trends → generate summary → send email"

Your agent will:

1. Design the workflow steps
2. Write the .workflow.json file to workflows/
3. Show you how to run it

Manual Creation

Create a .workflow.json file in the workflows/ directory:

{
  "id": "my-workflow",
  "name": "My Custom Workflow",
  "version": 1,
  "description": "What this workflow does",
  "steps": [
    {
      "id": "step1",
      "name": "First Step",
      "input": "Do this thing: {{task}}",
      "expects": "STATUS: done",
      "maxRetries": 1
    },
    {
      "id": "step2",
      "name": "Second Step",
      "input": "Now do this based on step 1:\n\n{{step1_output}}\n\nOriginal task: {{task}}",
      "expects": "STATUS: done",
      "maxRetries": 1
    }
  ]
}

Variables

• {{task}} — The user's original task description
• {{stepid_output}} — Full output from a previous step (e.g. {{scan_output}})
• Any KEY: value lines in step output become variables (e.g. ROOT_CAUSE: ... → {{root_cause}})

Prompt Tips

For best results, write prompts that:

• Explicitly tell the agent to use tools: "Use read to examine the file", "Use edit to apply the fix"
• Say "Do NOT just describe — actually do it"
• End with "When done, end with: STATUS: done"

Architecture

• Zero dependencies — Pure Node.js 22 (native WebSocket)
• Gateway-native — Connects via WebSocket with challenge-response auth
• Session isolation — Each step in a fresh session
• Dedicated worker — Auto-creates soulflow-worker agent with minimal brain files
• JSON state — Run history saved to ~/.openclaw/workspace/.soulflow/runs/
• 10-minute timeout per step (configurable)

Requirements

• OpenClaw 2026.2.x or later
• Node.js 22+ (for native WebSocket)
• Gateway with token auth configured

Security & Permissions

What SoulFlow does to your OpenClaw instance:

1. Reads your gateway config (~/.openclaw/openclaw.json) to obtain the authentication token needed to connect via WebSocket
2. Modifies your gateway config (~/.openclaw/openclaw.json) via config.patch to register the soulflow-worker agent
3. Creates a dedicated worker agent (soulflow-worker) with minimal brain files (SOUL.md only, no memory/history)
4. Copies authProfiles from existing agents — Worker inherits credentials for external services (GitHub, cloud providers, etc.) that your other agents use
5. Grants the worker full tool access (read, write, edit, exec, browser) — this is required for workflows to actually perform tasks
6. Writes run state to ~/.openclaw/workspace/.soulflow/runs/ as JSON files

Why these permissions are needed:

• Config read/write: Required to authenticate with the gateway and register the worker agent (same as openclaw CLI tool)
• Agent creation: Each workflow step runs in an isolated session to prevent context bleed
• authProfiles inheritance: Allows workflows to interact with external services (e.g., git push, cloud API calls) using your existing credentials
• Full tools: Workflows need real capabilities (e.g., security-audit reads files, bug-fix edits code, deploy-pipeline pushes to git)
• Filesystem write: Stores workflow history and allows workflows to create/modify files

Security considerations:

• Worker agent has NO access to your main agent's memory or history
• Worker DOES inherit your external service credentials (authProfiles) — can access GitHub, cloud APIs, etc.
• Workflows run with YOUR permissions (same as running commands yourself)
• Malicious workflows could read/modify files, run commands, or access external services
• Only install SoulFlow if you trust the skill author (review code on GitHub first)
• Only run workflows you trust — custom workflows from untrusted sources could exfiltrate data or misuse credentials
• Run SoulFlow in isolated/sandboxed environments if processing untrusted workflows

Recommended practices:

• Review built-in workflows before first use (especially security-audit and bug-fix)
• Inspect custom .workflow.json files before running
• Review GitHub repo (https://github.com/0xtommythomas-dev/soulflow) before installation
• Run on non-production OpenClaw instances when testing new workflows
• Back up important files before running workflows that modify code
• Use BYOK (bring your own keys) mode if you want isolated credentials per workflow
• Monitor ~/.openclaw/workspace/.soulflow/runs/ for workflow execution logs

For Agents: How to Invoke SoulFlow

When the user requests a workflow (security audit, bug fix, feature build, etc.), you should:

1. Identify the workflow by matching keywords:

   • Security audit: "audit", "security", "scan", "vulnerabilit"
   • Bug fix: "fix", "bug", "broken", "not working", "error"
   • Feature dev: "build", "add", "implement", "create", "feature"
   • Custom: check workflows/*.workflow.json for other options

2. Extract the task description — the user's description of what they want done

3. Invoke SoulFlow using exec:

   cd /root/.openclaw/workspace/soulflow && node soulflow.js run <workflow> "<task>"
   

4. Monitor the run — SoulFlow will output the run ID, then show progress as each step completes

5. Report results — When complete, relay the final status to the user

Example:

User: "Run a security audit on ~/myapp"
You: [exec] cd /root/.openclaw/workspace/soulflow && node soulflow.js run security-audit "Audit ~/myapp for vulnerabilities"

Creating workflows for users: If the user asks you to create a custom workflow:

1. Design the workflow steps based on their requirements
2. Write a .workflow.json file to /root/.openclaw/workspace/soulflow/workflows/
3. Show them how to run it

See CONTRIBUTING.md for workflow design best practices.