How to Use Paradev: The Beginner's Guide (First Workspace, Parallel Agents, and the Review-Merge Flow)
CodexFuse Team · 2026-11-03T07:41:40.145Z · 13 min read min read
Learning how to use Paradev starts with one mental shift: stop running a single coding agent in a single terminal, and start orchestrating many agents in parallel workspaces. Paradev — formerly Superset, renamed on October 26, 2026 — is a source-available desktop workspace that gives every task its own Git worktree and branch, then lets you review and merge everything from one board. This Paradev tutorial covers the full beginner arc: install, sign-in, your first workspace, parallel agents, and the review-merge flow. If you already run one persistent AI teammate instead, our OpenClaw beginner guide covers that lane; Paradev is the other end of the spectrum — many agents, many tasks, one review queue.
What is Paradev, exactly?
Paradev is a source-available desktop workspace for orchestrating CLI-based coding agents in parallel. Each task runs in its own Git worktree and branch, and a shared board tracks every workspace from Working to Needs review to Merged. It is not a model and not a code editor — in the vendor's own framing, Paradev is the orchestration layer around agents.
The code is public on GitHub under the Elastic License 2.0 (ELv2). That makes Paradev source-available, but it is not OSI-approved open source — an important distinction to keep straight, because the two terms are not interchangeable. The repository moved to github.com/paradevai/paradev as part of the October 2026 rebrand, with old links redirecting.
How do I install Paradev?
Pick one of three install routes — the one-line script, Homebrew, or the desktop app. All three give you the same CLI, and the CLI is currently in beta, so commands can still evolve.
| Route | Command | Details |
|---|---|---|
| Shell script | curl -fsSL https://paradev.com/cli/install.sh | sh | Auto-detects macOS (Apple Silicon/Intel) or Linux (x64/arm64); installs under ~/superset and adds ~/superset/bin to PATH |
| Homebrew | brew install paradevai/tap/superset | Same CLI through the Paradev tap |
| Desktop app | Download from paradev.com | macOS desktop (experimental Linux AppImage); includes the CLI and writes shims to ~/.paradev/bin/superset and ~/.paradev/bin/paradev — add $HOME/.paradev/bin to PATH for a normal shell |
One naming quirk to learn on day one: the binary is called superset, the product's old name. paradev is an alias — either name runs the same binary. The old superset.sh domain redirects to paradev.com now, and the superset command keeps working so existing scripts do not break.
Platforms are limited for now. The desktop app ships for macOS and as an experimental Linux AppImage; Windows is not yet available, per the vendor FAQ. There is also an iPhone and iPad app on the App Store — but using it requires Paradev Pro, the paid tier.
What happens on first run?
First you sign in, then you create a project that points at a local repository. The sign-in is a browser OAuth flow:
superset auth login
This opens the browser, completes a loopback callback on 127.0.0.1:51789, and stores a token at ~/.paradev/config.json. Treat that token like any credential — it lives in your home directory and must not be committed anywhere.
Organizations and headless setups have their own flags: superset auth login --organization acme for an org, and superset auth login --api-key sk_live_… (or the SUPERSET_API_KEY environment variable) for CI. Then point Paradev at your code:
superset projects list superset projects create --name "my-app" --local --import ~/code/my-app
Because every project is a Git repository and every workspace becomes a branch, solid branching fundamentals pay off here. If yours are rusty, the GitHub beginner guide covers repositories, branches, and pull requests.
How do I create my first workspace and run an agent?
One command does it all: superset workspaces create spins up a workspace on its own branch and starts an agent with your prompt. Here is the first-run arc, start to finish:
- Create the project pointing at your local repository (see above).
- Run one command to create the workspace and start the agent:
superset workspaces create --project PROJECT_ID --name "fix-login-bug" --branch fix/login-bug --local --agent claude --prompt "Fix the login bug..." - Watch the workspace appear on the board in the Working state.
- The agent works in its own Git worktree while you keep coding in yours — the two never share a working directory.
- When the board flips the workspace to Needs review, read the diff and merge or request changes.
To add another agent to an existing workspace, use superset agents create --workspace WORKSPACE_ID --local --agent codex --prompt "...". Paradev agents are simply the CLI coding tools you connect per task — and you are not locked to one model provider:
| Agent | CLI name for Paradev | Typical strength |
|---|---|---|
| Claude Code | claude | Deep codebase reasoning; the example agent in the vendor's own docs |
| OpenCode | opencode | Lightweight open CLI runner |
| OpenAI Codex | codex | Strong at focused, well-scoped tasks |
The board lets you switch agents between tasks while your workflow stays put — that agent independence is one of Paradev's headline features. New to the flagship agent itself? The Claude Code beginner guide walks through sessions, slash commands, and the safety line.
How do parallel agents actually work?
Each task gets its own Git worktree plus its own branch, and all of them show up on one shared board. Paradev worktrees are the isolation unit: a Git worktree is a second checkout of the same repository, so the agent's files and your files never share a working directory — and the branch keeps the commit history separate too.
The board itself is the control tower. Workspaces move through four states — Working, Needs attention, Needs review, Merged — so you can glance at dozens of agents and know exactly which ones need you. One command creates a workspace on its own branch and starts an agent with a prompt, which is why the product's tagline is "run an army of coding agents" (the vendor claims it scales to 100+ agents — reported as claimed, not independently verified).
Now the caveat, stated once because it matters: worktrees separate files, but they do not sandbox processes and they do not prevent merge conflicts. The vendor says this in its own FAQ and docs. So the practical rule is to give agents independent tasks — two agents editing the same file from two worktrees will still collide at merge time. Product Hunt community threads echo this from experience: parallel agents on dependent tasks are where errors creep in.
How do I review and merge what the agents did?
Everything funnels into the Changes pane — the heart of the Paradev review flow: read each workspace's diff, send follow-ups to the agent, open a pull request, and check CI — all from the same window. The built-in diff viewer is the core of the review-merge flow, and the PR view shows checks and review threads. Line comments from a pull request can even be sent back to the agent for another pass.
This is where Paradev earns its keep as a review-merge tool rather than a launcher. The balanced verdict: orchestration shines when tasks are genuinely parallelizable — bug fixes in different modules, independent features, parallel experiments. Serial, deeply interdependent work still belongs to one agent at a time, no matter how pretty the board looks.
Paradev vs Superset — did anything actually change?
No — only the name changed. Superset became Paradev on October 26, 2026 (the rename was announced on October 12), and everything else stayed put: same product, same accounts, same workspaces, same billing.
The vendor's stated reason for the rebrand is disarmingly honest: the old name was "shared by many existing products and companies" — most notably Apache Superset, the business-intelligence tool, which is completely unrelated. They wanted a name that was "truly ours." The meaning they give it: "Lawyers have paralegals, doctors have paramedics, and developers have paradevs."
Practically, the transition is painless. The superset command keeps working and paradev is its alias, superset.sh redirects to paradev.com, and the GitHub repository moved to paradevai/paradev with old links redirecting. The rebrand coincided with a $11.5M seed round led by Union Square Ventures, announced the same day, with Y Combinator and other firms participating (vendor-reported). Founders are Kiet Ho (CEO), Satya Patel (CTO), and Avi Peltz (CPO), all previously CTOs at Y Combinator companies.
Paradev vs OpenClaw — which style fits your workflow?
Pick by the mental model: Paradev orchestrates many task-scoped agents in parallel workspaces, while OpenClaw runs one persistent, always-on personal agent. Neither vendor publishes a direct comparison, so the split really comes down to how you want to work:
| Dimension | Paradev | OpenClaw |
|---|---|---|
| Unit of work | Many tasks, each in its own worktree + branch | One ongoing agent relationship |
| Agent count | Many in parallel (vendor claims 100+) | One persistent agent |
| Isolation | Per-task Git worktrees and branches | Single persistent session |
| Review surface | Shared board + diff viewer + PR flow | Conversational, in-session |
| Best fit | Batching independent coding tasks | An assistant that lives alongside you |
They are not rivals so much as different answers to "where does the agent live." If your day is ten small independent tickets, Paradev's board wins. If you want one teammate who remembers everything, the personal-agent lane does.
What does Paradev cost?
Paradev pricing has two halves, and the second one is the story: there is a free tier, paid plans start at Pro at $20 per user per month, and you always bring your own model keys — Paradev never proxies model calls and does not bill for model usage. All pricing below is vendor-reported, current as of early November 2026:
| Plan | Price | Notes |
|---|---|---|
| Free | $0 | The entry tier; "free forever" desktop per the vendor |
| Pro | $20/user/month ($16 billed yearly) | Unlocks the iPhone/iPad app |
| Team | $60/user/month ($54 billed yearly) | Multi-user workspaces |
| Ultra | $200/user/month | Heavy-usage tier |
| Enterprise | Custom | Org-level needs |
The bring-your-own-model design is the pricing story's second half: because you supply your own API keys, your model spend stays with the model provider and Paradev's bill is only for the orchestration layer. That local-first billing model is also why there is no per-token meter on Paradev's side to watch.
How do Paradev automations work?
Automations start agents on events or a schedule, so routine work runs without you opening the app. The vendor's examples are issue triage, changelog drafts, and dependency bumps, with webhook triggers for anything event-driven. The commands are straightforward: superset automations list, superset automations run AUTOMATION_ID, and superset automations logs.
Automations run against your connected machines — see the superset hosts list command for the inventory. If those machines are remote boxes you manage yourself, our what is VPS hosting guide explains the server side of that setup. And to keep an eye on what agents are doing mid-run, superset terminals list --workspace WORKSPACE_ID --local --json plus superset terminals read give you the raw terminal output.
What can the Paradev CLI actually do?
A handful of commands covers the whole surface — authentication, projects, workspaces, agents, terminals, automations, and hosts. Everything is scriptable, which is why the vendor also ships a TypeScript SDK for wiring Paradev into CI and an MCP server so your agent can drive Paradev itself (public MCP setup details are still thin in the docs as of this writing):
| Area | Key commands |
|---|---|
| Auth | superset auth login, --organization, --api-key / SUPERSET_API_KEY |
| Projects | superset projects list, superset projects create --name --local --import |
| Workspaces | superset workspaces create --project --name --branch --local --agent --prompt |
| Agents | superset agents create --workspace --local --agent --prompt |
| Terminals | superset terminals list --workspace --local --json, superset terminals read |
| Automations | superset automations list|run|logs |
| Hosts & MCP | superset hosts list, superset mcp tools, superset mcp call-tool |
6 mistakes beginners make with Paradev
The failure modes are predictable — and most of them come from treating an orchestration layer like a single agent:
| # | Mistake | What to do instead |
|---|---|---|
| 1 | Running dependent tasks in parallel | Split work into independent tasks first; parallel agents on overlapping work produce errors and merge conflicts (the vendor and community both say so) |
| 2 | Calling it "open source" | It is source-available under Elastic License 2.0 — public code, but not OSI-approved open source |
| 3 | Typing paradev where docs say superset and panicking | Both names run the same binary — paradev is an alias for superset |
| 4 | Assuming worktrees sandbox everything | Files are isolated; processes are not — keep agents off each other's runtime resources |
| 5 | Sending a one-line prompt for a complex task | One command creates the workspace AND the agent's briefing — write the prompt like a ticket: goal, scope, constraints, done criteria |
| 6 | Ignoring the auth token's home | ~/.paradev/config.json holds your session token — never commit it, never paste it into a prompt |
Sources
- Paradev CLI Getting Started — docs.paradev.com/cli/getting-started (install commands, auth flow, first-run commands; fetched 2026-11-03)
- Paradev CLI Reference — docs.paradev.com/cli/cli-reference (full command surface; fetched 2026-11-03)
- Paradev homepage and FAQ — paradev.com (product description, platforms, ELv2 license, pricing tiers; fetched 2026-11-03)
- "A New Name" — paradev.com/blog/a-new-name (rebrand reason and date; iPhone/iPad app requires Pro; fetched 2026-11-03)
- "Superset is now Paradev" — paradev.com/blog/superset-is-now-paradev ($11.5M seed led by Union Square Ventures; founders; rebrand details; fetched 2026-11-03)
- "Vibe Kanban Is Shutting Down: What to Move To in 2026" — paradev.com/compare/vibe-kanban-alternative (comparison format, vendor claims; fetched 2026-11-03)
- "Best IDE for Gemini CLI in 2026" — paradev.com/compare/best-ide-for-gemini-cli (comparison lane; fetched 2026-11-03)
- "Best cmux Alternatives in 2026" — paradev.com/compare/cmux-alternative (comparison lane; fetched 2026-11-03)
- "Best Grok Bot Alternatives" — paradev.com/compare/grok-bot-alternative (pricing corroboration; fetched 2026-11-03)
- Founderland — founderland.ai article on Paradev's $11.5M raise (seed news, rebrand coverage; fetched 2026-11-03)
- Subagentic — subagentic.ai post on the Paradev/Superset seed (rebrand and funding coverage; fetched 2026-11-03)
- EveryDev — tool directory listing (pricing and platform corroboration; fetched 2026-11-03)
- Product Hunt — community threads on parallel-agent usage (dependent-task criticism; fetched 2026-11-03)
Frequently Asked Questions
Is Paradev open source?
No. Paradev is source-available under the Elastic License 2.0 — the code is public on GitHub at github.com/paradevai/paradev, but ELv2 is not an OSI-approved open source license, so the two labels are not interchangeable.
Is Paradev the same thing as Superset?
Yes. Superset was renamed to Paradev on October 26, 2026; only the name, logo, website, and email domain changed. Your accounts, workspaces, and billing are untouched, the superset command still works, and paradev is its alias.
Does Paradev work on Windows?
Not yet, per the vendor FAQ. The desktop app runs on macOS and as an experimental Linux AppImage, plus the CLI, a TypeScript SDK, an MCP server, and an iPhone/iPad app that requires the Pro plan.
How much does Paradev cost?
There is a free tier, and paid plans start at Pro at $20 per user per month ($16 billed yearly), then Team at $60, Ultra at $200, and custom Enterprise. You always bring your own model API keys, so Paradev never bills you for model usage — only for the orchestration layer.
Can my parallel agents see each other's work?
Each task runs in its own Git worktree and branch, so agents do not share a working directory. But worktrees do not sandbox processes and do not prevent merge conflicts, so keep agents on independent tasks and let the review-merge board reconcile the results.
