{"slug": "show-hn-visually-orchestrate-claude-code-ai-agents", "title": "Show HN: Visually orchestrate Claude Code AI agents", "summary": "RondoFlow launched as an open-source, invite-only tool that lets users visually orchestrate teams of Claude Code agents on a drag-and-drop React Flow canvas, running locally via npm or Docker. The tool spawns Claude Code CLI subprocesses as agents that can read and write files, run commands, and use MCP tools, with a Director, Planner, and Advisor steering each run and a three-layer safety model gating risky actions. RondoFlow also supports mixing Claude Code, OpenAI, and Perplexity agents in one workflow and ships as five Docker containers on ports 5432, 3001, 3000, and 3002.", "body_md": "**Build teams of Claude Code agents - visually.**\n\nDescribe what you need on a drag-and-drop canvas, and RondoFlow assembles a team of specialized AI agents that plan, run, and improve the work together - locally, on your machine, with your files.\n\nMost \"AI workflow\" tools wire prompts together. RondoFlow orchestrates **real\n[Claude Code](https://docs.anthropic.com/en/docs/claude-code) agents** - so the agents on your\ncanvas can actually read and write files, run commands, and use MCP tools and skills, all\ngoverned by safety policies you control. You compose them visually, hit **Run**, and watch the\nteam execute in real time.\n\n**Why it's different**\n\n- 🧩 **Visual multi-agent canvas** - drag agents, skills, safety rules, resources, and MCP\nconnections onto a[React Flow](https://reactflow.dev) board and connect them into a workflow.\n- 🤖 **Real agents that *do* things** - agents are Claude Code CLI subprocesses, not just chat\ncompletions. They edit code, run tools, and stream their work back live.\n- 🎯 **AI that steers the run** - a**Director** evaluates each step mid-run and decides whether\nto continue, retry, or conclude; a**Planner** tunes the team before it starts; an**Advisor** reviews the result afterward.\n- 🔌 **Multi-provider** - mix**Claude Code** (local CLI),**OpenAI** , and**Perplexity** agents\nin the same workflow.\n- 🔒 **Local-first & policy-governed** - runs on your machine, talks to your files, and gates\nrisky actions behind a three-layer safety model. Nothing leaves your box except the model API\ncalls you configure.\n\n```\ngit clone https://github.com/rondoflow/rondoflow.git\ncd rondoflow\nnpm run setup    # installs deps, generates .env, starts Postgres, migrates + seeds\nnpm run dev      # opens at http://localhost:3000\ngit clone https://github.com/rondoflow/rondoflow.git\ncd rondoflow\ncp .env.example .env   # edit .env (see Configuration below)\ndocker compose up      # builds and starts all services\n```\n\nThis starts five containers:\n\n| Container | Port | Role | \n|---|---|---|\n| `rondoflow-postgres` | 5432 | PostgreSQL database | \n| `rondoflow-server` | 3001 | Fastify backend + Socket.IO + Claude Code CLI | \n| `rondoflow-ui` | 3000 | Next.js frontend | \n| `rondoflow-docs` | 3002 | Nextra documentation site (proxied at `/docs` ) | \n| `rondoflow-migrate` | - | Runs database migrations once, then exits | \n\nThen open **[http://localhost:3000](http://localhost:3000)**.\n\nDocker mode needs **Docker Desktop only** - Node.js is not required on the host.\n\nRondoFlow is **invite-only** - open self-registration is disabled, and an admin creates all\naccounts. Set `RONDOFLOW_ADMIN_EMAIL` and `RONDOFLOW_ADMIN_PASSWORD` in `.env` *before* you run\nsetup; the seed step then bootstraps that first admin (it's skipped if either is blank).\n\n- **Option A (local):**`npm run setup` runs the seed for you, so the admin is created automatically.\n- **Option B (Docker):** the`rondoflow-migrate` container runs migrations only - run the seed step\nyourself (`npm run db:seed` , with the admin vars set and Postgres reachable) to create the first admin.\n\nSign in with that account (email/password). On first sign-in a\nshort onboarding wizard walks you through picking a working directory and a work mode (*Quick\nStart* - describe a task and let RondoFlow build the team - or *Full Control* - assemble agents by\nhand). Admins can then create accounts for teammates from the **Users** panel. If the Claude Code\nCLI isn't detected, the app shows install instructions and waits.\n\nDrag nodes onto an interactive board and connect them to define how work flows. Everything auto-saves.\n\n| **Node types** | Assistants (agents), Skills, Safety Rules, Resources, Connections (MCP), Output, Condition (branching), Sticky Notes | \n| **Connections** | Flow edges (execution order), association edges (configuration), and conditional edges (branching from a Condition node) | \n| **Interaction** | Drag-and-drop palette, undo/redo ( `Ctrl+Z` ), keyboard shortcuts (`?` ), command palette (`Ctrl+K` ) | \n| **Workspaces** | Multiple project-based workspaces, each tied to a folder on your machine; export/import to share | \n\nEach Assistant has a provider, model, personality, skills, memory, and MCP connections - all configurable from the side panel.\n\n| Provider | Models | Notes | \n|---|---|---|\n| **Claude Code***(default)* | Opus / Sonnet / Haiku tiers | Runs the local CLI; full tool, MCP, and skill access | \n| **OpenAI** | GPT / o-series | API-based; optional web search | \n| **Perplexity** | Sonar family | API-based; web-grounded research | \n\nThe Workflow Generator picks a sensible model per agent automatically - you can always change it.\n\nThree AI helpers reason *about* your run at different points:\n\n- **Planner***(before)* - reviews the team, models, skills, and order; suggests improvements up front.\n- **Director***(during)* - after each step, decides`continue` /`redirect` (retry with sharper\ninstructions) /`conclude` , with a tunable criticism level and learnings it banks for next time.\n- **Advisor***(after)* - compares the result against the objective and offers one-click fixes.\n\nMultiple Assistants brainstorm, review, or debate a topic while an automated **Facilitator**\nmanages turn order and synthesizes a conclusion.\n\nDescribe a task in plain English and RondoFlow designs a 2–5 agent workflow with personas, models, and skills, laid out as a DAG. Review and edit it before it hits the canvas - or start from a built-in template (Code Review, Content Team, Research, Brainstorm).\n\nSkills are reusable instruction sets that give Assistants specialized abilities. RondoFlow ships built-in skills (Code Review, Writing Assistant, Data Analysis, API Designer, Test Writer) and you can install more from any Git repository.\n\nThree layers of policies - **global**, **per-agent**, and **per-session** - control what agents\nmay do. The most restrictive policy always wins, risky commands require your approval, and budget\nlimits prevent runaway costs. See [SECURITY.md](https://github.com/rondoflow/rondoflow/blob/master/SECURITY.md) for the full model.\n\nRondoFlow runs as a shared team workspace with three global roles: **viewer** (read-only),\n**editor** (create, edit, delete, and run workflows - Director / Planner / Advisor / Discussions\nincluded), and **admin** (everything an editor can do, plus user management and global settings).\nAccounts are **invite-only** - admins create users with a starting role from a **Users** panel and\ncan change roles or deactivate/remove accounts; there is no open self-registration. Roles are\nenforced server-side on both the REST API and the realtime socket layer (viewers get a read-only\ncanvas - palette hidden, nodes locked), and the UI mirrors those capabilities to hide affordances a\nrole can't use. Admin user-management actions are written to the audit log.\n\nRecurring **Schedules** (cron), iterative **Loops** (re-run an agent until a goal is met), an\nin-app **Git** panel (status, branches, commit, push), **Memory** that persists facts across runs,\n**external folder** mounts, and an **audit log** + **analytics** dashboard for monitoring and cost\ntracking.\n\n1. **Describe** what you need in plain English - or pick a template.\n2. **Review** the AI-generated team of agents with their providers, models, and skills.\n3. **Run** the workflow on the canvas - watch agents execute in real time, with the Director\nsteering between steps.\n4. **Improve** with Advisor analysis and one-click suggestions after each run.\n\n``` php\nflowchart TD\n    A[\"Describe your task<br/>in plain English\"] --> B[\"Workflow Generator builds<br/>a 2-5 agent team\"]\n    B --> C[\"Review and edit on the canvas\"]\n    C --> D[\"Planner tunes the team<br/>before the run\"]\n    D --> E[\"Run on the canvas\"]\n    E --> F[\"Agent runs a step\"]\n    F --> G{\"Director evaluates<br/>the output\"}\n    G -->|continue| F\n    G -->|redirect| F\n    G -->|conclude| H[\"Advisor reviews the run\"]\n    H --> I([\"Apply suggestions and<br/>re-run stronger\"])\n```\n\nFull documentation lives at **[docs.rondoflow.app](https://docs.rondoflow.app)**. It's built\nwith [Nextra](https://nextra.site) and the source ships in [`packages/docs`](https://github.com/rondoflow/rondoflow/blob/master/packages/docs) - run\nit locally with:\n\n```\nnpm run dev:docs   # http://localhost:3002/docs\n```\n\n`npm run setup` generates a `.env` automatically. For Docker mode, copy `.env.example` and set:\n\n- **`BETTER_AUTH_SECRET`** - a random string, e.g.` openssl rand -hex 32` .\n- **A Claude credential** (required for Claude Code agents) - either**`ANTHROPIC_API_KEY`** (an\nAnthropic API key)**or****`CLAUDE_CODE_OAUTH_TOKEN`** from` claude setup-token` to use your\nClaude subscription. If both are set, the setup token wins.\n- **Claude Code telemetry** - set**`CLAUDE_CODE_ENABLE_TELEMETRY`** ,**` OTEL_METRICS_EXPORTER`** ,**` OTEL_LOGS_EXPORTER`** ,**` OTEL_EXPORTER_OTLP_PROTOCOL`** , and either the direct OTEL values\n(`OTEL_EXPORTER_OTLP_ENDPOINT` ,`OTEL_EXPORTER_OTLP_HEADERS` ,`OTEL_RESOURCE_ATTRIBUTES` ) or the\nsource vars they derive from (`OTEL_ENDPOINT` ,`AUTH_TOKEN` ,`USER_EMAIL` ). The server forwards\nthese into spawned Claude Code processes.\n- **`RONDOFLOW_ADMIN_EMAIL` / `RONDOFLOW_ADMIN_PASSWORD`** - bootstrap the first admin account.\nRequired to get into a fresh instance, since self-registration is disabled (see[First run](#first-run) ).\n\n| Variable | Required | What it does | \n|---|---|---|\n| `DATABASE_URL` | Auto | PostgreSQL connection string | \n| `BETTER_AUTH_SECRET` | **Yes** | Session encryption - random, never commit | \n| `BETTER_AUTH_URL` | Auto | Backend URL | \n| `RONDOFLOW_ADMIN_EMAIL` | First run | Email for the bootstrap admin, created at seed time (RondoFlow is invite-only) | \n| `RONDOFLOW_ADMIN_PASSWORD` | With email | Password for the bootstrap admin - set alongside the email, then rotate after first login | \n| `RONDOFLOW_ADMIN_NAME` | No | Display name for the bootstrap admin (default `Administrator` ) | \n| `ANTHROPIC_API_KEY`*or*` CLAUDE_CODE_OAUTH_TOKEN` | For agents | Claude credential (setup token wins if both set) | \n| `CLAUDE_CODE_ENABLE_TELEMETRY` /`OTEL_METRICS_EXPORTER` /`OTEL_LOGS_EXPORTER` /`OTEL_EXPORTER_OTLP_PROTOCOL` | No | Enable Claude Code telemetry export when spawning agents | \n| `OTEL_ENDPOINT` /`AUTH_TOKEN` /`USER_EMAIL` | No | Convenience source vars used to derive `OTEL_EXPORTER_OTLP_ENDPOINT` ,`OTEL_EXPORTER_OTLP_HEADERS` , and`OTEL_RESOURCE_ATTRIBUTES` | \n| `OTEL_EXPORTER_OTLP_ENDPOINT` /`OTEL_EXPORTER_OTLP_HEADERS` /`OTEL_RESOURCE_ATTRIBUTES` | No | Direct telemetry overrides forwarded to Claude Code if you prefer to set OTEL values explicitly | \n| `GITHUB_CLIENT_ID` /`GITHUB_CLIENT_SECRET` | No | Enable GitHub login | \n| `GOOGLE_CLIENT_ID` /`GOOGLE_CLIENT_SECRET` | No | Enable Google login | \n\n**Invite-only.** Open self-registration is disabled - an admin creates all accounts. When\n`RONDOFLOW_ADMIN_EMAIL` and `RONDOFLOW_ADMIN_PASSWORD` are both set, the seed step (`npm run db:seed`, run for you by `npm run setup`) creates the first admin; leave both blank to skip.\n\nOpenAI and Perplexity API keys are configured in the app's Settings (instance-wide, shared by all agents of that provider).\n\nThe **Email node** sends a workflow's output via SMTP. Configure it with `SMTP_*` in `.env`, or at\nruntime in **Settings → Credentials** (a DB-stored value overrides `.env`; `SMTP_PASS` is stored\nencrypted). Leave `SMTP_HOST` blank to disable.\n\n| Variable | Default | What it does | \n|---|---|---|\n| `SMTP_HOST` | - | SMTP server hostname (blank disables email) | \n| `SMTP_PORT` | `587` | SMTP port | \n| `SMTP_SECURE` | `false` | `true` for implicit TLS (465),`false` for STARTTLS (587) | \n| `SMTP_USER` /`SMTP_PASS` | - | SMTP credentials ( `SMTP_PASS` encrypted if set in Settings) | \n| `SMTP_FROM` | - | From address, e.g. `RondoFlow <noreply@example.com>` | \n\n`.env.example` also documents optional variables not needed for a basic run:\n\n| Variable | Default | What it does | \n|---|---|---|\n| `PORT` /`UI_ORIGIN` | `3001` /`http://localhost:3000` | Backend port and allowed UI origin (CORS) | \n| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | `128000` | Max output tokens per agent response (clamped to each model's true max) | \n| `EXTERNAL_FOLDERS_HOST_PATH` /`EXTERNAL_FOLDERS_CONTAINER_ROOT` | `./external` /`/external` | Host directory bind-mounted into the server container, and the in-container root mounted folders resolve under (backs external-folder mounts) | \n| `RONDOFLOW_SPAWN_IDLE_TIMEOUT_MS` /`RONDOFLOW_SPAWN_MAX_MS` | `300000` /`0` | Kill a run after this many ms with no stream events / absolute wall-clock cap per spawn ( `0` disables) | \n| `RONDOFLOW_TEARDOWN_ON_DISCONNECT` /`RONDOFLOW_TEARDOWN_GRACE_MS` | `1` /`60000` | Tear down a user's in-flight runs after their last tab disconnects, following a grace window | \n\n```\nnpm run dev              # start everything (turbo)\nnpm run dev:ui           # frontend only (port 3000)\nnpm run dev:server       # backend only (port 3001)\nnpm run dev:docs         # docs site only (port 3002)\nnpm run build            # build all packages\nnpm run lint             # lint all packages\nnpm run format           # format with Prettier\nnpm run test             # run all tests (turbo)\nnpm run test:coverage    # run all tests with coverage\nnpm run db:migrate       # run database migrations\nnpm run db:seed          # load sample data (and bootstrap the admin)\nnpm run db:studio        # visual database browser\nnpm run docker:up        # start PostgreSQL only (for local dev)\nnpm run docker:down      # stop containers\n```\n\n**Tests:** both the `server` and `ui` packages use [Vitest](https://vitest.dev). `npm run test`\nruns the whole suite via the `turbo test` task; scope to one package with\n`npm test -w @rondoflow/server` or `npm test -w @rondoflow/ui`. The same lint / build / test\nsequence runs in CI ([`.github/workflows/ci.yml`](https://github.com/rondoflow/rondoflow/blob/master/.github/workflows/ci.yml)).\n\nA canvas talks to a server over websocket. The server's engine walks your workflow as a DAG, runs each agent through the right provider, and gates risky actions behind the policy layer.\n\n``` php\nflowchart LR\n    User([\"You\"]) -->|design and run| Canvas[\"Canvas UI<br/>React Flow\"]\n    Canvas <-->|Socket.IO live events| Engine\n\n    subgraph Engine[\"Server: Fastify + Socket.IO\"]\n        Chain[\"ChainExecutor<br/>DAG runner\"]\n        Plan[\"Planner\"]\n        Dir[\"Director\"]\n        Adv[\"Advisor\"]\n        Pol[\"PolicyResolver<br/>safety rules\"]\n        Chain --- Plan\n        Chain --- Dir\n        Chain --- Adv\n        Chain --- Pol\n    end\n\n    subgraph Runners[\"Agent runners\"]\n        CC[\"Claude Code CLI<br/>subprocess\"]\n        OAI[\"OpenAI API\"]\n        PPX[\"Perplexity API\"]\n    end\n\n    Chain --> CC\n    Chain --> OAI\n    Chain --> PPX\n    Engine <-->|Prisma| DB[(\"PostgreSQL\")]\n    CC -.->|tools, files, MCP| Host[(\"Your machine\")]\n```\n\nA run streams back live - here's the flow for a single Claude Code agent step:\n\n```\nsequenceDiagram\n    actor User\n    participant UI as Browser\n    participant Server as Server\n    participant Agent as Claude Code CLI\n    User->>UI: Run workflow\n    UI->>Server: Socket.IO chain:execute\n    loop each step in the DAG\n        Server->>Agent: spawn (no shell) with stream-json output\n        Agent-->>Server: stream events - text, tool_use, usage\n        Server-->>UI: live text + tool-use cards\n        opt risky command\n            Server-->>UI: approval request\n            UI-->>Server: approve or reject\n            Server->>Agent: stdin response\n        end\n        Agent-->>Server: step complete\n        Note over Server: Director decides continue / redirect / conclude\n    end\n    Server-->>UI: chain complete + token usage\n```\n\nContributions are welcome! Please read **[CONTRIBUTING.md](https://github.com/rondoflow/rondoflow/blob/master/CONTRIBUTING.md)** for setup, code\nconventions, and the PR process. In short:\n\n```\n# Fork, clone, then:\nnpm run setup\nnpm run dev\n\n# Before submitting a PR:\nnpm run build && npm run lint\n```\n\nBug reports and feature requests go through the [issue templates](https://github.com/rondoflow/rondoflow/blob/master/.github/ISSUE_TEMPLATE). By\ncontributing, you agree your work is licensed under the project's MIT license.\n\nRondoFlow runs AI agents that can execute code on your machine, so please review the threat model\nand deployment guidance in **[SECURITY.md](https://github.com/rondoflow/rondoflow/blob/master/SECURITY.md)** before exposing it beyond localhost.\nFound a vulnerability? Report it privately via GitHub's\n[security advisories](https://github.com/rondoflow/rondoflow/security/advisories/new) - please don't\nopen a public issue.\n\n[MIT](https://github.com/rondoflow/rondoflow/blob/master/LICENSE) © RondoFlow contributors. RondoFlow began as a fork of\n[Orchestra](https://github.com/gbrein/Orchestra) (also MIT) and has diverged substantially since,\nwith the original copyright retained in [LICENSE](https://github.com/rondoflow/rondoflow/blob/master/LICENSE). Third-party dependency licenses are\nsummarized in [THIRD_PARTY_NOTICES.md](https://github.com/rondoflow/rondoflow/blob/master/THIRD_PARTY_NOTICES.md).\n\nQuestions, ideas, and show-and-tell go in\n[GitHub Discussions](https://github.com/orgs/rondoflow/discussions). Found a bug or have a\nfeature request? Open one through the\n[issue templates](https://github.com/rondoflow/rondoflow/issues/new/choose). For security issues,\nplease use private [security advisories](https://github.com/rondoflow/rondoflow/security/advisories/new)\nrather than a public issue.", "url": "https://wpnews.pro/news/show-hn-visually-orchestrate-claude-code-ai-agents", "canonical_source": "https://github.com/rondoflow/rondoflow", "published_at": "2026-09-23 05:55:48+00:00", "updated_at": "2026-09-23 06:23:46.063057+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "agent-protocols"], "entities": ["RondoFlow", "Claude Code", "Anthropic", "OpenAI", "Perplexity", "React Flow", "Fastify", "Next.js"], "alternates": {"html": "https://wpnews.pro/news/show-hn-visually-orchestrate-claude-code-ai-agents", "markdown": "https://wpnews.pro/news/show-hn-visually-orchestrate-claude-code-ai-agents.md", "text": "https://wpnews.pro/news/show-hn-visually-orchestrate-claude-code-ai-agents.txt", "jsonld": "https://wpnews.pro/news/show-hn-visually-orchestrate-claude-code-ai-agents.jsonld"}}