DEV Community

Cover image for Rufler: One YAML File to Rule Your Autonomous AI Swarm
Ivan Filippov
Ivan Filippov

Posted on

Rufler: One YAML File to Rule Your Autonomous AI Swarm

#actionshackathon #claude #ai #webdev

The Problem: Too Many Commands, Not Enough Orchestration

If you've worked with ruflo (the TypeScript AI agent orchestration CLI from the claude-flow family), you know it's powerful. It gives you swarm topologies, hive-mind coordination, shared memory, autopilot loops, and the ability to spawn Claude Code as an autonomous agent.

But actually using it on a project looks something like this:

ruflo init --force
ruflo daemon start
ruflo memory init --backend=hybrid
ruflo swarm init --topology=hierarchical --max-agents=8 --strategy=specialized
ruflo hive-mind init --topology=hierarchical --consensus=raft --max-agents=8
ruflo autopilot config --max-iterations=100 --timeout=180
ruflo autopilot enable
ruflo hive-mind spawn --count=4 --role=specialist --claude \
  --non-interactive --dangerously-skip-permissions=true \
  --objective="$(cat my_assembled_prompt.txt)"
Enter fullscreen mode Exit fullscreen mode

That's 8 commands just to get started. And the objective prompt? You have to assemble it by hand -- project context, task description, every agent's role and prompt, autonomy instructions, memory checkpointing rules.

Do this across multiple projects, add multi-task workflows, background runs, log management, and graceful teardown -- and you're writing a lot of shell scripts.

Enter Rufler

Rufler is a Python wrapper that replaces all of the above with:

rufler run
Enter fullscreen mode Exit fullscreen mode

One command. One YAML file. The entire ruflo pipeline runs automatically.

Here's what a rufler_flow.yml looks like:

project:
  name: my-api
  description: Go microservice with REST API and PostgreSQL.

task:
  main: |
    Build a Go HTTP server on :8080 with CRUD endpoints,
    PostgreSQL storage, and integration tests.
  autonomous: true

agents:
  - name: architect
    type: system-architect
    role: specialist
    seniority: lead
    prompt: Design the API schema and package layout.

  - name: coder
    type: coder
    role: worker
    seniority: senior
    prompt: Implement the server following the architect's design.
    depends_on: [architect]

  - name: reviewer
    type: reviewer
    role: specialist
    seniority: senior
    prompt: Review all code for quality and security.
    depends_on: [coder]
Enter fullscreen mode Exit fullscreen mode

Rufler reads this, composes a structured objective prompt (agents sorted by seniority, with GATE/HANDOFF blocks for depends_on), and runs the full ruflo pipeline.

What Rufler Adds Over Raw Ruflo

Raw ruflo With rufler
8+ shell commands to boot rufler run (one command)
Assemble objective prompts by hand Auto-composed from YAML
No multi-task support Sequential or parallel task groups
No task decomposition AI-powered decomposition (task.decompose: true)
Mixed ANSI/JSON/text logs Clean NDJSON -- every line is parseable JSON
No way to see live progress rufler follow -- 4-panel TUI dashboard
No run history Docker-style registry: rufler ps, rufler tasks, rufler tokens
No resume after interruption Automatic resume from last completed task
Manual MCP server setup Declare MCP servers in YAML

In short: ruflo is the engine; rufler is the ignition, dashboard, and cruise control.

Features Worth Highlighting

Docker-Style Run Lifecycle

Every rufler run gets an 8-char hex id. You can list runs with rufler ps, inspect tasks with rufler tasks, check tokens with rufler tokens, and stop gracefully with rufler stop. Works from any directory.

rufler run -d          # detach (like docker run -d)
rufler ps              # list running
rufler follow a1b2     # live TUI for run a1b2
rufler stop a1b2       # graceful shutdown
Enter fullscreen mode Exit fullscreen mode

Task Tracking and Resume

Each task gets a sub-id (a1b2c3d4.01) with a tracked lifecycle: queued -> running -> exited / failed / stopped. Token usage is counted per task.

When you stop a run mid-way and restart, rufler automatically resumes from the first incomplete task:

rufler run -d        # tasks 1-2 complete, stopped on task 3
rufler stop
rufler run -d        # resumes from task 3
# => "resuming: skipping 2 completed tasks, starting from task_3"
Enter fullscreen mode Exit fullscreen mode

AI-decomposed task files are reused too -- no wasted claude calls on re-decomposition. Use --new to force a clean start.

Live TUI Dashboard

rufler follow renders a 4-panel Rich dashboard that tails all per-task logs:

+-----------------------------------------------------------------+
| rufler follow  [running]  claude-opus-4  tokens: 94.6K  00:04:23|
+-----------------------------------------------------------------+
| Tasks  2/4            | Session                                 |
| > task_1     done     | model: claude-opus-4-6                  |
| > task_2     running  | tokens: in=98  out=829                  |
|   task_3     queued   | turns: 14                               |
|   task_4     queued   | last tool: Write                        |
+-----------------------+-----------------------------------------+
| Conversation (task_2)                                           |
| 14:23  think  Planning the API routes...                        |
| 14:24  tool   Write(src/api/routes.go)                          |
| 14:24  result File created successfully                         |
+-----------------------------------------------------------------+
| Log                                                             |
| 14:22  OK    task_end task_1                                    |
| 14:23  INFO  session init (claude-opus-4-6)                     |
+-----------------------------------------------------------------+
Enter fullscreen mode Exit fullscreen mode

You see the AI's thinking, text output, tool calls, and results in real time.

MCP Server Management

Declare MCP servers directly in the YAML -- rufler registers them with Claude Code via claude mcp add:

mcp:
  servers:
    - name: my-db
      command: npx
      args: ["-y", "@anthropic/mcp-postgres"]
      env:
        DATABASE_URL: "postgresql://localhost/mydb"

    - name: sentry
      transport: http
      url: "https://mcp.sentry.dev/mcp"
Enter fullscreen mode Exit fullscreen mode

Supports stdio, HTTP, and SSE transports with env vars and headers.

Agent Dependencies (Soft DAG)

Declare depends_on and rufler injects coordination prompts:

agents:
  - name: architect
    ...
  - name: coder
    depends_on: [architect]  # waits for architect's approval
Enter fullscreen mode Exit fullscreen mode

The coder agent won't start until the architect writes an approval to shared memory. Cycles and self-dependencies are rejected at config load time.

Getting Started 

# Install
git clone https://github.com/lib4u/rufler.git
cd rufler && pip install -e .

# Verify dependencies
rufler check

# Create a sample flow
rufler init

# Edit and run
$EDITOR rufler_flow.yml
rufler run --dry-run    # inspect the plan
rufler run -d           # launch detached
rufler follow           # watch it work
Enter fullscreen mode Exit fullscreen mode

Prerequisites: Python 3.9+, Node.js 20+, Claude Code CLI (claude), and ruflo (resolved automatically via npx).

When to Use Rufler vs Raw Ruflo

Use rufler when:

  • You want a single config file checked into your repo
  • You're running multi-task workflows (sequential or parallel)
  • You need task-level tracking, resume, and token accounting
  • You want a live dashboard instead of raw log tailing
  • You're managing MCP servers across projects

Use ruflo directly when:

  • You need fine-grained control over individual ruflo commands
  • You're building custom orchestration scripts
  • You need features rufler doesn't wrap yet

Rufler doesn't replace ruflo -- it's a layer on top. Every ruflo command still works alongside rufler.

Repository: github.com/lib4u/rufler
Built on: ruflo by @ruvnet + Claude Code CLI by Anthropic
License: MIT

Top comments (0)