# Add Paradev Support to Your Agent Source: https://docs.paradev.com/add-agent-support For agent makers - how your coding agent runs in Paradev today, and what first-class support takes ## Overview [#overview] If you build a terminal coding agent, it already runs in Paradev: users can add any command as a custom agent, and it gets its own workspace, Git worktree, and terminal. First-class support adds status indicators, notifications, session resume, and usage tracking. This page explains what each one needs from your agent, so Paradev users get the best experience with it. ## Works Today: Custom Agents [#works-today-custom-agents] Users add your agent in **Settings → Agents → Add agent → Custom agent…** with: * **Command** - how to launch your agent * **Prompt-only args** and **Prompt transport** - how Paradev passes a prompt: as an argument or on stdin * **Resume args** and **Fork args** - how to reopen or clone a session by its id, if your agent supports it To make this easy, document a single command that starts your agent, a way to pass the first prompt as an argument or on stdin, and, if you have them, resume and fork flags that take a session id. Inside a Paradev terminal, your agent can read these environment variables: | Variable | Description | | ------------------------- | ------------------------------------------- | | `SUPERSET_WORKSPACE_ID` | The workspace the terminal belongs to | | `SUPERSET_WORKSPACE_PATH` | Path to the workspace's worktree | | `SUPERSET_ROOT_PATH` | Path to the main checkout of the repository | | `SUPERSET_TERMINAL_ID` | The terminal the agent runs in | ## First-Class Support [#first-class-support] Built-in agents get more than a terminal. Each feature below has a clear requirement: | Feature | What your agent needs | | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Status** (working, needs input, done) and notifications | Lifecycle hooks that run a command on session start, prompt submit, tool use, permission request, stop, and session end. Hooks shaped like Claude Code's (`hook_event_name`, `session_id` in a JSON payload) are the easiest to support. | | **Resume after restart** | A stable session id reported in those hooks, and a flag that reopens a session by id. | | **Fork session** | A flag that clones a session by id. | | **Usage history** | Session logs on disk that record tokens per model, in a documented location and format. | | **Quota meter** | A documented way to read the subscription's usage windows. | | **Model and effort pickers** | Flags or environment variables that select a model and reasoning effort. | Built-in agent support lives in the Paradev repository on GitHub. To request it, [open an issue](https://github.com/paradevai/paradev/issues) with your agent's install command, its hook and session-id documentation, and where it writes session logs. We review pull requests that add an agent too. ## What Users See [#what-users-see] With first-class support, your agent appears in Paradev's agent launcher with its icon, shows a live status in the sidebar, sends a notification when it needs input or finishes, and comes back with its session after a restart. See [Supported Agents](/supported-agents) for where each built-in agent stands today. --- # AI Agents Source: https://docs.paradev.com/agent-integration Use Claude Code and other AI agents ## Overview [#overview] Run AI coding agents in isolated workspaces. Each agent works independently without interfering with others. AI Agents ## Supported Agents [#supported-agents] * **Claude Code** - Anthropic's CLI * **Amp** - Amp Code CLI * **Codex** - OpenAI's assistant * **Gemini CLI** - Google's CLI agent * **Mastracode** - Mastra's terminal coding agent * **OpenCode** - Open-source alternative * **Pi** - Minimal terminal coding harness * **Oh My Pi** - Terminal-first coding agent with session-aware workflows * **Copilot** - GitHub's coding agent * **Mistral Vibe** - Mistral's terminal coding agent * **Kimi Code** - Moonshot AI's CLI coding agent * **Grok** - xAI's CLI coding agent (Grok Build) * **Cursor Agent** - Cursor AI agent * **Droid** - Factory's autonomous coding agent * **Polygraph** - Meta-harness with cross-repo visibility and persistent memory * **Hermes** - Nous Research's autonomous coding and research agent * **Muse Code** - Meta's terminal coding agent with persistent subagents * **Devin** - Cognition's Devin agent in the terminal, with Devin Cloud handoff * **fx** - Vercel's terminal coding agent * **Antigravity** - Google's Antigravity CLI (`agy`) * **Kiro** - AWS's spec-driven CLI coding agent * **UFO** - UFO's workspace assistant for local and remote terminal workflows ## Chat [#chat] Paradev includes a built-in chat panel for AI interactions without leaving the app. * Use the model picker to choose supported models and connect providers * Chat session titles are generated automatically from the conversation * Use the thinking level control to adjust reasoning effort for the selected model ## Models and Reasoning Effort [#models-and-reasoning-effort] The model pickers include **GPT-6 Astra**, **GPT-6 Sol**, and **GPT-6 Luna**, and **Opus 5.5** and **Sonnet 5.5**, wherever the agent supports them: Claude Code (Claude models), Codex (GPT models), Copilot, OpenCode, Oh My Pi, and Paradev Chat. In the Codex picker, **GPT-5.5** is under **Retiring 2026-10-14**, and the retired GPT-5.4 and GPT-5.3 Codex are gone. Available reasoning levels depend on the agent and model; see the [launch options](/cli/cli-reference#agent-effort-levels). ## Agent Settings [#agent-settings] Go to **Settings → Agents** to change how each agent launches, reorder agents, or add your own. * **Label** and **Icon** - How the agent appears in launchers and the list * **Command** - The command used to launch the agent * **Prompt-only args** - Arguments added only when Paradev launches the agent with a prompt * **Prompt transport** - How the prompt is delivered to the process (as an argument or on stdin) * **Resume args** - Arguments used to restore a session by its id (e.g. `--resume`) * **Fork args** - Arguments used to clone a session by its id. Put `{sessionId}` where the id belongs (e.g. `--resume {sessionId} --fork-session`); leave empty if the agent cannot fork * **Paradev hooks** - Whether Paradev installs its status hooks for the agent * **Restore defaults** - Restore the shipped configuration for a built-in agent To add an agent that isn't built in, choose **Add agent → Custom agent…**. A custom agent runs in its own worktree like any other. To see which features each built-in agent supports, see [Supported Agents](/supported-agents). ## Usage [#usage] Run agents directly in the terminal: ```bash claude "Add error handling to fetchUser" ``` ## Auto-Run Command [#auto-run-command] When launching an agent from a task, the **Auto-run command** toggle controls whether it executes immediately. * **On** - Terminal agents run their command right away, and Paradev Chat sends the task prompt immediately * **Off** - Terminal agents stage the command without pressing Enter, and Paradev Chat opens as a draft instead The setting is remembered between sessions. ## Agent Sessions & Forking [#agent-sessions--forking] Resume an interrupted session, fork a session, or hand its work to another agent. See [Agent Sessions & Forking](/agent-sessions). ## Parallel Agents [#parallel-agents] Create multiple workspaces and run an agent in each. Compare results and merge the best solution. ## Inline Prompts [#inline-prompts] Agents can pause and ask questions, request tool approval, and ask for plan review directly in the chat pane. ## Sandbox Access [#sandbox-access] When an agent needs access to files outside its workspace, it will prompt for permission in chat so you can approve or deny the request inline. ## Notifications [#notifications] Get notified when agents finish. Configure sounds in Settings. ## Agent Skills [#agent-skills] Teach any agent to drive Paradev itself with the official [skills](https://github.com/paradevai/skills), one for the `superset` CLI and one for the [MCP server](/mcp-server): ```bash npx skills add paradevai/skills ``` --- # Agent Sessions & Forking Source: https://docs.paradev.com/agent-sessions Resume, fork, and hand off agent sessions An agent session is one agent conversation running in one terminal. Paradev can bring a session back after its terminal dies, copy it into a new session of the same agent, or pass its recent context to a different agent. ## Resume Interrupted Sessions [#resume-interrupted-sessions] If an agent's terminal dies under it (a crash, a reboot, a killed process), Paradev resumes the session automatically: the pane relaunches the agent with its resume command (e.g. `claude --resume `) and shows a "Resuming…" pill while it happens. Only unexpected deaths qualify: sessions you close or kill deliberately, and agents that exited cleanly, stay down. If the resume fails, the pill turns into "Failed to resume" with a **Retry** button and a dismiss control. Works for agents with an id-based resume command (the **Resume Args** field under **Settings → Agents**). From the CLI: ```bash superset agents create --workspace ws_… --agent claude --resume-session ``` ## Fork and Hand Off Sessions [#fork-and-hand-off-sessions] The fork icon in an agent terminal's header opens two actions. Both open the new session in a split pane or a new tab. The fork icon menu on a Claude terminal with Continue with another agent and Fork session * **Continue with another agent** - Starts a fresh session of the agent you pick, seeded with this terminal's recent context. Use it when a session is stuck, out of context, or the wrong tool for the job. The dialog shows how many characters (and about how many tokens) it will send before you continue. * **Fork session** - Starts a native copy of this session in the same agent, with the same conversation. The original session keeps running unchanged. ### Fork [#fork] Fork uses the agent's own fork command, so the copy has the full conversation. Built-in agents that can fork, with the fork part of each command: | Agent | Fork command | | ----------- | ------------------------------------- | | Claude Code | `claude --resume --fork-session` | | Codex | `codex fork ` | | OpenCode | `opencode --session --fork` | | Pi | `pi --fork ` | | Grok | `grok --resume --fork-session` | | Droid | `droid --fork ` | Paradev also passes the agent's launch flags, such as `--dangerously-skip-permissions` for Claude Code, so a fork runs with the same permissions as a new session. **Settings → Agents** shows each agent's command and fork args. For other agents, set **Fork Args** under **Settings → Agents**. **Fork session** is disabled until Paradev knows the agent's session id, and for agents without fork args. For Claude Code, Codex, OpenCode, and Pi, Paradev refuses the fork if the agent has deleted the source session. For other agents, Paradev cannot check, so the new pane opens and the agent reports the missing session there. A fork copies the conversation, not the files. Both sessions work in the same workspace. ### Continue with another agent [#continue-with-another-agent] The new session gets a prompt that contains the last 36,000 characters of this terminal's context, marked as read-only history. The prompt tells the agent to check `git status` and the files first, because the workspace, not the transcript, is the source of truth. For Claude Code and Codex, Paradev reads the agent's own saved conversation when it can. Otherwise it reads the terminal's recorded output stream, not only the visible screen. A handoff sends terminal output to the target agent's provider. Paradev removes terminal control codes but does not redact anything, so tokens, keys, or connection strings that a command printed go with it. If the session showed credentials, ask the agent for a summary and start the new agent with that instead. ## Find Session and Terminal IDs [#find-session-and-terminal-ids] Click the copy icon in an agent terminal's header (**Copy IDs**): * **Copy agent session ID** - The agent's own session id, used by `--resume-session` and `--fork-session` * **Copy terminal ID** - The Paradev terminal id, used by `--from-terminal` and `superset agents read` ## From the CLI [#from-the-cli] ```bash # Fork a session superset agents create --workspace --agent claude --fork-session # Continue in another agent superset agents create --workspace --agent codex --from-terminal ``` `--from-terminal` builds its own prompt, so it does not accept `--prompt`. Use `--context-chars` to send less than 36,000 characters. See [`agents create`](/cli/cli-reference#agents). ## Read an Agent's Transcript [#read-an-agents-transcript] `superset agents read` returns the agent's saved conversation, including what scrolled off a full-screen interface. Paradev can read saved transcripts for Claude Code and Codex. The command fails for other agents, and when the saved transcript is missing. It does not fall back to terminal output. ```bash superset agents read --local --workspace --terminal ``` --- # Agent Status & Notifications Source: https://docs.paradev.com/agent-status How Paradev knows what your agents are doing, and how it tells you ## The Activity Strip [#the-activity-strip] Each workspace in the sidebar shows an activity strip: * **Running agents and open ports** appear inline on the workspace item * **Running and PR state persist across restarts** * Workspaces with live work are visually emphasized so in-progress items stand out * Agent chips stay hidden unless multiple agents are running in that workspace If a workspace shows as running after you've stopped its agent (for example after force-quitting the agent), use **Clear Status** on the workspace to reset the indicator. ## How Status Is Detected [#how-status-is-detected] Paradev installs lifecycle hooks and command wrappers into each agent's config (the entries in `~/.superset/bin` and files like `superset-hooks`). Those hooks report when an agent starts, finishes, or is waiting for input. That's why status only works for agents launched through Paradev, and why removing the hooks disables status and notifications. The hooks no-op outside Paradev terminals (they check for a Paradev-supplied env var). To remove them from an agent's config entirely, turn off the agent's **Paradev hooks** toggle in **Settings → Agents**. ## Notifications [#notifications] * **Finished / waiting for input**: get notified when an agent finishes or pauses for your input. Configure sounds in Settings. * **Support varies by agent.** Claude Code reports both finished and waiting states. Some agents don't emit a waiting-for-input signal yet, so you'll only get completion notifications for them. * **Inline prompts**: agents can pause to ask questions, request tool approval, or ask for plan review directly in the chat pane, and the workspace is flagged as needing attention. ## Dock Badge [#dock-badge] The macOS dock icon shows a badge for workspaces with unread activity or that need your attention. Dock icon showing an attention badge macOS only shows dock badges when Paradev has notification permission. If you don't see badges, check **System Settings → Notifications → Paradev**. --- # Automations Source: https://docs.paradev.com/automations Run agent sessions on a schedule or when something happens in GitHub, Slack, Linear, Sentry, Notion, Microsoft Teams, or a webhook ## Overview [#overview] Automations run an agent session against a project when something happens (a review is requested, an issue is filed, a message lands in a channel) or on a schedule, like a cron job. Either way the output is a live workspace you (or a teammate) can open, review, and continue interactively. The Automations list with scheduled agent sessions Typical uses: * **Standups**: a nightly summary of PRs, issues, and activity * **Release notes**: generate a draft from merged commits * **Audits**: scan for security issues or deprecated APIs each morning * **Dependency sweeps**: check for outdated packages weekly * **PR reviews**: review a pull request as soon as you're requested as a reviewer * **Bug triage**: reproduce a new Sentry issue or a report posted in #bugs The list shows 7-day health stats (Active, Created, Failed), groups enabled automations by soonest run under **Up next**, and splits into **Mine** and **Team** tabs. Team automations are read-only; only the owner can edit, pause, run, or delete one. ## Requirements [#requirements] * **A Pro plan**: Automations are a [Pro feature](https://superset.sh/pricing). Creating, running, and resuming an automation needs a Pro or Enterprise subscription on the organization, from the app, the CLI, or the SDK alike. An organization that downgrades keeps its automations and can still edit, pause, or delete them, but they stop firing until it upgrades again. * **A project, or session mode**: automations usually run against a v2 project linked to a GitHub repo. Pick **No project** and each run creates a [session workspace](/workspaces#sessions) instead. * **A target device**: The run fires on the device you pick when creating the automation. * **A connected integration, for event triggers**: connect GitHub, Slack, Linear, Sentry, Notion, or Microsoft Teams from **Integrations** before you add one of its triggers. Microsoft Teams triggers need an Enterprise plan; every other trigger works on Pro. ## Create an Automation [#create-an-automation] Click **Automations → New automation** and fill in: * **Title**: how the automation appears in the list * **Prompt**: the instructions the agent will receive at dispatch time. Supports markdown, `@file/path` mentions (scoped to the selected project), `:emoji:` shortcodes, and `/` slash commands. * **Device**: which host runs the session. Defaults to this device. Pick **Cloud** to run each session in a new [cloud workspace](/cloud-workspaces) at the [machine size](/cloud-workspaces#machine-sizes) you choose, or in an existing cloud workspace. * **Project**: the v2 project the session runs against, or **No project** for a session per run. * **Trigger**: an event from a connected integration, a webhook, or a schedule. See [Triggers](#triggers). * **Agent**: Claude, Codex, Amp, or anything else you've set up under **Settings → Agents**. ## Triggers [#triggers] Triggers decide when an automation runs. They live in the **Triggers** card on the automation's detail page: **Add Trigger** opens a searchable menu of providers and events, and each trigger reads as a sentence you fill in, like "Review requested from **Me** in **acme/web** by **Anyone**". One automation can have up to 25 triggers and can mix events and schedules. Edits are drafts until you press **Save**. ### Event triggers [#event-triggers] An event trigger starts a run when the event comes in, without waiting for a schedule. Pick the provider, the event, and the scope it watches: | Provider | Events | Scope and filters | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | GitHub | Pull request opened, pushed, merged, closed, review requested, or assigned; draft opened; comment added; PR review comment; PR review submitted; review thread resolved or unresolved; issue comment; label change; checks completed; workflow run completed; new push to branch; release published, created, edited, unpublished, or deleted | One repository (required), branches, labels, comment text, and people (Anyone, Me, or specific people) | | Slack | Message in channel, reaction added, channel created | Channels (required, except for channel created), message text or new channel name, emoji (required for reaction added), people | | Linear | Issue created, status changed, or assigned; cycle ended | Teams (required), projects, labels, status, assignee | | Sentry | Issue created, resolved, assigned, archived, or unresolved; any issue event | Projects (required), level (Fatal, Error, Warning, Info, Debug) | | Notion | Rows changed, comment added, comment mentions user | Data sources (required), pages, people | | Microsoft Teams | Message in channel, channel created | Team (required), channels (required for message in channel), message or channel name text, people | Text filters are plain, case-insensitive "contains" matches against the first 4,096 characters, not regular expressions. Thread replies in Slack don't count as a message in channel. GitHub triggers skip pull request events from forks (opened, pushed, reviews, review comments, threads), and a run never checks out a fork's branch. A top-level comment on a fork's pull request can still fire **Comment added**, and checks and workflow runs from fork pull requests still fire. If the provider isn't connected, the trigger shows **Requires connection** with a **Connect** button; an expired connection shows **Connection expired** with a **Reconnect** button. A few providers need one extra step: * **Slack**: the Paradev bot joins the public channels you pick when you save. For a private channel, invite **@Paradev** to it first. * **Notion**: share the pages and data sources the automation should watch with the Paradev integration. * **Microsoft Teams**: a tenant administrator grants consent once for the whole tenant. * **GitHub**: a trigger that filters by **Me** needs your personal GitHub account connected, or it won't fire. ### Webhook triggers [#webhook-triggers] A webhook trigger runs the automation whenever something sends a POST to its URL, so any service that can call a URL can start a run. 1. Add a **Webhook triggered** trigger and save. 2. Click **Generate token**, then **Copy URL with token** (or **Copy auth header**). The token starts with `sset_wh_` and is shown once. **Regenerate token** asks you to confirm, then replaces it, and the old token stops working immediately. 3. Send a JSON body to the URL, with the token as a bearer header or as a `?token=` query parameter: ```bash curl -X POST "https://api.superset.sh/api/automations/webhook/" \ -H "Authorization: Bearer sset_wh_..." \ -H "Content-Type: application/json" \ -d '{"service": "checkout", "status": "failed"}' ``` The body must be a JSON object or array of at most 1 MiB; an empty body counts as `{}`. Each token can make 300 requests per minute. Responses: `200` when the delivery is accepted (the reply's `runs` field says how many runs it started; `0` means none did, for example on a plan without automations), `400` if the automation is paused or the body isn't JSON, `401` for a missing or invalid token, `413` for a body that's too large, `429` past the rate limit. Every request is a new event: webhook triggers have no filters and no de-duplication. ### What the agent receives [#what-the-agent-receives] The agent gets your prompt with the event that started the run in front of it: the provider, the event type, its title, URL, and who did it, plus the event payload (capped at 24,000 characters). For a webhook it's the JSON body you sent. So a prompt like "Review this pull request and leave comments" knows which pull request to look at. When a pull request event runs in a project linked to that repository, the run's workspace checks out the pull request's branch, and reuses that pull request's workspace if one exists. If the device can't fetch the pull request, the run starts on a fresh branch. ### Guides [#guides] * [Review pull requests when your review is requested](/recipes/review-requested-prs): GitHub **Review requested** * [Triage new Sentry issues](/recipes/sentry-triage): Sentry **Issue created** * [Fix bugs reported in Slack](/recipes/slack-bug-reports): Slack **Message in channel** * [Start a run with a webhook](/recipes/webhook-runs): **Webhook triggered** ### Schedules [#schedules] Schedules are stored as [RFC 5545 RRules](https://datatracker.ietf.org/doc/html/rfc5545#section-3.8.5). The picker has presets for Hourly, Daily, and Weekly. **Custom** opens with a weekdays rule you can edit, for anything else. Times use your timezone at creation, and each schedule shows its next run inline. Custom rules are validated inline: invalid rules, rules with no upcoming runs, and one-shot rules (`COUNT`/`UNTIL`) are rejected before saving. Examples: * `FREQ=DAILY;BYHOUR=9;BYMINUTE=0`: every day at 9:00 AM * `FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=9;BYMINUTE=0`: weekdays at 9:00 AM * `FREQ=WEEKLY;BYDAY=FR;BYHOUR=17;BYMINUTE=0`: every Friday at 5:00 PM ## Runs [#runs] Each time an automation fires, from an event or a schedule, a **run** is recorded. Runs show up on the automation detail page's **Run History** tab with a status: * **created**: the workspace was created on the target device (a run's success state) * **creating**: the handoff is in flight * **missed**: no device was online to take the run. It isn't retried * **failed**: the handoff broke. The error shows inline under the run, selectable for copying The schedule advances to the next occurrence either way. When a run dispatches in "new workspace" mode, a fresh workspace is created from the project's repo for that run (or a fresh session workspace when the automation has no project). Open it from the run row to see the agent's work. ## Pause, Run Now, Delete [#pause-run-now-delete] From the automation's detail page (**Settings** tab): * **Pause**: flip the Active switch. Runs are kept, and each schedule row on a paused automation still shows when it *would* next run, so schedule edits are previewable. * **Run now**: dispatches immediately. The run appears under **Run History** within seconds. * **Delete**: in the ⋯ overflow menu; removes the automation and its run history. ## Retry Failed Runs [#retry-failed-runs] On the **Mine** tab, **Retry all** appears in the header when any of your automations' latest run failed, and re-dispatches all of them. The **Failed** stat card filters to failing automations. Hover a row you own for **Run now** to re-dispatch one. ## Limits [#limits] * **At-least-once delivery**: Automations may dispatch more than once in rare cases (e.g. dispatcher retries). Design prompts that are safe to re-run. * **No agent-outcome tracking**: a successful run means its workspace was created; the detail page doesn't show whether the agent's work succeeded. Open the workspace to see what happened. * **Offline hosts miss the run**: if the target device is offline when the automation fires, the run is recorded as missed and the next occurrence or event is handled normally. Keep the target device online for automations that should catch every event. * **Watch for loops**: an agent's own activity can match its trigger, for example a review comment on a PR that a "Comment added" trigger watches. Narrow the trigger with its people filter (for example, comments by specific teammates) so the agent's own activity doesn't start new runs. Slack triggers already ignore the Paradev bot's own messages and reactions. * **One prompt per automation**: Each automation has one prompt (though it can have up to 25 triggers). To run different prompts, create multiple automations. ## CLI [#cli] ```bash superset automations list superset automations create --name "Nightly audit" --rrule "FREQ=DAILY;BYHOUR=3;BYMINUTE=0" --project --prompt-file prompt.md --agent claude # Omit --project and --workspace for session mode (a session workspace per run) superset automations create --name "Scratch triage" --rrule "FREQ=DAILY;BYHOUR=8;BYMINUTE=0" --prompt "…" # Each run's workspace carries the automation's tags and groups into the matching # sidebar folders. Default tag: "automation" — runs collect in an "automation" # folder per project. --tag (repeatable) files them elsewhere; clearing the tags # in the editor opts out of grouping. superset automations create --name "Nightly audit" --rrule "FREQ=DAILY;BYHOUR=3;BYMINUTE=0" --project --prompt "…" --tag audits # Event triggers: pass the trigger set as a JSON array with --triggers or --triggers-file. # trigger-options lists the ids a provider's filters accept (channels, repos, teams, ...). superset automations trigger-options --group slack superset automations create --name "Triage #bugs" --project --prompt-file triage.md \ --triggers '[{"config":{"kind":"slack","event":"reaction_added","channels":{"mode":"list","ids":["C123"]},"emoji":{"mode":"list","ids":["bug"]},"actor":{"mode":"any"}}}]' # update --triggers replaces the whole set: include each existing trigger's id to keep it. superset automations update --session # switch an existing automation to session mode superset automations get superset automations run superset automations pause superset automations resume superset automations delete ``` --- # In-App Browser Source: https://docs.paradev.com/browser Built-in browser pane for previewing your running services ## Overview [#overview] Paradev includes a built-in browser pane so you can preview your running services without leaving the app. The in-app browser previewing a dev server ## Open a Browser Tab [#open-a-browser-tab] * Press **⌘⇧B** to open a new browser tab * Click the external link icon on any detected port in the sidebar to open it in the browser ## Navigation [#navigation] The browser pane includes a full address bar with: * Back, forward, and reload buttons * URL autocomplete based on your browsing history * Favicon display for visited sites ## Browsing History [#browsing-history] URLs you visit are saved locally and appear as autocomplete suggestions. To clear your history: 1. Click the overflow menu (⋯) in the browser toolbar 2. Select **Clear Browsing History** ## DevTools [#devtools] Open the DevTools pane alongside any browser tab to inspect and debug the page running in the browser. ## Design Mode [#design-mode] Click **Design** in the browser toolbar to arm an element picker inside the page. Click any element and a prompt card opens under it: describe the change, pick an agent, and send. The agent receives the element's DOM, computed styles, React component metadata, and a cropped screenshot along with your note, in an existing agent terminal or a fresh session. Marketplace page or the `Marketplace` link in `Settings → Appearance → Theme`. ## Ask An Agent To Customize It [#ask-an-agent-to-customize-it] After downloading the base file, you can prompt an agent with something like: ```text Customize this Paradev theme JSON to feel like a neon cyberpunk arcade. Keep the schema valid. Preserve all required ui and terminal keys. Return the full JSON file contents only. ``` Then save the returned JSON and import it in Paradev. ## Theme File Format [#theme-file-format] Paradev accepts: * A single theme object * An array of theme objects * An object with `themes: [...]` The importer supports: * `id`, `name`, `type` (`dark` or `light`) * `ui` color overrides * `terminal` color overrides * `colors` as an alias for `terminal` Missing values fall back to Paradev defaults for the selected theme type. ## Example: Single Theme [#example-single-theme] ```json { "id": "my-neon-theme", "name": "My Neon Theme", "type": "dark", "author": "You", "description": "Neon terminal and UI accents", "ui": { "background": "#12061f", "foreground": "#f7f5ff", "primary": "#39ff14", "accent": "#00e5ff", "border": "#7b2dff" }, "terminal": { "background": "#0b0314", "foreground": "#f8f2ff", "cursor": "#39ff14", "red": "#ff2b70", "green": "#39ff14", "yellow": "#ffef00", "blue": "#00b7ff", "magenta": "#ff5ecf", "cyan": "#00ffd1", "white": "#e9dcff", "black": "#18082a", "brightBlack": "#6e3ea5", "brightRed": "#ff6fa2", "brightGreen": "#7dff5a", "brightYellow": "#fff86a", "brightBlue": "#59dbff", "brightMagenta": "#ff9be8", "brightCyan": "#8dffe8", "brightWhite": "#ffffff" } } ``` ## Notes [#notes] * Theme IDs must be unique and not reserved (`system`, built-in theme IDs like `dark`/`light`). * Very large files are rejected in the desktop importer. --- # Customization Source: https://docs.paradev.com/customization Personalize Paradev to your workflow ## Notification Sounds [#notification-sounds] Get audio notifications when agents finish or terminals exit. Settings → Notifications → Choose a sound Import custom ringtone audio files (MP3, WAV, OGG, up to 20MB) from **Settings → Notifications**. Preview any imported sound and set it as your active notification. ## Project Colors [#project-colors] Color-code your projects in the sidebar for quick identification. Click the project thumbnail in project settings to open the icon picker: choose an accent color, pick a glyph, or upload a custom image. Colors set on v1 projects carry over when they're imported. The project icon and color picker ## Default Editor [#default-editor] Set which editor opens when you press ⌘O. Settings → Editor → Select Cursor, VS Code, or other ## File Open Mode [#file-open-mode] Control how files open when clicked in the file tree or changes view. Settings → Files & Editor → Opening files → File open mode * **Split pane** (default) - Opens files by splitting the current tab * **New tab** - Opens files in a new tab Preview pane reuse works in both modes. This setting only affects the fallback when no reusable pane exists. To choose what a click, Shift-click, Cmd/Ctrl-click, or Cmd/Ctrl+Shift-click does on a row in the file tree, changes list, or diff header, use **Sidebar file rows** in the same section. ## Terminal Scripts [#terminal-scripts] Save reusable terminal commands, group them into panes or tabs, and launch them from the Scripts bar or CLI. Settings → Terminal → Terminal Scripts These are separate from repository setup, run, and teardown behavior, which uses [project lifecycle scripts](/setup-teardown-scripts). See the full [Terminal Scripts guide](/terminal-scripts). ## Custom Themes [#custom-themes] Download a theme from the Marketplace, or start from a base theme JSON and customize it before importing. Settings → Appearance → Theme → Marketplace / Download Base File / Import Theme See full guide: [Custom Themes](/custom-themes) ## Settings Sync [#settings-sync] Your settings sync across devices when signed in. --- # Diff Viewer Source: https://docs.paradev.com/diff-viewer Review code changes and manage your git workflow ## Overview [#overview] Review changes, stage files, commit, and push, all from one interface. Diff Viewer ## Features [#features] * **View changes** - See modified, staged, and untracked files * **Stage/unstage** - Select files for commit * **Commit** - Write message and commit * **Push/Pull** - Sync with remote * **Create PR** - Open pull request on GitHub The Changes control sits at the top of the right sidebar beside **Pages** and **Run**. It changes with the branch: * **Before a PR, with changed files** - shows diff stats, with the ship actions (commit, push, create PR) in a chevron menu beside them * **Before a PR, no changed files** - shows the next ship action that applies as a button * **After a PR exists** - shows the PR badge. Its dropdown lists **Commit** and **Push** above the merge actions when there is something to commit or push Click the diff stats or the PR badge to open or close the Changes pane; the ship actions do not toggle it. The control is hidden while the right sidebar is closed. For PR links and what each click does, see [Pull Requests](/pull-requests#open-a-pr-from-a-workspace). ## Diff Layouts [#diff-layouts] * **Split view** - Side by side comparison * **Unified view** - Inline changes ## Text Selection [#text-selection] Select text directly in the diff and copy it from the context menu. Double-click a diff line, or right-click and choose **Edit Here**, to open the raw editor at the matching location. ## Review Tab [#review-tab] The changes sidebar has a dedicated **Review** tab for PR review comments: read, filter, and respond without leaving the app. * Resolved comments are separated from open ones so you can focus on what still needs attention * Stays in sync with GitHub, refreshing automatically after PR mutations * PR check status appears in the changes sidebar alongside the review state ## Send PR Feedback to an Agent [#send-pr-feedback-to-an-agent] To ask an agent to change specific PR lines, open **Pull requests** in the dashboard sidebar and select the PR's **Code** tab. Select the lines and send your feedback to a running agent or a new session. Posting the comment to GitHub is optional. The agent receives the file, line range, and selected side of the diff. If the PR has no linked workspace, Paradev creates a PR-checkout workspace for the new session. Inspect the revision and run the relevant tests before merging. See [Pull Requests](/pull-requests#comment-straight-to-an-agent) for the controls or [send PR feedback to your coding agent](https://superset.sh/blog/send-pr-feedback-to-your-agent) for a walkthrough. ## Focus Mode [#focus-mode] Review one file at a time with navigation controls. Toggle focus mode in the diff toolbar (target icon) to: * View a single file with minimal distraction * Navigate between files with Prev/Next buttons * Jump between sections (Against base, Commits, Staged, Unstaged) via the section dropdown * See per-section file counts and position (e.g., "2/5 in Staged") Click files in the sidebar to jump directly to them in focus mode. --- # Editor & Files Source: https://docs.paradev.com/editor File explorer, built-in editor, and cross-workspace search Each workspace has a file tree, a built-in editor, and search across workspaces. ## File Explorer [#file-explorer] Browse and manage your workspace's files from the sidebar: The file tree with git decorations * Hierarchical tree with **git decorations** showing changed files * Create, rename, delete, move, and copy files with context menus * Rename inline, and drag files or folders to move them. Open editors, including ones with unsaved edits, follow the new path * Toggle hidden files; refresh directory listings * Search files with instant results * **Material icon theme** for at-a-glance file types ## Built-in Editor [#built-in-editor] The built-in editor Ways in: * Click any file in the explorer * From a diff: double-click a line or right-click → **Edit Here** to jump to that exact spot in the raw file (see [Diff Viewer](/diff-viewer)) The editor also opens files outside the workspace, including files reached through a symlink, and saves your edits to them. Creating, deleting, moving, and copying files stay inside the workspace. For longer editing sessions, **⌘O** opens the workspace in your IDE ([IDE Integration](/use-with-ide)). ## Save and Review External Changes [#save-and-review-external-changes] Use **Save** or **⌘S** to write your edits. If an agent or script changes the file while you have unsaved edits, the editor keeps your buffer and shows an external-change banner. Click **Compare** to review the disk and local versions side by side. Saving a conflicted file opens the same review. * **Keep editing** preserves your unsaved edits without writing to disk. * **Reload from disk** replaces your buffer with the disk version. It is unavailable if the file cannot be read. * **Overwrite file** replaces the disk version with your edits. The editor does not merge simultaneous edits. ## Auto Save [#auto-save] Auto Save is off by default. Set it in **Settings → Files & Editor → Editing → Auto Save**: * **After delay (3s)**: saves 3 seconds after you stop typing * **On focus change**: saves when you leave the file's pane or the Paradev window * **On window change**: saves when the Paradev window loses focus Auto Save applies to files you edit by hand, including files in editors that are not active. It pauses for a file with a save conflict or a failed save until you resolve it. ## Markdown Links [#markdown-links] Web links in Markdown previews follow **Settings → Browser → URL links**, and links to Paradev Pages follow **Settings → Files & Editor → Page links**. By default, Shift-click opens a new tab, Cmd/Ctrl-click opens a split browser pane, and Cmd/Ctrl+Shift-click opens the system browser. A plain click keeps you editing. **⌘C** in a rendered Markdown view copies the text as you see it, without backticks or fences. To copy the Markdown source, right-click the selection and choose **Copy as Markdown**. ## Cross-Workspace Search [#cross-workspace-search] The search bar searches across all open workspaces. Cross-workspace search ## Image Viewer [#image-viewer] Images open fitted to the pane, with standard viewer navigation: * **Zoom**: pinch, or Ctrl/⌘ + scroll (anchored at the cursor, 25%–1600%) * **Pan**: two-finger scroll, or click and drag * **Keyboard**: **+**/**−** to zoom, arrow keys to pan, **0** to reset * **Reset**: double-click, or click the zoom badge that appears while zoomed ## Tabs, Splits, and Panes [#tabs-splits-and-panes] Drop a pane onto the tab strip to create a new tab; mix terminals, files, diffs, and browser panes in one layout. The browser pane keeps its state when you switch workspaces. If one pane fails to render, it shows **This pane hit an error** with **Retry** and **Close pane**. The rest of the workspace keeps working. **Close pane** also removes the pane from the saved layout, so it does not come back after a reload. --- # FAQ Source: https://docs.paradev.com/faq Frequently asked questions ## Platforms [#platforms] **What platforms are supported?** macOS (Apple Silicon and Intel) is the supported target. A Linux x64 AppImage ships with each release but is experimental and untested. Windows is planned with no date. The CLI also supports Linux x64 and arm64. **Is Paradev a terminal app?** No. It's a desktop app with a full interface. Agents run in terminals, and next to them you get the [Changes pane](/diff-viewer), [pull requests](/pull-requests) with checks and review threads, an [in-app browser](/browser) with Design Mode, and a [file editor](/editor). **Is there a mobile app or web dashboard?** Yes, [Paradev for iPhone and iPad](/install#iphone-and-ipad) is on the App Store. It needs iOS 26 or iPadOS 26 or later and Paradev Pro. Push notifications are coming. Android is not available yet; join the [Android waitlist](https://superset.sh/mobile#android). There's no supported web dashboard today. **Do I need to keep my computer on to use the mobile app?** Only for workspaces hosted on that computer. Enable Remote Access and keep the host awake and online. [Cloud workspaces](/cloud-workspaces) work on iPhone and iPad without keeping your own computer connected. **Does it work with GitLab or self-hosted remotes?** GitHub is fully supported via the `gh` CLI. Repos with other remotes work locally, but cross-machine project identity is currently tied to GitHub, so the same project can show up twice across devices. **I was looking for the Paradev hiring platform.** That's a different company (joinsuperset.com). This Paradev is a desktop app for running AI coding agents. ## Accounts and Billing [#accounts-and-billing] **I signed in and everything is gone.** GitHub and Google sign-ins create **separate accounts**, even with the same email. Sign out and back in with the provider you originally used. Also check which organization you're in: updates can land you in a different org, and its workspaces live separately. **I paid for Pro but can't find the features.** Pro features (remote access, automations, and more) live in the current v2 interface. If your app looks like the older UI, enable it under **Settings → Experimental**. **Does Paradev bill my model usage?** No. Paradev never proxies model calls. Agents use your own subscriptions and API keys, and your provider bills you directly. **How do I cancel or get a refund?** Email [support@superset.sh](mailto:support@superset.sh). Refunds are handled promptly. **How do I delete my account, change my email, or move projects between orgs?** These aren't self-serve yet; email [support@superset.sh](mailto:support@superset.sh). ## Workspaces and Git [#workspaces-and-git] **Do I need a git repo?** For projects, yes: every project must be a git repository, and its workspaces are git worktrees. For a fresh folder, run `git init && git add -A && git commit -m "init"` first. If you just want a scratch space without setting up a repo, create a [session](/workspaces#sessions) instead. **Is each worktree a sandbox?** No. A worktree gives each task its own working files and branch. Agents still run on the same machine, so they share processes, the network, and files outside the worktree. Worktrees also don't prevent merge conflicts. **Same branch in multiple workspaces?** No. One branch = one workspace. Create a new branch if needed. **Where are workspaces stored on disk?** `~/.superset/worktrees/`, as ordinary git worktrees (sessions live at `~/.superset/sessions/`). Deleting a workspace removes its worktree; Paradev never deletes worktrees behind your back. **I already have worktrees from another tool.** Use the **Import** tab in the New Workspace modal to bring existing worktrees in. See [Workspaces](/workspaces). **Why did my branch get a random name like `interesting-forest`?** Branch names are generated from your prompt by a small model. When no usable model credential is available, naming falls back to random words; check your connected models in Settings. **Does deleting a workspace touch my repo?** It removes that worktree and runs your [lifecycle teardown scripts](/setup-teardown-scripts). Your root checkout and other branches are untouched. ## Agents [#agents] **Which agents are supported?** See [AI Agents](/agent-integration) for the full list. If an installed agent doesn't appear in launchers, check it's **Enabled** under **Settings → Agents**. **Where do I set the model or reasoning effort an agent launches with?** Under **Settings → Agents**, per agent. Preset-level tweaks don't override the agent's own launch settings. **Why did Paradev add hooks to my agent configs?** Paradev installs lifecycle hooks and command wrappers (in `~/.superset/bin`) so it can show agent status and send finished/waiting notifications. Removing them disables those features. **Do sessions survive restarts?** Yes. Terminals are backed by a background daemon, so running processes and scrollback survive app restarts and updates. ## Remote and Automations [#remote-and-automations] **Why does my host show offline when the machine is up?** "Online" means connected to the Paradev relay, not "the process is running." Remote access via relay is **off by default**; enable it under **Settings → Remote Access** (or run `superset start --daemon` on CLI hosts). See [Remote Access](/remote-access). The local CLI works regardless of relay state. **Can I open a remote host's ports on my Mac?** Yes. The desktop app forwards detected ports for the selected remote workspace to your machine. If a local port is busy, choose **Use another port**. See [Remote Access](/remote-access#ports-on-a-remote-host) for requirements. **Why did my automation run fail while my machine was asleep?** Runs fail when the target device isn't relay-connected at fire time. Use **Retry all** once it's back. See [Troubleshooting](/troubleshooting#automation-run-failed-while-the-device-was-offline). ## Privacy [#privacy] **Does my code leave my machine?** Local workspace files live on their host machine. Enabling Remote Access sends workspace traffic through the relay; cloud workspaces run your code in the cloud, and publishing a Page uploads its content. Agents also send prompts and context to the model providers you configure. **Does it modify git config?** No. Paradev uses standard git commands. ## CLI [#cli] **`superset projects list` / `workspaces list` shows nothing, but I have projects.** The CLI works against the v2 local-first model only. If you're on the legacy v1 interface, the CLI won't see those projects; enable v2 under **Settings → Experimental**. ## Getting Help [#getting-help] * [Troubleshooting](/troubleshooting) for symptom-by-symptom fixes * Discord for the fastest answers * Report issues: {`${SOCIAL.GITHUB.handle}/issues`} * Email: {COMPANY.SUPPORT_EMAIL} * All channels: [Community & Support](/community) --- # Your First Parallel Session Source: https://docs.paradev.com/first-workspace Go from install to three agents working in parallel, then ship the best result In about ten minutes you'll add a repo, put three agents to work on isolated branches, and merge the winner. ## 1. Add a Repository [#1-add-a-repository] Add your repo from a local folder or clone a remote repository. In the clone dialog, search the GitHub repositories available to the selected host's GitHub CLI login, then pick one to fill in the URL and project name. You can also paste a Git URL manually. Check GitHub access with `gh auth status` on that host. Add Repository ## 2. Create a Workspace with a Prompt [#2-create-a-workspace-with-a-prompt] Press **⌘N** to create an isolated git worktree on its own branch. In the prompt-first flow, describe the task, pick an agent, and create. The agent starts working on your prompt immediately. A good first prompt if your repo needs dependencies or env files: ```text Set up this project for Paradev. Read docs.superset.sh/setup-teardown-scripts and docs.superset.sh/ports, then author a .superset/config.json for this repo. ``` Future workspaces will then install dependencies and copy env files automatically via [project lifecycle scripts](/setup-teardown-scripts). Creating a workspace from a prompt ## 3. Fan Out to Three Agents [#3-fan-out-to-three-agents] Press **⌘N** twice more and give each workspace the same prompt with a different agent, say Claude Code, Codex, and Amp: ```text Find a small bug in this repo and fix it. Explain the bug and the fix in your final message. ``` ## 4. Watch Them Work [#4-watch-them-work] * The sidebar shows each workspace's status at a glance * Agents pause in the chat pane when they need input, tool approval, or plan review * Enable notification sounds in Settings to hear when an agent finishes instead of babysitting terminals ## 5. Review in the Diff Viewer [#5-review-in-the-diff-viewer] Open each workspace's **Changes** tab to see exactly what its agent did. Diff Viewer * Toggle split or unified view * Use focus mode (target icon) to step through files one at a time * Double-click a line or choose **Edit Here** to fix small things yourself ## 6. Ship the Winner [#6-ship-the-winner] In the workspace with the best result: stage, commit, push, and **Create PR**, all from the diff viewer. If a losing attempt had one good idea, select those lines in its diff and copy them over before you clean up. ## 7. Clean Up [#7-clean-up] Delete the other workspaces. [Lifecycle teardown scripts](/setup-teardown-scripts) run automatically, and the worktrees are removed. ## You Now Know the Core Loop [#you-now-know-the-core-loop] Try these workflows next: The pattern you just ran, refined. Feature + bugfix + PR review in parallel. An agent addresses review comments while you move on. Split large changes into independent slices. Scheduled agent runs with Automations. --- # Paradev Documentation Source: https://docs.paradev.com/ Run AI coding agents in parallel, each in its own isolated workspace Paradev gives every task its own isolated git worktree, so you can delegate to many agents at once and integrate the results through ordinary branches and PRs. The Paradev home screen: describe a task, pick an agent, go ## Start Here [#start-here] The 60-second version. Requirements and first launch. Two minutes. Three agents in parallel, ship the winner. Ten minutes. The five concepts everything else builds on. ## What You Can Do [#what-you-can-do] Same prompt, multiple agents, isolated branches. Merge the best diff. A feature, a bugfix, and a PR review at once, without branch juggling. Stage, commit, push, and open PRs from the built-in diff viewer. Start agent sessions on a schedule or an event; open a reviewable workspace. Claude Code, Codex, Amp, Gemini, and more, or the built-in chat. Reach workspaces hosted on another machine through the relay. ## Build On It [#build-on-it] Drive projects, workspaces, and automations from the command line. Programmatic access to everything the CLI can do. Let agents drive Paradev itself over MCP. ## Help [#help] Stuck? Check [Troubleshooting](/troubleshooting) and the [FAQ](/faq), or [open an issue](https://github.com/paradevai/paradev/issues). --- # Install Source: https://docs.paradev.com/install Requirements, download, and first launch ## Requirements [#requirements] * **macOS**, Apple Silicon or Intel. A Linux x64 AppImage ships with each release but is experimental; Windows is not yet available. * **Git** installed * **GitHub CLI** for the PR workflows: optional, and Paradev offers to install it during onboarding. Run `gh auth status` to check. * At least one coding agent you already use (Claude Code, Codex, Amp, ...). Paradev launches agents; it doesn't replace your subscriptions. ## Download [#download] On an Intel Mac? [Download Superset-x64.dmg](https://github.com/paradevai/paradev/releases/latest/download/Superset-x64.dmg) instead. ## First Launch [#first-launch] Onboarding checks your prerequisites with live detection: install or sign in to anything missing and the checklist updates on its own. 1. **GitHub CLI**: install it if needed, then sign in. You can run `gh auth login` right inside the app. 2. **Agents**: Paradev detects Claude Code and Codex automatically. Everything else is configurable later under **Settings → Agents**. 3. **Add a project**: point Paradev at a local folder or a Git URL. Using Bedrock, Vertex, OpenRouter, or another provider? See [Providers](/providers). Paid organizations also get a **Get the best out of Pro** sidebar checklist for Remote Access, mobile, and automations. Reopen it from **Help → Get the best out of Pro** if you dismissed it. ## iPhone and iPad [#iphone-and-ipad] [Download Paradev for iPhone and iPad](https://apps.apple.com/app/id6788926383) to continue your agents away from your desk. You need **iOS 26 or iPadOS 26 or later** and **Paradev Pro**. Enable **Remote Access** to reach agents on your computer. You can also use [cloud workspaces](/workspaces#cloud-workspaces) without keeping your own computer connected. For workspaces on your own computer, keep that host awake and online. Follow [mobile setup](/remote-access#connect-from-an-iphone-or-ipad) to connect your computer, then see [Mobile App](/mobile) for what you can do in the app. Android is not available yet; join the [Android waitlist](https://superset.sh/mobile#android). ## Staying Updated [#staying-updated] Paradev checks for updates automatically. New releases ship daily; the [changelog](https://superset.sh/changelog) rounds up each week's highlights. ## Next [#next] You're two minutes in; the next ten are the fun part: [Your First Parallel Session](/first-workspace). --- # Keep Agents Running Source: https://docs.paradev.com/keep-agents-running What keeps running when you close or quit Paradev, and how to keep agents reachable while you're away ## Overview [#overview] Agents in Paradev run in terminals that belong to a background terminal daemon, not to the app window. Closing the window, quitting the app, or installing an update does not stop them. When you open Paradev again, each terminal reattaches with its scrollback. What changes when the app is not running is **reachability**: other devices, the mobile app, and automations reach a machine through its host service, and the desktop app starts and stops that service. ## What Happens When You… [#what-happens-when-you] | You do this | Agents keep running? | Reachable from other devices and automations? | | ----------------------------------------------------- | ----------------------------- | --------------------------------------------- | | Close the last window (macOS) | Yes | Yes. The app is still running | | Quit with **⌘Q** or **Close Paradev** in the menu bar | Yes | No, until you open Paradev again | | Install an update | Yes | Yes, after the app restarts | | **Quit Paradev Completely** in the menu bar | No. All terminal sessions end | No | | Restart or log out of the computer | No | No | After a restart, you can often pick up an interrupted agent where it left off. See [Agent Sessions](/agent-sessions). ## Keep a Machine Reachable While You're Away [#keep-a-machine-reachable-while-youre-away] The desktop app starts its own host service and stops it when you quit. To keep a machine reachable from your phone, and by automations, while the desktop app is closed, run the host service from the standalone CLI instead: 1. Install the standalone CLI. The CLI that comes with the desktop app depends on the app, so it can't keep the host running after you quit. ```bash curl -fsSL https://superset.sh/cli/install.sh | sh ``` 2. Quit the Paradev desktop app. While the app is running, the host belongs to it, and `superset start` only reports that a host is already running. 3. Sign in and start the host service: ```bash superset auth login superset start --daemon ``` 4. Run `superset status` and check that the host is running before you leave. The CLI host picks up terminals that are already running and stays registered with the relay. On a dedicated machine, such as a Mac mini or a Linux server, this is the recommended setup. See [Getting Started](/cli/getting-started), [Host Server](/cli/host-server), and [Remote Access](/remote-access). Keep the machine awake and online. A machine that sleeps or loses its network connection shows as offline until it comes back. ## Stop Everything [#stop-everything] * **Quit Paradev Completely** in the menu bar stops the host service and ends every terminal session. * On a CLI host, `superset stop` stops the host server but leaves terminals running; `superset stop --terminals` ends them too. ## FAQ [#faq] ### Do agents stop when I close my laptop? [#do-agents-stop-when-i-close-my-laptop] They pause while the computer sleeps, like any other process, and continue when it wakes. To keep agents working while your laptop is closed, run them on another machine you add as a host. See [Remote Access](/remote-access). ### Why does my Mac show as offline in the mobile app after I quit Paradev? [#why-does-my-mac-show-as-offline-in-the-mobile-app-after-i-quit-paradev] Quitting the desktop app stops its host service, which is what the relay talks to. Your agents are still running. Open Paradev again, or start the host service from the standalone CLI as described above, and the machine comes back online. --- # Keyboard Shortcuts Source: https://docs.paradev.com/keyboard-shortcuts Customize hotkeys for common actions ## Workspace [#workspace] | Action | Shortcut | | ----------------------- | -------- | | New Workspace | ⌘N | | Quick Create Workspace | ⌘⇧N | | Add Project from Folder | ⌘⇧O | | Switch to Workspace 1-9 | ⌘1-9 | | Previous Workspace | ⌘⌥↑ | | Next Workspace | ⌘⌥↓ | | Open in Editor | ⌘O | | Copy Path | ⌘⇧C | Previous and Next Workspace follow the sidebar order (Pinned, then Sessions, then Projects) and wrap around at the ends. ## Layout [#layout] | Action | Shortcut | | ------------------------- | -------- | | Toggle Changes Tab | ⌘L | | Open Diff Viewer | ⌘⇧G | | Toggle Workspaces Sidebar | ⌘B | | Split Right | ⌘D | | Split Down | ⌘⇧D | | Split Along Longer Side | ⌘E | | Close Pane | ⌘W | | Quick Open File | ⌘P | | Focus Task Search | ⌘⇧F | | New Browser Tab | ⌘⇧B | **Toggle Workspaces Sidebar** collapses the sidebar to a narrow rail and expands it again. ## Chat [#chat] | Action | Shortcut | | ----------------------- | -------- | | Find in Chat | ⌘F | | Focus Chat Input | ⌘J | | Undo Closing a Chat Tab | ⌘Z | ## Terminal [#terminal] | Action | Shortcut | | ------------------------ | -------- | | New Tab | ⌘T | | Close Tab | ⌘⇧W | | Close Terminal | ⌘W | | Clear Terminal | ⌘K | | Find in Terminal | ⌘F | | Scroll to Bottom | ⌘⇧↓ | | Previous Tab | ⌘⌥← | | Next Tab | ⌘⌥→ | | Open Terminal Script 1-9 | ⌃1-9 | ## Window [#window] | Action | Shortcut | | ----------------------- | -------- | | Close Window | ⌘⇧Q | | Show Keyboard Shortcuts | ⌘/ | | Open Command Palette | ⌘⇧K | | Check Resources | ⌘⇧U | ## Customize [#customize] Open Settings → Keyboard Shortcuts to rebind or disable any hotkey. **Reset** next to a shortcut restores its default. --- # Paradev MCP Server Source: https://docs.paradev.com/mcp-server Connect AI agents directly to Paradev via MCP The Paradev MCP server lives at `https://api.superset.sh/mcp`. The versioned URL (`/api/v2/agent/mcp`) keeps working for existing configurations; the legacy v1 server (`/api/agent/mcp`) has been removed and returns `410 Gone`. ## Overview [#overview] Paradev provides an [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that lets AI agents interact with your tasks, workspaces, and devices programmatically. ## Capabilities [#capabilities] | Category | Operations | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | **Tasks** | list, get (by id or slug), create, update, delete, list statuses | | **Workspaces** | list (per host), create on a host, update, delete | | **Agents** | list agents on a host, launch an agent session in a workspace | | **Terminals** | create in a workspace, list, send input, read screen, close | | **Pages** | list, get, list versions, pull content, publish, read storage; list/reply/resolve page comments | | **Automations** | list, get metadata, get/set prompt body, create, update metadata and triggers, list trigger options, pause, resume, run on demand, list runs, delete | | **Projects** | list projects on a host | | **Hosts** | list hosts (registered machines) you have access to | | **Organization** | list members | ## Setup [#setup] ### CLI Options [#cli-options] ```bash title="terminal" claude mcp add superset --transport http https://api.superset.sh/mcp ``` ```bash title="terminal" codex mcp add superset --url https://api.superset.sh/mcp ``` ```bash title="terminal" gemini mcp add --transport http superset https://api.superset.sh/mcp ``` Run `opencode mcp add` and follow the interactive prompts: ```ansi title="terminal" opencode mcp add [2m┌[0m Add MCP server [2m│[0m [2m◇[0m Location [2m│[0m [36mCurrent project[0m [2m│[0m [2m◇[0m Enter MCP server name [2m│[0m [36msuperset[0m [2m│[0m [2m◇[0m Select MCP server type [2m│[0m [36mRemote[0m [2m│[0m [2m◇[0m Enter MCP server URL [2m│[0m [36mhttps://api.superset.sh/mcp[0m [2m│[0m [2m◇[0m Does this server require OAuth authentication? [2m│[0m [36mYes[0m [2m│[0m [2m◇[0m Do you have a pre-registered client ID? [2m│[0m [36mNo[0m [2m│[0m [2m└[0m [32mMCP server added successfully[0m ``` ```bash title="terminal" amp mcp add --workspace superset https://api.superset.sh/mcp ``` Add to your `.vibe/config.toml`: ```toml title=".vibe/config.toml" [[mcp_servers]] name = "superset" transport = "http" url = "https://api.superset.sh/mcp" ``` Run `kimi`, enter `/mcp-config`, and add an HTTP server named `superset` with this URL: ```text title="Kimi Code" https://api.superset.sh/mcp ``` Then enter `/mcp-config login superset` to authorize it. Run `grok`, enter `/mcps`, and add an HTTP server named `superset` with this URL: ```text title="Grok" https://api.superset.sh/mcp ``` ### Manual Configuration [#manual-configuration] Alternatively, you can manually configure the MCP server for each client: Add a `.mcp.json` to your project root. Claude Code auto-discovers this file and handles OAuth authentication. ```json title=".mcp.json" { "mcpServers": { "superset": { "type": "http", "url": "https://api.superset.sh/mcp" } } } ``` Add to your `claude_desktop_config.json`: ```json title="claude_desktop_config.json" { "mcpServers": { "superset": { "type": "http", "url": "https://api.superset.sh/mcp" } } } ``` Add to `.cursor/mcp.json` in your project root: ```json title=".cursor/mcp.json" { "mcpServers": { "superset": { "url": "https://api.superset.sh/mcp" } } } ``` Add to your `~/.codex/config.toml`: ```toml title="config.toml" [mcp_servers.superset] url = "https://api.superset.sh/mcp" ``` Add to your `.gemini/settings.json`: ```json title="settings.json" { "mcpServers": { "superset": { "httpUrl": "https://api.superset.sh/mcp" } } } ``` Add to your `opencode.json`: ```json title="opencode.json" { "$schema": "https://opencode.ai/config.json", "mcp": { "superset": { "type": "remote", "url": "https://api.superset.sh/mcp" } } } ``` Add to `.amp/settings.json` in your project root: ```json title=".amp/settings.json" { "amp.mcpServers": { "superset": { "url": "https://api.superset.sh/mcp" } } } ``` Add to `.vibe/config.toml` in your project root (or `~/.vibe/config.toml` for global config): ```toml title=".vibe/config.toml" [[mcp_servers]] name = "superset" transport = "http" url = "https://api.superset.sh/mcp" ``` Add to `.kimi-code/mcp.json` in your project root (or `~/.kimi-code/mcp.json` for global config): ```json title=".kimi-code/mcp.json" { "mcpServers": { "superset": { "url": "https://api.superset.sh/mcp" } } } ``` Then enter `/mcp-config login superset` in Kimi Code to authorize it. Add to your `~/.grok/config.toml`: ```toml title="~/.grok/config.toml" [mcp_servers.superset] url = "https://api.superset.sh/mcp" ``` ## Authentication [#authentication] The MCP server uses OAuth 2.1. When you first connect, you'll be prompted to authorize the connection in your browser. The token is scoped to your active organization. ### API Key Authentication [#api-key-authentication] For headless environments, CI/CD pipelines, or scripts where browser-based OAuth isn't practical, you can authenticate with an API key instead. **Generating an API key:** 1. Open the Paradev desktop app 2. Go to **Settings > API Keys** 3. Click **Create API Key** 4. Copy the key (it starts with `sk_live_`). You won't be able to see it again. **Using the API key:** Pass the API key as a Bearer token in the `Authorization` header: ``` Authorization: Bearer sk_live_your_api_key_here ``` MCP clients that support custom headers can use this directly. For Claude Code, set the header in your `.mcp.json`: ```json { "mcpServers": { "superset": { "type": "http", "url": "https://api.superset.sh/mcp", "headers": { "Authorization": "Bearer sk_live_your_api_key_here" } } } } ``` API keys grant full access to your organization. Keep them secret and never commit them to version control. Use environment variables or secrets managers for CI/CD. **When to use which method:** | Method | Best for | | --------- | ---------------------------------------------------- | | OAuth 2.1 | Interactive use: Claude Desktop, Claude Code, Cursor | | API Key | Headless/CI: scripts, automation, pipelines | ## Available Tools [#available-tools] ### Tasks [#tasks] | Tool | Description | | --------------------- | ---------------------------------------------------------------------------------- | | `tasks_list` | List tasks with optional filters (status, priority, assignee, free-text search) | | `tasks_get` | Get one task by UUID or slug | | `tasks_create` | Create a task in the active organization | | `tasks_update` | Update fields on an existing task | | `tasks_delete` | Soft-delete a task by UUID | | `tasks_statuses_list` | List the organization's task statuses (for `tasks_create`/`tasks_update` statusId) | ### Workspaces [#workspaces] | Tool | Description | | ------------------- | ---------------------------------------------------------------------------------------------------- | | `workspaces_list` | List workspaces on a host (get the hostId from `hosts_list`) | | `workspaces_create` | Create a workspace on a host, optionally launching agents with per-launch model and effort overrides | | `workspaces_update` | Update fields on a workspace on its host | | `workspaces_delete` | Delete a workspace by UUID on its host | ### Agents [#agents] | Tool | Description | | --------------- | ------------------------------------------------------------------------------------ | | `agents_list` | List agents configured on a host | | `agents_create` | Create (launch) an agent session with optional per-launch model and effort overrides | ### Terminals [#terminals] | Tool | Description | | ------------------ | ------------------------------------------------------------------------------ | | `terminals_create` | Create a terminal session in a workspace, optionally running a command | | `terminals_list` | List terminal sessions in a workspace | | `terminals_send` | Write text into a running terminal (presses Enter by default) | | `terminals_read` | Read the terminal screen as plain text (current screen plus recent scrollback) | | `terminals_close` | Close a terminal session and kill its process | ### Pages [#pages] [Paradev Pages](/pages) lets agents present designs and reports to your team and act on feedback left directly on the page. The MCP publish tool accepts a self-contained HTML document and returns a shareable URL. Every publish creates a new version; nothing is overwritten. | Tool | Description | | ------------------------ | --------------------------------------------------------------------------------- | | `pages_list` | Search and paginate pages, optionally scoped to one workspace | | `pages_get` | Get one page's metadata by id or slug (title, visibility, URL, served version) | | `pages_versions` | List a page's version history, newest first | | `pages_pull` | Get a download URL for a page's HTML, plus that version's metadata | | `pages_storage` | Read what viewers stored on a page, by key, scope or per person | | `pages_storage_set` | Write a value under a key in a page's storage, as you | | `pages_storage_remove` | Remove a value under a key in a page's storage, as you | | `pages_publish` | Publish an HTML document (passed inline, not as a path) and get its shareable URL | | `pages_comments_list` | List comment threads on a page, with replies and resolved state | | `pages_comments_reply` | Post a reply into a comment thread | | `pages_comments_resolve` | Mark a comment thread resolved, or reopen it | `pages_list` returns `{ items, nextCursor }`, ordered newest-created first. Pass `search` to match title, slug, or description, `limit` for 1–200 rows (default 50), and the returned `nextCursor` as `cursor` to continue. Keep fetching until `nextCursor` is null. `scope` accepts `all` (default), `team` for shared pages, or `mine` for your private pages. `pages_publish` accepts `visibility: "just_me"`, `"org"` (the default for new pages), or `"everyone"` for anonymous read-only access. Pass `workspaceId` and `entryPath` together to link the page to a workspace. Both are optional; outside a workspace, save the returned `id` and pass it as `pageId` when publishing updates. Otherwise each publish creates a separate page. ### Automations [#automations] | Tool | Description | | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `automations_list` | List automations the calling user owns | | `automations_get` | Get one automation's metadata (prompt body omitted) | | `automations_get_prompt` | Fetch the full markdown prompt for one automation | | `automations_create` | Create an automation that runs on an RFC 5545 RRULE schedule, on event triggers, or both | | `automations_update` | Update an automation (name, schedule, triggers, agent, host); `triggers` replaces the whole set. Use `automations_set_prompt` to change the prompt | | `automations_set_prompt` | Replace the full markdown prompt body | | `automations_pause` | Pause an automation (its schedules and event triggers stop firing) | | `automations_resume` | Resume a paused automation | | `automations_run` | Dispatch an automation immediately, without waiting for a schedule or event | | `automations_trigger_options` | List the values an event trigger can filter on (channels, repositories, teams, ...) | | `automations_logs` | List recent runs for an automation | | `automations_delete` | Delete an automation | ### Projects [#projects] | Tool | Description | | --------------- | ------------------------------------------------------------------------------ | | `projects_list` | List projects (checked-out repos) on a host (get the hostId from `hosts_list`) | ### Hosts [#hosts] | Tool | Description | | ------------ | ------------------------------------------------------- | | `hosts_list` | List the hosts (registered machines) you have access to | ### Organization [#organization] | Tool | Description | | --------------------------- | --------------------------------------- | | `organization_members_list` | List members of the active organization | ## Chat Integration [#chat-integration] In the built-in chat panel, use the `/mcp` slash command to see your workspace's configured MCP servers: their names, transport type (local/remote), and current state (enabled/disabled/invalid). This reads from your workspace MCP config (`.mastracode/mcp.json`, `.amp/settings.json`, or `.mcp.json`). ## Example Usage [#example-usage] Once connected, you can ask your AI agent to: * "Create a task for fixing the login bug" * "List all my assigned tasks" * "Create a workspace for the auth feature on my MacBook" * "Schedule a daily automation that triages new Linear issues at 9 a.m." * "Pause the nightly cleanup automation" * "Show me the last 10 runs of my Linear triage automation" * "Answer the two threads handed to me on the launch-plan page" --- # Mobile App Source: https://docs.paradev.com/mobile Start agents, answer them, and review their changes from your iPhone or iPad Paradev for iPhone and iPad opens the same workspaces you use on your computer. Your agents keep running on that computer. From your phone, you can start new agents, answer the ones that need you, and review what they changed. [Download Paradev for iPhone and iPad](https://apps.apple.com/app/id6788926383). You need **iOS 26 or iPadOS 26 or later** and **Paradev Pro**. Android is not available yet; join the [Android waitlist](https://superset.sh/mobile#android). ## Connect Your Computer [#connect-your-computer] 1. On your computer, turn on **Remote Access** in **Settings → Remote Access**. 2. On your iPhone or iPad, sign in with the same Paradev account and select the same organization. 3. Keep the computer awake, online, and running Paradev. For details, see [Connect from an iPhone or iPad](/remote-access#connect-from-an-iphone-or-ipad). ## Home [#home] The mobile Home screen, with the Mac machine picker, the Last updated sort, workspaces grouped under a project, and the What do you want to do? composer Home lists the workspaces on one machine, grouped by project. * **Machine:** tap the machine name to switch to another computer. The dot beside the name shows whether that machine is online. * **Sort:** sort by **Last updated** or **Date created**. * **Search:** tap the search button to find a workspace by name. Each row shows the workspace name, its branch, the lines added and removed, and the agents and terminals open in it. A dot on the row's icon tells you what needs attention: | Dot | Meaning | | :----- | :-------------------------------------------------- | | Yellow | An agent needs your permission. | | Red | An agent run failed. | | Green | An agent finished, and its work is ready to review. | Touch and hold a workspace to **Pin**, **Rename**, **Share**, **Archive**, **Mark as Read**, **Copy ID**, or **Delete** it. ## Start an Agent [#start-an-agent] Type a prompt in **What do you want to do?** at the bottom of Home. Before you send it, you can choose the project, the base branch, the agent, and the model or effort, and attach files or photos. Sending the prompt creates a workspace on the selected machine and starts the agent in it. To start a workspace in a specific project, tap **+** beside the project name. ## Work in a Workspace [#work-in-a-workspace] Open a workspace to follow its sessions live. To answer an agent or send the next prompt, type it, dictate it, or attach a photo. Use the session tabs in the composer to switch sessions or start another one in the same workspace. An agent session on iPhone, showing the agent's messages and the steps it ran, a prompt from the user, and the composer while the agent works ## Review Changes [#review-changes] 1. Open the changed files to read syntax-highlighted diffs, one file at a time. 2. Touch and hold a line to add a comment. 3. Tap **Finish review**, write a summary if you want one, and choose where to send it: an open agent session, or **New agent session**. 4. Tap **Send review**. The agent gets your comments and the summary. ## Pull Requests [#pull-requests] When a workspace has a pull request, its icon on Home shows the pull request state. Open the pull request to see its checks, reviews, and comments. You can: * Merge it with **Squash & Merge**, **Create Merge Commit**, or **Rebase & Merge**. * Hand the next step to an agent in the workspace: **Fix Checks with Agent** when checks fail or the branch has conflicts, or **Address Comments with Agent** when reviewers left comments. ## Pages [#pages] Open [Pages](/pages) from the app to read pages your team publishes. Tap anything on a page to comment on it, reply to threads, and resolve them. ## Settings [#settings] In **Settings**, you can: * See which of your machines are online under **Hosts**. * Switch organization. * Manage your plan on the web. * Get help, contact support, or sign out. ## Troubleshooting [#troubleshooting] If your computer shows as offline in the app, see [Why does my Mac show as offline in the mobile app after I quit Paradev?](/keep-agents-running#why-does-my-mac-show-as-offline-in-the-mobile-app-after-i-quit-superset) and [Remote Host Won’t Connect](/troubleshooting#remote-host-wont-connect). --- # Multiple Windows Source: https://docs.paradev.com/multiple-windows Keep several workspaces or organizations on screen at once Open more than one Paradev window to watch several workspaces at the same time, or to put two organizations side by side. ## Open a New Window [#open-a-new-window] * **File → New Window** (**Ctrl+Alt+N** on Linux) * **New window** in the organization menu * **New window** in the command palette (**⌘⇧K**) * On Linux, **New Window** in the launcher or dock menu for Paradev. An AppImage shows it only when it is integrated with your desktop. A new window uses the same organization as the window you opened it from, and opens on the page you visited last in any window. ## Switch and Close Windows [#switch-and-close-windows] Each window's title is the name of its organization. On macOS, the **Window** menu lists the open windows by that name. To close the focused window, use **Window → Close** (**⌘⇧Q**) or **File → Close Window**. ## What Each Window Has [#what-each-window-has] Each window has its own: * **Page and workspace** - each window navigates on its own * **Organization** - switching organization in one window doesn't change any other window * **Active tab and focused pane** * **Size, position, and zoom level** All windows share: * **Settings**, including theme and keyboard shortcuts * **Workspaces, terminals, and agents** - they run on the host, so closing a window doesn't stop them * **Sidebar projects and sections, and each workspace's tabs and panes**, for windows on the same organization The organization you switch to last is also the default for a window that opens without one, such as the window macOS opens when you click the Dock icon with no windows open. Clicking a desktop notification brings the window you used last to the front, and every open window navigates to that notification's workspace. ## Same Workspace in Two Windows [#same-workspace-in-two-windows] You can open one workspace in two windows. Its tabs and panes stay in sync: a tab you open, close, or split in one window appears in the other. The selection stays local, so switching tabs or focusing a pane in one window doesn't move the other. If the other window closes your active tab, your window moves to the nearest remaining tab. ## Restore on Relaunch [#restore-on-relaunch] When you quit, Paradev saves every open window with its position, size, zoom level, and organization. On the next launch, each window opens again on its organization. Restored windows all open on the same page, the one you visited last before you quit, not on the pages they each showed. Closing a window without quitting removes it from the saved set. On macOS, closing the last window keeps Paradev running, and the next launch opens one window. On Linux, closing the last window quits Paradev, and that window comes back on the next launch. --- # Agent Orchestration Source: https://docs.paradev.com/orchestration Turn the agent you're already talking to into a coordinator of other agents the fan-out is mechanical: many similar slices, clear acceptance criteria, and results a coordinator can verify against tests. For work you want to review step by step, use the [parallel workstreams recipe](/recipes/parallel-workstreams). The `superset:orchestrate` skill lets one agent coordinate workers in separate workspaces through the Paradev CLI. Agents working in parallel workspaces The coordinator can be Claude Code or Codex; the workers can be any mix of agents Paradev runs. ## Install [#install] The desktop app includes this skill. For standalone agents, see [Skills installation](/skills#installation). ## What to Ask For [#what-to-ask-for] * **Fan out a refactor or migration** across several worktrees at once ("split this migration into independent slices and run a worker on each") * **Hand a branch from one agent to another** with its full terminal context * **Dispatch to a remote host** and monitor until every worker reports done or blocked ## How It Works [#how-it-works] Under the hood the coordinator uses the [Paradev CLI](/cli/getting-started): * `superset workspaces create` for an isolated branch per worker * `superset agents create` to launch a worker with a bounded prompt * `superset terminals read` / `send` to monitor progress and deliver follow-ups or dependency results Workers finish by reporting a structured completion or blocked message, which the coordinator verifies before integrating. You review the results the same way as always: one branch and PR per worker. Related: [Automations](/automations) for runs on a schedule or an event, and the [MCP server](/mcp-server) for agents that drive Paradev over MCP instead of the CLI. --- # What is Paradev? Source: https://docs.paradev.com/overview The 60-second version Paradev is a source-available platform for running AI coding agents in parallel, licensed under the Elastic License 2.0. It's available as a desktop IDE, an [iPhone and iPad app](/install#iphone-and-ipad), a command-line interface, and an MCP server. The core move: every task gets its own **workspace**, an isolated git worktree on its own branch. Agents work in workspaces, so three agents (or ten) can run at once without overwriting each other's files or your `main`. If two agents edit the same lines, you resolve that at merge time, like any branch. You review each result in a built-in diff viewer and integrate through ordinary branches and PRs. ## Who It's For [#who-its-for] * You use Claude Code, Codex, Amp, or another CLI agent and keep hitting the one-branch-at-a-time wall * You're juggling a feature, a bugfix, and a PR review, and every switch means stash-checkout-rebuild * You want scheduled agents doing maintenance while you sleep Paradev is local-first: it works offline and syncs when connected. Your code never leaves your machine unless you say so. ## What Makes It Different [#what-makes-it-different] * **Worktree isolation, handled for you**: no manual `git worktree` bookkeeping, no stashing, no checkout whiplash * **Any agent**: Claude Code, Codex, Amp, Gemini, OpenCode, Cursor Agent, and [more](/agent-integration), or the built-in chat * **The whole loop in one place**: terminals, diffs, commits, PRs, ports, and dev servers per workspace * **Automations**: agent sessions that start on a schedule or when something happens (a review request, a Sentry issue, a Slack message, a webhook), with a real workspace as the output * **[Pages](/pages)**: share agent-created designs and reports with your team, and have an agent act on comments directly ## Next Steps [#next-steps] Requirements and first launch. Two minutes. The ten-minute tutorial: three agents in parallel, ship the winner. The five concepts everything else builds on. Named workflows: race agents, fan out a refactor, wake up to an audit. --- # Pages Source: https://docs.paradev.com/pages Share agent-created designs and reports with your team, and turn comments into updates Paradev Pages gives your agents a way to present designs, reports, and analysis to your team. Teammates comment directly on the page, and an agent picks up the feedback, makes changes, and publishes an updated version. A Paradev Page presenting a cloud signup design review, with a comment pinned to the headline ## The Design Loop [#the-design-loop] 1. **Create.** Ask an agent to build a design doc, report, or proposal and publish it as a Page. 2. **Share.** Send the page's link to your team. 3. **Comment.** Teammates pin feedback to the part of the page they want to discuss. 4. **Iterate.** The agent watching the page receives new comments, updates the source, republishes, and replies to the threads it addressed. ## Create Your First Page [#create-your-first-page] Open the **Pages** tab and click **Create with AI**. Paradev starts an agent session that asks what you want to create, helps build the page, and publishes a link for your team. The help icon beside the **Pages** title opens this guide. You can also ask an agent in an existing Paradev workspace: ```text Create a design doc for our onboarding flow and publish it as a Paradev Page so the team can review it and leave comments. ``` Or start with work the agent has already done: ```text Turn your findings into a report and publish it as a Page for the team. ``` The Paradev plugin includes a [Pages skill](/skills) that guides agents through building, publishing, and updating pages. A page can be a self-contained HTML file or a directory with an `index.html` and supporting assets. When an agent finishes work that someone else will read, such as a PR walkthrough, a comparison, or a report, the agent offers to publish it as a page and waits for your answer. To publish from the CLI, run: ```bash superset pages publish design.html --title "Onboarding design" --label "First draft" ``` The command returns a shareable URL. Publishing does not open the page or move the desktop to another workspace. See the [CLI reference](/cli/cli-reference#pages) for options. ## Find Workspace Pages [#find-workspace-pages] Open the Pages menu beside **Run**, above **Files / Changes / Review**. It lists pages published from the workspace, your pinned pages, and **All pages**. Choose **New page**, enter a request, and pick an agent to create it. A blue **New** indicator marks a fresh publish until you close the menu. The main Pages list shows linked workspace names so you can see where a page came from. Clicking a page there does not switch workspaces. Web links inside a workspace Page follow **Settings → Browser → URL links**, and links to other Pages follow **Settings → Files & Editor → Page links**. Both open outside the Page pane. If no plain-click action is set, a plain click opens a pane. Links in standalone Pages in the desktop app open in the system browser. ## Share a Page [#share-a-page] Use **Share** to choose who can open the page: * **Only you**: a private draft. * **Anyone in your organization**: members of your organization. This is the default for new pages. * **Anyone with the link**: anyone can read it without signing in. Public access does not grant comment or edit permissions, or access to the rest of the version history. When a page is public, the **Share** button shows a globe icon. **Shared version** controls whether the link follows the latest publish or stays on a specific version. Anonymous readers can access only that shared version. For a new page, the CLI accepts `--visibility just_me`, `--visibility org`, or `--visibility everyone`. Republishing preserves visibility unless you explicitly change it. Shared links include the page thumbnail in link previews, including [Slack unfurls](/use-with-slack). Anyone viewing a public page can use **Report** to flag it to the Paradev team with a reason, optional details, and an optional email. The Paradev team reviews reports and can take a page down, which stops its link working. ## Send Feedback Directly to an Agent [#send-feedback-directly-to-an-agent] Open the page, enter comment mode, and click an element to pin feedback to it. The agent receives the comment along with context identifying the element, so teammates can point to exactly what they want changed. On iPhone, the comments sheet keeps replies inline. Tap **Reply** to target a thread, or clear the reply target to leave a page-level comment. Resolved threads appear under the resolved-comments disclosure. Publishing from an agent's Paradev terminal attempts to register that session for new comments. Check the command's watch status; a failed registration does not fail the publish. In the workspace page pane, open the **Listening agents** menu in the page header: * It lists every agent watching the page, including agents on other devices. Click a row to open that agent's terminal. * The page's creator can click the **X** on a row to stop that agent watching. * The page's creator can use **Add listening agent** to assign a running agent in the workspace, or start a new agent session and assign it. Keep the host and agent session running for automatic feedback delivery. If the menu says **No listening agents**, the page's creator can add one. New comments are delivered when the agent is available to handle them. The agent can change the page, answer a question in the thread, or leave feedback open when it needs more discussion. When it makes a change, it republishes the page, replies with what changed, and resolves the feedback it addressed. A pinned comment asking for a white cloud icon, the agent's reply confirming the update in version 4, and a follow-up being drafted ## Keep Iterating on the Same Page [#keep-iterating-on-the-same-page] Publish the same source path from the same workspace to create a new version of the existing page. Your team keeps using the same link, and earlier versions remain in version history. ```bash superset pages publish design.html --label "Simplified onboarding after team review" ``` If the source moved or you're publishing from another workspace, pass the existing page ID explicitly: ```bash superset pages publish design.html --page --label "Updated onboarding flow" ``` Publishing from outside a workspace works too, but there's no path for a later publish to resolve against: every run creates a separate page unless you pass `--page`. The publish tells you when that happened and prints the command to reuse. Use the page title menu to preview earlier versions read-only, rename the page, or refresh it. You can also inspect version history or retrieve a published version: ```bash superset pages versions superset pages pull --version 1 > original-design.html ``` ## Read What Viewers Stored [#read-what-viewers-stored] A page can keep values under each key with `window.superset.storage`. Each call takes an optional `{ scope }`: | Scope | What it holds | | ---------------- | --------------------------------------------------------------------------------------------- | | `slot` (default) | One value per person. Everyone can read all of them. Good for votes and RSVPs. | | `private` | One value per person. Only that person can read it. Good for drafts and settings. | | `shared` | One value per key for the whole page. Any member of the page's organization can overwrite it. | To find keys, `list` returns the keys in one scope that start with a prefix, sorted by key: ```js const keys = await window.superset.storage.list("pipeline:", { scope: "shared" }); // [{ key: "pipeline:1", records: 1, updatedAt: "2026-10-12T09:30:00.000Z" }] ``` A page can store up to 20 MiB in total. You can read what viewers stored: ```bash superset pages storage superset pages storage --key votes ``` The first command lists each key and how many people stored a value under it. With `--key`, it prints each person's value and when they last changed it. With `--scope private`, you see only your own value. Add `--scope` to pick `slot`, `private` or `shared`. Add `--json` for the raw records. On a `just_me` page only the creator can read storage. On an `org` or `everyone` page, members of the page's organization can read it, even when the page is public. You can also write storage as yourself, for example to refresh data from an automation without a new publish. Both `--set` and `--remove` need `--key`, and `--set` takes a JSON value: ```bash superset pages storage --key data --scope shared --set '{"deals": 42}' superset pages storage --key data --scope shared --remove ``` Only signed-in members of the page's organization can write storage, and on a `just_me` page only the creator can. Anyone who can write can overwrite or remove a `shared` value. Someone outside the organization who opens an `everyone` page can read the page, but not its storage. Reading storage and writing it both need membership in the page's organization. ## Show Live Data from Your Tools [#show-live-data-from-your-tools] A page can call a tool from a plugin, such as a read-only database query or a web search, and show the result. The call runs as the person viewing the page, through their own connected account. The page itself makes no network request; Paradev makes the call. ```js const tools = window.superset?.tools; if (await tools?.ready) { const result = await tools.call("neon", "run_sql", { sql: "select count(*) from organizations", }); } ``` * **Consent.** The first time a page calls a plugin, the viewer sees a dialog and chooses whether to allow it. The choice applies to that page and that plugin, for every tool of the plugin, including tools that change data, and for future versions of the page. The viewer may also be asked to install the plugin, connect an account, or choose which account to use. * **Trust.** A page can send what it reads to other websites, for example in an image URL. Only allow pages you trust. * **Their data.** Each viewer sees results from their own account, so two people can see different numbers. A signed-out viewer cannot use tools. * **Databases and search.** The `neon` plugin runs SQL against the viewer's Neon database, writes included, so only run read queries from a page. The `exa` plugin gives a page Exa's search tools. * **Errors.** A call fails with a code in `error.code`: `needs_install`, `needs_connection`, `denied`, `unavailable_signed_out`, `rate_limited`, `invalid`, `tool_error` or `unavailable`. A tool that fails returns `tool_error` with the tool's message. A call times out after 60 seconds. Time the viewer spends in the dialog does not count. * **Not on mobile.** Tools work in the desktop app and on the web, not in the mobile app. Removing a page's tool access from the app is not available yet. Agents connecting through MCP can publish, retrieve versions, read a page's storage, and reply to or resolve comments with the [Pages tools](/mcp-server#pages). --- # Port Management Source: https://docs.paradev.com/ports View and manage active ports per workspace ## Overview [#overview] Paradev does not assign per-workspace port ranges. It discovers listening ports from processes running in each workspace and lets you manage them from the UI. Port Panel ## Features [#features] * **View active ports** - See which processes are using which ports * **Kill processes** - Stop a process by clicking its port * **Workspace grouping** - Ports are grouped by the workspace that owns the process * **Terminal focus** - Select a port to jump back to the terminal that owns it * **Browser actions** - Open local web servers in the in-app browser or externally from the port action ## Port Labels [#port-labels] Label detected ports by creating `.superset/ports.json` in your repository: ```json { "ports": [ { "port": 3000, "label": "Frontend Dev Server" }, { "port": 8080, "label": "API Server" }, { "port": 5432, "label": "PostgreSQL" } ] } ``` **Fields:** * `port` - Port number (1-65535) * `label` - Display text shown in tooltip **Behavior:** * Labels apply only to ports detected as listening * Ports without a matching label still appear * Each workspace reads labels from its own worktree's file * Changes are detected automatically * Ports can be opened at `localhost:PORT` from the browser action (remote workspace ports are [forwarded to your machine](#remote-access) first) **Error Handling:** If `ports.json` is malformed, detected ports still appear without labels until you fix the file. **Tips:** * Commit `.superset/ports.json` to share port labels with your team * **Pro tip:** If you want deterministic per-workspace port ranges, implement it in project lifecycle setup/teardown scripts by reserving a range in a shared file (for example `~/.superset/port-allocations.json`) during setup and releasing it during teardown. See this repo's examples: [`.superset/setup.sh`](https://github.com/paradevai/paradev/blob/main/.superset/setup.sh) and [`.superset/teardown.sh`](https://github.com/paradevai/paradev/blob/main/.superset/teardown.sh). ## Remote Access [#remote-access] The desktop app forwards detected ports from the selected remote workspace to your machine. If a local port is busy, choose **Use another port** from its row. See [remote port forwarding](/remote-access#ports-on-a-remote-host) for requirements and behavior, or forward a port yourself below. ### Forward a port yourself [#forward-a-port-yourself] **SSH**: forward the port, then open `http://localhost:3000` locally: ```bash ssh -N -L 3000:localhost:3000 user@remote-host ``` **[Tailscale](https://tailscale.com)**: on the host, expose the port to your tailnet and open the URL it prints: ```bash tailscale serve 3000 ``` Both work for servers that only listen on loopback. If the server binds `0.0.0.0`, you can skip the tunnel and hit the host's Tailscale name directly (`http://remote-host:3000`). ## Discovery and Updates [#discovery-and-updates] The port list updates as workspace processes start and stop listening. --- # Use with OpenRouter, Bedrock, Vertex, or Vercel Source: https://docs.paradev.com/providers Connect Paradev to Vercel AI Gateway, OpenRouter, AWS Bedrock, Google Vertex, and other providers If you're using Paradev in the terminal - any CLI agent (Claude Code, Codex, Curser Agents, etc.) automatically just work. That's the beauty of us being terminal first. For the Chat UI, we have a flow for users to get started. ## Chat UI [#chat-ui] 1. Open the model picker at the bottom of the chat Model picker 2. Click the **key icon** next to **Anthropic** 3. Select **Use API key** Connect Anthropic 4. Enter the environment variables for your provider (one per line, `VAR_NAME=value` format) Environment variables 5. Click **Save settings** See the provider sections below for the specific variables to use. ## Terminal [#terminal] Set environment variables in your shell profile or per workspace via **Settings > Env**. For Anthropic-compatible providers (OpenRouter, Vercel AI Gateway), set `ANTHROPIC_API_KEY` to an empty string to prevent direct Anthropic authentication. *** ## Vercel AI Gateway [#vercel-ai-gateway] Route requests through the [Vercel AI Gateway](https://vercel.com/docs/ai-gateway). ```bash ANTHROPIC_BASE_URL=https://ai-gateway.vercel.sh ANTHROPIC_AUTH_TOKEN=your-vercel-ai-gateway-api-key ANTHROPIC_API_KEY= ``` ## OpenRouter [#openrouter] [OpenRouter](https://openrouter.ai) provides access to many models through a single API. ```bash ANTHROPIC_BASE_URL=https://openrouter.ai/api ANTHROPIC_AUTH_TOKEN=your-openrouter-api-key ANTHROPIC_API_KEY= ``` ## AWS Bedrock [#aws-bedrock] Use Claude models through your AWS account with [Amazon Bedrock](https://aws.amazon.com/bedrock/). Ensure your AWS credentials are configured via `aws configure`, environment variables, or SSO profile. ```bash CLAUDE_CODE_USE_BEDROCK=1 AWS_REGION=us-east-1 ``` Optionally override the region for the small/fast model (Haiku): ```bash ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION=us-west-2 ``` Pin specific model versions to prevent breakage when new models are released: ```bash ANTHROPIC_DEFAULT_OPUS_MODEL=us.anthropic.claude-opus-4-6-v1 ANTHROPIC_DEFAULT_SONNET_MODEL=us.anthropic.claude-sonnet-4-6 ANTHROPIC_DEFAULT_HAIKU_MODEL=us.anthropic.claude-haiku-4-5-20251001-v1:0 ``` For full setup details including IAM configuration, see the [Claude Code on Amazon Bedrock docs](https://code.claude.com/docs/en/amazon-bedrock). ## Google Vertex AI [#google-vertex-ai] Run Claude models on [Google Cloud Vertex AI](https://cloud.google.com/vertex-ai). Authenticate with `gcloud auth application-default login`, then set: ```bash CLAUDE_CODE_USE_VERTEX=1 CLOUD_ML_REGION=global ANTHROPIC_VERTEX_PROJECT_ID=your-project-id ``` Pin specific model versions to prevent breakage when new models are released: ```bash ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-6 ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6 ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5@20251001 ``` For full setup details including IAM configuration, see the [Claude Code on Google Vertex AI docs](https://code.claude.com/docs/en/google-vertex-ai). ## Microsoft Foundry (Azure) [#microsoft-foundry-azure] Use Claude models via [Microsoft Foundry](https://ai.azure.com). Authenticate with an API key or Microsoft Entra ID (`az login`), then set: ```bash CLAUDE_CODE_USE_FOUNDRY=1 ANTHROPIC_FOUNDRY_RESOURCE=your-resource-name # If using API key authentication: ANTHROPIC_FOUNDRY_API_KEY=your-azure-api-key ``` Pin specific model versions to prevent breakage when new models are released: ```bash ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-6 ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6 ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5 ``` For full setup details including RBAC configuration, see the [Claude Code on Microsoft Foundry docs](https://code.claude.com/docs/en/microsoft-foundry). ## Other Anthropic-Compatible Providers [#other-anthropic-compatible-providers] Any provider that exposes an Anthropic-compatible API (such as LiteLLM) can be used: ```bash ANTHROPIC_BASE_URL=https://your-provider.example.com ANTHROPIC_AUTH_TOKEN=your-api-key ANTHROPIC_API_KEY= ``` For LLM gateway configuration details, see the [Claude Code LLM gateway docs](https://code.claude.com/docs/en/llm-gateway). --- # Pull Requests Source: https://docs.paradev.com/pull-requests Review, check, and merge PRs from your projects without leaving the app Open **Pull requests** in the dashboard sidebar to review PRs from your projects' GitHub repositories. The resizable split view shows the PR list on the left and the selected PR's description, checks, and diff on the right. The Pull requests split view: filterable list on the left, detail with rendered markdown on the right ## Browse and Filter [#browse-and-filter] The list shows every PR from the repositories behind your projects. Each row carries the repo, PR number, title, author, a compact CI check summary (passed/total), age, and the +added/−deleted line counts. * **State tabs**: **All**, **Open**, or **Merged** * **Repository**: multi-select across your projects' repos * **Author**: filter to a specific GitHub author * **Reviews**: review-status filter: *No reviews*, *Review required*, *Approved review*, *Changes requested*, *Reviewed by you*, *Not reviewed by you*, *Awaiting review from you*, or *Awaiting review from you or your team* * **Search**: find PRs by title or number Filters persist, so the view comes back the way you left it. Active filters show a count badge next to the search box. ## The Detail View [#the-detail-view] Selecting a PR opens it in the right pane, with **Summary** and **Code** tabs. Toggles at either end of the header collapse the list or the detail pane when you want more room; on narrow windows the panes stack automatically. ### Summary [#summary] The Summary tab shows the PR description alongside: * **Checks**: every CI check with its status and a link to the run on GitHub. The header summarizes the state at a glance ("All 12 passed"). Cancelled checks count as failures, not successes. * Review status and reviewers for the PR. Each reviewer links to their GitHub profile * **Activity**: comments, reviews, review threads, and commits in one stream, oldest first, with a composer for replying * **Pages**: in a workspace's PR pane, up to three pages the workspace's agents published, with a link to view all Review threads show one card per thread, with its replies inside. Resolved and outdated threads fold to their header; click the header to unfold one. Each card keeps copy, resolve or unresolve, reply, and open-in-diff actions. PR checks alongside the summary, with Start Workspace and Merge actions in the header ### Code [#code] The **Code** tab is a complete diff viewer: a file tree with per-file added/deleted counts and modified/renamed markers, syntax-highlighted diffs, collapsed unmodified regions, and unified or side-by-side layouts. A **Files** dropdown jumps to any file in the changeset. The Code tab: file tree plus syntax-highlighted diffs ### Comment Straight to an Agent [#comment-straight-to-an-agent] Select lines in the Code tab and send a comment to an agent, optionally posting it on GitHub too. The agent receives the file, line range, and diff side: * If a workspace is already linked to the PR, send it to one of its **running agent terminals**, or start a **new agent session** there * If no workspace exists yet, Paradev **creates a PR-checkout workspace** and launches the agent with your comment as its first prompt ## Actions [#actions] From the detail header: * **Start Workspace** - check out the PR into a new workspace to run, test, or continue it. See [Workspaces](/workspaces) * **Merge** - choose **Squash and merge** (combine all commits), **Merge commit** (preserve commit history), or **Rebase and merge** (reapply all commits) * **Close** / reopen the PR * Open the PR on GitHub Merging, closing, and commenting act on the real PR through your GitHub connection - same permissions, same effects as doing it on github.com. ### Open a PR from a Workspace [#open-a-pr-from-a-workspace] PR links in a workspace open the PR pane or GitHub, depending on the click. This covers the **Open PR** button in the Diff pane, the PR title in the sidebar **Review** tab, **Open pull request** in the PR status menu, and the PR icon on a sidebar row. * **Click** - opens the PR pane in a split beside the active pane * **Shift-click** - opens it in a new tab * **⌘-click** or **Ctrl-click** - opens the PR on GitHub in your browser ## Where PRs Come From [#where-prs-come-from] Connect GitHub under project settings to sync PRs. Linked workspaces also show [PR status](/workspaces#pr-status) in the sidebar. For a review workflow, see the [PR feedback recipe](/recipes/pr-feedback). --- # Remote Access Source: https://docs.paradev.com/remote-access Reach workspaces hosted on another machine ## Overview [#overview] A workspace lives on the machine that hosts its files, terminal, and ports. **Remote access** lets you reach a workspace that's hosted on a different machine, like a Mac mini under your desk, a sandbox your team shares, or a spare laptop in the office. **Paradev Relay** is a service that provides a secure way to route traffic between your different devices. There are two ways to grant a device remote access through the relay: ## Option 1: Desktop [#option-1-desktop] Exposing your primary workstation through the relay means anything reachable by your local host service (files, terminals, agent runs) becomes reachable by clients you grant access to. The recommended setup is a **separate machine** provisioned with only the repos and credentials you intend to share. That way a misclick or compromised client can't wipe an unrelated project or leak unrelated secrets. Use the desktop toggle when you genuinely need it on this machine. Otherwise prefer the CLI path on a dedicated host. Open the desktop app and go to **Settings → Remote Access**. Flip on **Allow remote access to this device via relay**. Settings → Remote Access relay toggle Enabling the toggle restarts the host service, so any running terminals on this device will be interrupted. You'll be asked to type a confirmation phrase before the change applies. ## Option 2: CLI [#option-2-cli] See the CLI's [Getting Started](/cli/getting-started) and [Host Server](/cli/host-server) docs to get set up. On the machine you want to add to your shared relay network, sign in and start the host server. ```bash superset auth login superset start --daemon ``` `superset start --daemon` runs a small HTTP server in the background and registers the machine with the relay so other clients in your organization can find it. Verify it's online: ```bash superset status ``` ### Headless (sandbox, CI, or server) [#headless-sandbox-ci-or-server] On a machine with no browser to complete an interactive login, authenticate with an API key instead. Create one in **Settings → API Keys**, then export it. The CLI reads `SUPERSET_API_KEY` automatically (no `superset auth login` needed): ```bash export SUPERSET_API_KEY=sk_live_… superset start --daemon --org ``` Pass `--org` to choose which organization the host registers under. It's required when your key belongs to more than one organization (the CLI won't guess); with a single organization you can omit it. The host claims itself to the key's user on first registration. No desktop step required. Observe or manage it from the same headless environment. Every `hosts`/`status` command takes the same `--org`: ```bash superset hosts list --org superset status --org ``` ## Set Up a Host Over SSH [#set-up-a-host-over-ssh] In the desktop app, open **Settings → Hosts** and choose **Set up a host over SSH**. Enter the SSH destination (`user@box` or a Host alias). The dialog runs [`superset hosts add`](/cli/cli-reference) in an embedded terminal, so password, host-key, and install prompts work as in any terminal. When it finishes, the new host appears in the list. If it fails, edit the destination and retry. ## Connect from an iPhone or iPad [#connect-from-an-iphone-or-ipad] Install [Paradev for iPhone and iPad](/install#iphone-and-ipad) and check its requirements before connecting. You can use [cloud workspaces](/cloud-workspaces) without connecting your own computer. To connect to workspaces hosted on your own computer: 1. On your computer, enable **Allow remote access to this device via relay** in **Settings → Remote Access**. You can also use the inline toggle in **Settings → Mobile** when that tab is available. Both toggles control the same setting. 2. On your iPhone or iPad, sign in with the same Paradev account and select the same organization. The QR code in desktop Mobile settings opens the App Store; it does not sign you in. 3. Select your computer and open a workspace to continue its terminal sessions, send prompts, review diffs, or merge PRs. Keep the computer awake, online, and running Paradev. If your computer does not appear online, see [Remote Host Won’t Connect](/troubleshooting#remote-host-wont-connect). ## Grant teammates access [#grant-teammates-access] When a host first comes online, the user who started it is the only one with access. Other members of your organization won't see it in their workspaces list until you add them. Open **Settings → Hosts** in the desktop app, pick the host, and use **Add member** to grant teammates access. Owners can promote members to owner or remove them from the host. Settings → Hosts members table ## Reach a remote host from another device [#reach-a-remote-host-from-another-device] On any other device signed into the same organization, open the desktop app's **Workspaces** list. Use the **Device** filter in the top right to pick a remote host: * **This device**: workspaces on the machine you're using now * **Other devices**: each remote host that has opted in, listed by name with an online indicator Device filter in the workspaces list Pick a remote host to see the workspaces hosted there. Open one and you get the full Paradev experience (terminals, agent runs, the diff viewer) proxied through the relay to the host machine. ### Ports on a remote host [#ports-on-a-remote-host] The ports sidebar shows ports listening **on the remote host**. When you select a remote workspace, the desktop app forwards each of its ports to the same port number on your machine, so `localhost:3000` reaches the dev server on the host. All traffic for a workspace shares one tunnel, established when you select the workspace; every connection reuses it. When you select another workspace, the app stops those forwards and starts the new workspace's forwards. Only ports that the workspace started are forwarded. Other services on the host stay unreachable. If a local process already uses the port, the row shows **local port busy** and offers two actions: stop the local process (only when a Paradev workspace started it) or **Use another port**, which maps the remote port to a free local port and shows the mapping, for example `3000 → localhost:54321`. The remote server sees each forwarded connection as coming from its own loopback address; there is no real client IP. Only TCP is carried; anything UDP (WebRTC media, mDNS) does not ride the forward. Forwarding needs a host on the current relay running host-service 1.26 or newer. For a host you reach some other way, [forward a port yourself](/ports#forward-a-port-yourself) with SSH or Tailscale. Forwarded traffic passes through the Paradev relay, like terminal traffic does. A browser talking to a forwarded dev server sends whatever it normally would (cookies, auth headers, query strings), so treat a forwarded port like the remote service it reaches, not like localhost. ## Turning access off [#turning-access-off] * **Desktop**: flip the toggle in **Settings → Remote Access** back off. The host service restarts and stops accepting relay traffic. * **CLI**: run `superset stop` on the host machine. In both cases, in-flight terminals and host-backed work on that machine are interrupted. --- # Project Lifecycle Scripts Source: https://docs.paradev.com/setup-teardown-scripts Configure setup, teardown, and Run-button commands for a project ## Overview [#overview] Run commands automatically when creating or deleting workspaces, and define dev server commands that launch via the Run button. These are **project lifecycle scripts**: project-owned behavior stored in the repository or a per-machine override. They are different from [terminal scripts](/terminal-scripts), which are reusable launches saved in your Paradev settings and shown in the Scripts bar. Create `.superset/config.json` in your project: ```json { "setup": ["bun install", "cp \"$SUPERSET_ROOT_PATH/.env\" .env"], "teardown": ["docker-compose down"], "run": ["./.superset/run.sh"] } ``` ## How It Works [#how-it-works] 1. Create workspace → **setup** commands run in a terminal 2. Delete workspace → **teardown** commands run 3. Click the **Run** button → **run** commands execute in a dedicated pane Setup and teardown commands run sequentially in the workspace directory. By default, an agent launched at workspace creation starts immediately, in parallel with setup. Enable **Settings → Experimental → Wait for workspace setup before starting agents** to chain the agent after the setup commands in the same terminal: the agent only starts once setup succeeds, and no separate setup pane is left behind. ## Run Script [#run-script] The `run` field defines commands that start your dev server or other long-running processes. Unlike setup/teardown, run commands are: * **On-demand**: triggered by the Run button, not automatically on workspace creation * **Restartable**: stop and restart from the UI without recreating the workspace * **Dedicated pane**: runs in its own terminal pane separate from your shell ```json { "setup": ["npm install"], "run": ["./.superset/run.sh"] } ``` ## Environment Variables [#environment-variables] | Variable | Description | | ------------------------- | ------------------------------ | | `SUPERSET_ROOT_PATH` | Path to root repository | | `SUPERSET_WORKSPACE_NAME` | Current workspace name | | `SUPERSET_WORKSPACE_PATH` | Path to the workspace worktree | ## Examples [#examples] **Node.js:** ```json { "setup": ["bun install", "cp \"$SUPERSET_ROOT_PATH/.env\" .env"] } ``` **Docker:** ```json { "setup": ["docker-compose up -d", "bun run db:migrate"], "teardown": ["docker-compose down -v"] } ``` **Full config:** ```json { "setup": ["./.superset/setup.sh"], "teardown": ["./.superset/teardown.sh"], "run": ["./.superset/run.sh"] } ``` ## User Overrides [#user-overrides] Override project scripts without modifying the repo by placing a `config.json` in your home directory, mirroring the repo's absolute path: ``` ~/.superset/projects//config.json ``` For a repo at `/Users/me/work/app`, that's `~/.superset/projects/Users/me/work/app/config.json`. The legacy location keyed by project ID (`~/.superset/projects//config.json`) still works as a fallback. ### Priority Order [#priority-order] For each key (`setup`, `teardown`, `run`), the highest-priority source that defines it wins: 1. `~/.superset/projects//config.json`: user override 2. `/.superset/config.json`: workspace-specific (setup and teardown only) 3. `/.superset/config.json`: project default Levels merge per key: a key one level doesn't define falls through to the next. `run` resolves at the project level, so it skips the worktree layer. ### Script Fallback [#script-fallback] If no commands are configured for a key, Paradev looks for a script instead: `.superset/.sh` (`setup.sh`, `teardown.sh`, `run.sh`) in the worktree first, then the main repo. A gitignored script isn't checked out into new worktrees, so it typically exists only in the main repo. ### Working Directory [#working-directory] Set `cwd` to run commands somewhere other than the workspace root. Relative paths resolve against the worktree: ```json { "cwd": "apps/web", "run": ["bun dev"] } ``` ### Examples [#examples-1] **Custom setup script:** ```json { "setup": ["~/.superset/projects//setup.sh"], "teardown": ["~/.superset/projects//teardown.sh"] } ``` **Skip setup entirely:** ```json { "setup": [], "teardown": [] } ``` ## Local Config [#local-config] Extend or override your team's committed scripts without modifying the repo. Create `.superset/config.local.json` alongside `config.json`. It's gitignored automatically. ### Prepend and/or append [#prepend-andor-append] Add steps before or after the team's scripts: ```json { "setup": { "before": ["echo 'running pre-setup'"], "after": ["./.superset/my-post-setup.sh"] }, "teardown": { "after": ["./.superset/my-cleanup.sh"] } } ``` Result: `before` → committed setup scripts → `after`. Keys you don't specify pass through unchanged. ### Override entirely [#override-entirely] Use a plain array to replace the team's scripts completely: ```json { "setup": ["./.superset/my-custom-setup.sh"] } ``` ### Mix and match [#mix-and-match] Override one key while extending the other: ```json { "setup": { "after": ["bun run my-extra-step"] }, "teardown": ["my-custom-teardown.sh"] } ``` ### Resolution order [#resolution-order] The local config merges on top of whichever base config wins the [priority order](#priority-order). If a `config.local.json` exists in both the worktree and main repo, the worktree's local config takes priority. ## Force Delete [#force-delete] If teardown scripts fail during workspace deletion, you can force-delete to skip the failed teardown and continue cleanup. When teardown fails: 1. Error toast appears with "Delete Anyway" and "View Logs" buttons 2. Click "Delete Anyway" to force-delete immediately 3. Or click "View Logs" to review the failure, then force-delete from the dialog Deleting a workspace through the CLI, SDK, or MCP also runs teardown. Since there's no one to prompt on those surfaces, a teardown failure doesn't block the delete; it's reported in the response's `warnings` instead. ## Tips [#tips] * Keep setup fast: it runs on every workspace creation * Commit `.superset/` to share with team * Use shell scripts for complex logic: `"setup": ["./.superset/setup.sh"]` * Use `config.local.json` to add personal steps without touching the team's config * Use user overrides (`~/.superset/projects/`) to replace scripts entirely per-project * Use `run` for dev servers instead of putting them in `setup`: run scripts are restartable and don't block workspace creation --- # Skills Source: https://docs.paradev.com/skills Paradev abilities your coding agents get automatically. Orchestration, automations, feedback, diagnostics, and more Skills teach the coding agents you already use how to drive Paradev: orchestrate parallel agents, create automations, diagnose problems, and more. ## Installation [#installation] **Using the Paradev desktop app?** Skills are already installed. The app provisions them at launch and keeps them updated. Otherwise, install them directly: ```bash npx skills add paradevai/skills ``` Or, in Claude Code, via the plugin marketplace: ```text /plugin marketplace add paradevai/paradev ``` ## What You Get [#what-you-get] | Skill | What it does | | :--------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `superset:setup` | Makes a repo Paradev-ready: authors `.superset/config.json` and project lifecycle scripts, then verifies with a real workspace | | `superset:orchestrate` | Turns the agent you're talking to into a coordinator of parallel agents; see [Agent Orchestration](/orchestration) | | `superset:automate` | Turns a recurring chore into an [automation](/automations) that runs on a schedule or an event, and reviews its first run with you | | `superset:page` | Builds and publishes shareable [Pages](/pages), then updates them in response to pinned team comments | | `superset:browser` | Drives a workspace's [in-app browser](/browser) panes: open, navigate, screenshot, eval, read console, and raw CDP for click/type automation, and routes to [Browser Use 3.0](/browser#browser-use-30) for browsers the panes can't reach | | `superset:computer` | Drives [native desktop apps](/computer) through an accessibility-first driver (Cua Driver by default): inspect windows, click, type, use menus, and verify results with background interaction when the platform supports it | | `superset:panes` | Arranges a workspace's tabs and split panes in the desktop app: split, open tabs, resize, swap, move, focus, and close, with commands running in the new panes; see the [`panes` CLI reference](/cli/cli-reference#panes) | | `superset:standup` | Sweeps your workspaces, tasks, and agent terminals into a digest: what needs you, what's in flight, what's blocked | | `superset:doctor` | Diagnoses Paradev problems (expired auth, offline hosts, stale versions) and fixes them one step at a time | | `superset:feedback` | Files a bug report or feature request: privately to the Paradev team (from your account, so we can reply) or as a public GitHub issue | | `superset:10x` | Audits how you use Paradev and teaches the advanced features you're not using yet | | `superset:contribute` | Sets up a Paradev open-source contribution end to end, following the repo's contribution rules | ## Using Skills [#using-skills] You usually don't invoke them; agents pick the right skill from context: * "report this bug to the superset team" → `superset:feedback` * "what did my agents do overnight?" → `superset:standup` * "run these three refactors in parallel" → `superset:orchestrate` * "open localhost:3000 and click through the signup flow" → `superset:browser` * "open the desktop app and change its settings" → `superset:computer` * "split this and run the tests on the right" → `superset:panes` To invoke one explicitly: `/superset:feedback` in Claude Code, or `/superset/feedback` in the in-app chat. Other agents that read skills (Codex, Kimi, Vibe, Grok) see the same skills with a `superset-` prefix. ## How They're Delivered [#how-theyre-delivered] At launch, the desktop app writes managed copies into the standard discovery locations: `~/.claude/skills/superset/` (loaded by Claude Code as a plugin, hence the `superset:` namespace), `~/.agents/skills/`, and `~/.agents/commands/`. * **Your files are never touched.** Managed files carry a marker; a skill or command you authored at the same path is left alone. * **Updates are automatic.** Managed skills refresh on every app launch, and ones that no longer ship are cleaned up. --- # The Paradev Model Source: https://docs.paradev.com/superset-model Five concepts everything else builds on Paradev has one mental model: **delegate in workspaces, integrate through branches and PRs**. Five concepts make it work. ## Projects [#projects] A project is a repo you've registered with Paradev, from a local folder or a Git URL. Everything else happens inside a project. A project can define [project lifecycle scripts](/setup-teardown-scripts) for setup, teardown, and Run-button behavior in `.superset/config.json` so every new workspace comes up ready to work. ## Workspaces [#workspaces] A workspace is an isolated [git worktree](/workspaces) on its own branch: its own directory, its own terminal sessions, its own ports. Only git-tracked files are copied in; lifecycle setup scripts handle the rest (dependencies, env files). Workspaces are cheap and disposable by design. Create one per task with **⌘N**, delete it when the branch merges. The workspace is where you delegate; the branch and PR are how the work comes back. Workspaces in the sidebar, each with its own branch and diff stats ## Terminals [#terminals] Every workspace gets [persistent terminals](/terminal-integration). Sessions survive app restarts: running processes continue, output history and scrollback are preserved. This is what makes it safe to have five agents running: closing the app doesn't kill their work. ## Agents [#agents] Any CLI agent runs in any workspace: Claude Code, Codex, Amp, Gemini, and [the rest](/agent-integration), plus a built-in chat. To power [status and notifications](/agent-status), Paradev wraps agent launch commands and installs lifecycle hooks into their configs. It never touches model traffic: prompts and tokens go directly from the agent CLI to your provider, on your own accounts. ## Devices [#devices] A workspace lives on the machine that hosts its files, terminals, and ports; that doesn't have to be the machine you're looking at. [Remote access](/remote-access) reaches workspaces hosted on another device (a Mac mini under the desk, a shared sandbox), and [Automations](/automations) dispatch agent runs, on a schedule or when an event comes in, to whichever device you pick. ## How They Compose [#how-they-compose] Every workflow in the [recipes](/recipes/race-agents) is these five pieces arranged differently: racing is N workspaces with the same prompt; the nightly audit is an automation dispatching to a device that creates a workspace; a fanned-out refactor is one workspace per slice, integrated as PRs. --- # Supported Agents Source: https://docs.paradev.com/supported-agents Which features Paradev supports for each built-in agent ## Overview [#overview] Every agent runs in its own workspace, with its own Git worktree and terminal, on your own subscription or API key. Paradev never proxies model calls. Beyond that, how deeply Paradev integrates depends on the agent: some report their status, resume after a restart, and show up in the Usage page; others run as plain terminal programs. ## Feature Support [#feature-support] | Agent | Status | Resumes after restart | Usage history | Quota meter | | ------------ | ------------------------------- | --------------------- | ------------- | --------------------------- | | Claude | Yes | Yes | Yes | Yes, with multiple accounts | | Codex | Yes | Yes | Yes | Yes, with multiple accounts | | OpenCode | Yes | Yes | Yes | Yes | | Grok | Yes | Yes | Yes | Yes | | Cursor Agent | Yes | Yes | Yes | No | | Copilot | Yes | Yes | Yes | No | | Devin | Yes | Yes | Yes | No | | Muse Code | Yes | Yes | Yes | No | | Pi | Yes | Yes | Yes | No | | Oh My Pi | Yes | No | Yes | No | | Droid | Yes | Yes | No | No | | Gemini | Yes | Yes | No | No | | Amp | Yes | Yes | No | No | | Kimi Code | Yes | Yes | No | No | | Mastracode | Yes | Yes | No | No | | Mistral Vibe | Partial: no "needs input" state | Yes | No | No | | UFO | Partial: launch only | No | No | No | | Antigravity | No | No | Yes | Yes | | fx | No | No | Yes | No | | Hermes | No | No | Yes | No | | Kiro | No | No | No | No | | Polygraph | No | No | No | No | * **Status** means the agent reports when it is working, needs input, or is done, which drives the sidebar indicators and notifications. See [Agent Status](/agent-status). * **Resumes after restart** means Paradev can restore the agent's session by its id after the app or machine restarts. See [Agent Sessions](/agent-sessions). * **Usage history** means the agent's token use appears on the [Usage](/usage) page. * **Quota meter** means the Usage page shows the subscription's quota windows. Only Claude and Codex support switching between several accounts. ## Subagents and Handoff [#subagents-and-handoff] * Subagents started by **Claude** and **Codex** appear under their parent session, in the terminal header's **Subagents** menu. * Moving a conversation to another agent carries a structured transcript for **Claude** and **Codex**; other agents hand over their terminal output. * **Fork session** is available for agents with fork arguments: Claude, Codex, OpenCode, Pi, Grok, and Droid. ## Models and Effort [#models-and-effort] The model picker is available for Claude, Codex, Gemini, OpenCode, Oh My Pi, Copilot, Mistral Vibe, and Cursor Agent. A reasoning-effort picker is available for Claude, Codex, Amp, Mastracode, Oh My Pi, Pi, Copilot, and Cursor Agent. See [AI Agents](/agent-integration#models-and-reasoning-effort). ## Other Agents [#other-agents] Any CLI agent runs in Paradev. Add it in **Settings → Agents → Add agent → Custom agent…**. A custom agent gets a workspace, worktree, and terminal like any built-in agent, without the integrations above. If you build an agent and want first-class support, see [Add Paradev Support to Your Agent](/add-agent-support). --- # Tasks Source: https://docs.paradev.com/tasks Track work items and delegate them to agents without leaving the app Open **Tasks** in the dashboard sidebar to browse issues and delegate them to agents. Filters persist between visits. [Pull Requests](/pull-requests) has a separate view. The Tasks view on the GitHub issues source, with per-row Add to workspace actions ## Where Tasks Come From [#where-tasks-come-from] A source toggle at the top of the view switches between: * **Linear** - issues synced from your connected workspace (see [Linear Integration](/use-with-linear)), listed alongside Paradev-native tasks you create in the app * **GitHub issues** - open issues from your projects' repositories, with a repository filter and per-row **Add to workspace** buttons The Linear source lists issues from the whole connected workspace; filter by project, status, or assignee to narrow it to yours. ## What You Can Do [#what-you-can-do] * **List and board views**: a sortable table or a kanban board grouped by status * **Filters** for project, task state, assignee, and label; empty filters mean everything * **Label hierarchy**: name a label with a path like `acme/website` and its parent labels are created for you. The **Label** filter shows labels as a tree, and filtering on `acme` also matches tasks labelled `acme/website` * **Semantic search**: find tasks by meaning, not just keywords * **Multi-select**: check several tasks and act on them together * **Create tasks** from the desktop with the **New task** modal: title, description, status, priority, and assignee Creating a task from the desktop Opening a task shows its full detail: an editable title, description, activity, and a properties sidebar for status, priority, and assignee. ## From Task to Workspace [#from-task-to-workspace] Launch an agent from a task and the task's content becomes the agent's prompt: * **Run in workspace** on a task (or a multi-selection of tasks) picks a project and an agent, then creates a workspace per task with the agent already working * The **Auto-run command** toggle controls whether each agent starts immediately or stages the command for review * The **Task Prompt Template** (per agent, under **Settings → Agents**) controls how a task is turned into the agent's prompt * On the GitHub issues source, **Add to workspace** does the same for a single issue After creating a PR, review and merge it from [Pull Requests](/pull-requests). --- # Terminal Source: https://docs.paradev.com/terminal-integration Built-in terminal with multiple tabs and persistence ## Overview [#overview] Built-in terminal per workspace with multiple tabs and session persistence. Terminal ## Multiple Tabs [#multiple-tabs] Open several terminal tabs per workspace. Each runs independently. * **⌘T** - New tab * **⌘W** - Close pane; **⌘⇧W** - Close tab * **⌘⌥1-9** - Switch tabs (⌘1-9 switches workspaces) ## Session Persistence [#session-persistence] Sessions survive app restarts: * Running processes continue * Output history preserved * Scrollback maintained If a terminal has ended, choose **New shell** to start a fresh session in the same pane. Recent output from the previous session stays visible. For agent recovery, see [Resume Interrupted Sessions](/agent-sessions#resume-interrupted-sessions). ## Pane Rename [#pane-rename] Double-click a pane title to rename it. ## Merge Tabs [#merge-tabs] Drag a tab onto another tab's split drop zone to merge the source tab's panes into that layout. The source tab closes after the merge. ## Close Warning [#close-warning] Closing a terminal with a running process asks you to confirm. If you tick **Don't ask again**, turn the warning back on with **Warn before closing a running terminal** in **Settings → Terminal**. ## Right-Click Menu [#right-click-menu] Right-click in the terminal for quick actions: * **Copy** - Copy selected text (enabled when text is selected) * **Paste** - Paste from clipboard (enabled when clipboard has content) * **Mark as Unread** - Show the unread indicator again * Split, Clear, Move to Tab, Close Copying follows Ghostty's whitespace rules: trailing spaces on each line and trailing blank lines are removed, indentation and blank lines between text are kept, and lines that wrapped only because of the pane width are joined back into one line. The same rules apply to ⌘C, copy on select, and rectangular selections. ## Copy From Agents [#copy-from-agents] Agents such as Codex and Claude Code capture the mouse, so a drag selects text inside the agent instead of the terminal: * **Drag, then ⌘C** - copies what the agent highlighted. Most agents also copy as soon as you release the mouse. * **Option-drag, then ⌘C** - makes a normal terminal selection over the agent, using Paradev's whitespace rules. On macOS, Ctrl+C stops the running program. It does not copy. ## Cmd/Ctrl-Click Links [#cmdctrl-click-links] Hold `Cmd` (macOS) or `Ctrl` and click links in terminal output: * URLs open in browser * File paths open in the built-in file viewer by default. A location such as `src/index.ts:240:7` jumps to line 240, column 7. * Links to Paradev Pages open in a Page pane when the click opens them in the app * Configure modifier keys for URLs in **Settings → Browser → URL links**, and for file, folder, and page links in **Settings → Files & Editor** ## Environment Variables [#environment-variables] | Variable | Description | | ------------------------- | ----------------------- | | `SUPERSET_ROOT_PATH` | Path to root repository | | `SUPERSET_WORKSPACE_NAME` | Current workspace name | --- # Terminal Scripts Source: https://docs.paradev.com/terminal-scripts Save and reuse commands that launch in terminals ## Overview [#overview] Terminal scripts are reusable terminal launches. Give a script a name, one or more shell commands, an optional working directory, and a launch mode; then run it from any matching workspace with one click or a keyboard shortcut. Terminal scripts are different from [project lifecycle scripts](/setup-teardown-scripts): | Type | Purpose | Stored in | | ---------------------------- | --------------------------------------------------------------- | ------------------------------------------- | | **Terminal script** | A reusable command or group of commands you launch from the app | Paradev user settings | | **Project lifecycle script** | Repository setup, teardown, or Run-button behavior | `.superset/config.json` or `.superset/*.sh` | Older versions of Paradev called terminal scripts **presets**. You may still see `preset` in old links, CLI aliases, or compatibility-oriented API and storage fields, but the product term is **terminal script**. ## What Terminal Scripts Do [#what-terminal-scripts-do] * **Launch reusable commands**: start a dev server, agent, test watcher, or any shell command * **Choose a working directory**: run from the workspace root or a path such as `apps/web` * **Group commands**: open several commands as panes, tabs, or a sequential workflow * **Target projects**: make a script available everywhere or only in selected projects * **Integrate with workspace actions**: use a script for workspace creation, new tabs, or the Run button * **Import agents**: create terminal scripts linked to configured Claude, Codex, and other agents ## Create a Terminal Script [#create-a-terminal-script] Go to **Settings → Terminal → Terminal Scripts**, then click **Add Script**. | Field | Description | | --------------- | ----------------------------------------------- | | **Name** | The label shown in Settings and the Scripts bar | | **Description** | Optional context about what the script launches | | **Commands** | One or more shell commands, one command per row | | **Applies to** | Every project or selected projects | | **Directory** | A workspace-relative path or absolute directory | | **Launch mode** | Where one or more commands open | You can also add one from a terminal: ```bash superset scripts add --name dev --command "bun run dev" ``` Repeat `--command` for a grouped script and use `--execution-mode` to control its layout: ```bash superset scripts add \ --name services \ --command "docker compose up" \ --command "bun run dev" \ --execution-mode split-pane ``` To change or remove a script from the same terminal, use its id from `superset scripts list`: ```bash superset scripts list superset scripts edit --command "gh pr view --web" superset scripts delete ``` When you are iterating on one script, `superset scripts add --upsert` replaces the script with the same name instead of adding another copy to the Scripts bar. Changes made with the CLI reach the app the next time it opens or refocuses with the same organization active, and the running app picks them up immediately. Scripts created in Settings live in the app profile only, so they do not show up in `superset scripts list`. `superset presets add` remains an alias for compatibility. See the [CLI reference](/cli/cli-reference#scripts) for every option. ## Launch Modes [#launch-modes] * **New tab**: open the command in a new terminal tab * **Split pane**: open grouped commands as parallel panes in the current tab * **New tab with split panes**: create a new tab containing parallel panes * **Sequential**: run grouped commands in order in one terminal ## Import an Agent [#import-an-agent] Use **Import agent** in Terminal settings to create a terminal script linked to an agent configuration. The script uses the agent's current command and icon; edit the underlying launch command in **Settings → Agents**. The bundled Claude and Codex configurations default to their most permissive bypass flags (for example `claude --dangerously-skip-permissions`). Review the launch command in **Settings → Agents** if you want a stricter permission mode before importing. ## Scripts Bar [#scripts-bar] The Scripts bar appears above terminal tabs and shows visible terminal scripts for one-click access. * **Show or hide a script**: use its visibility control in Terminal settings or the gear menu * **Launch**: click a script to open it in the current workspace * **Choose a target**: right-click to use the current terminal, current tab, or a new tab * **Reorder**: drag scripts to change their order * **Manage**: use the gear menu to browse scripts or open Terminal settings * **Keyboard shortcuts**: press Control+1 through Control+9 to open visible scripts 1 through 9 The bar includes a built-in **Paradev CLI** script that runs `superset --help`. Built-in scripts can be hidden and restored, but not edited or reordered. ## Workspace Actions [#workspace-actions] A terminal script can participate in three workspace actions: * **Workspace Run**: the Run button launches this script for matching projects * **Workspace creation**: launch the script when a new workspace is created * **New terminal tab**: launch the script when a terminal tab opens These are explicit per-script controls. Launching a script directly from the bar, menu, or keyboard shortcut always works regardless of its workspace-action settings. On v1 desktop builds, the global auto-apply settings (such as `autoApplyDefaultPreset`, visible in `superset settings list`) also gate auto-run behavior. If more than one Run source matches a workspace, Paradev uses the first project-targeted terminal script marked **Use as workspace run**, then the project lifecycle Run command, then the first matching global terminal script. Keep only one matching script enabled for Run when you want the choice to be unambiguous. --- # Troubleshooting Source: https://docs.paradev.com/troubleshooting Symptoms, causes, and fixes for common issues ## All My Workspaces or Projects Disappeared [#all-my-workspaces-or-projects-disappeared] Almost always a context mix-up, not data loss. Check, in order: 1. **Organization**: updates can switch your active org. Check the org switcher. 2. **Sign-in provider**: GitHub and Google logins are separate accounts even with the same email. Sign out and back in with your original provider. 3. **v1 fallback**: if the app reverted to the legacy interface, re-enable v2 under **Settings → Experimental**. Your worktrees are still on disk at `~/.superset/worktrees/` either way; Paradev only deletes them when you delete a workspace. If you created your account after using v1, update Paradev and relaunch it. Current versions import pre-account workspaces that older v2 releases could miss. ## Update Button Does Nothing [#update-button-does-nothing] If the app quits and reopens on the same version, the updater hit a known race (fixed in recent releases). Download a fresh copy from [superset.sh/download](https://superset.sh/download) once; updates work normally after that. ## gh, git, or an Agent Works in My Normal Terminal but Not in Paradev [#gh-git-or-an-agent-works-in-my-normal-terminal-but-not-in-paradev] Paradev terminals differ from Terminal.app in a few specific ways: * **PATH shims**: Paradev puts wrappers in `~/.superset/bin` (for status and notifications). If an agent misbehaves, run `which -a codex` (or `claude`) to spot duplicate installs on your PATH. * **Copied settings**: new worktrees copy files like `.claude/settings.local.json` from your root checkout. If you rotated an API key, old worktrees may still carry the stale one. * **Shell**: launch commands assume a POSIX shell. fish or nushell as your login shell breaks agent launches. * **After an update**: terminal sessions are held by a background daemon that outlives the app. If terminals stay broken after an update, quit Paradev fully and relaunch; if that doesn't clear it, reboot. ## New Workspace Is Missing Dependencies or .env [#new-workspace-is-missing-dependencies-or-env] Workspaces only copy git-tracked files, so `node_modules`, `.env`, and build artifacts don't come along. **Fix:** add [project lifecycle setup commands](/setup-teardown-scripts) to `.superset/config.json`: ```json { "setup": ["bun install", "cp \"$SUPERSET_ROOT_PATH/.env\" .env"] } ``` Or ask an agent to do it: the "Set up this project for Paradev" [sample prompt](/first-workspace#2-create-a-workspace-with-a-prompt) authors the config for you. ## Can't Add a Private Repository [#cant-add-a-private-repository] Repo access goes through the GitHub CLI. **Fix:** run `gh auth status` in a terminal. If it fails, `gh auth login` (you can run it inside Paradev), then retry. ## Can't Create a Workspace on a Branch [#cant-create-a-workspace-on-a-branch] One branch = one workspace. If the branch is already checked out in another workspace (or your root checkout), git won't allow a second worktree on it. **Fix:** open the existing workspace, or create a new branch. ## Agent Isn't Showing Up in the Launcher [#agent-isnt-showing-up-in-the-launcher] Paradev detects installed agents automatically, but each agent can be enabled or disabled. **Fix:** check **Settings → Agents**: confirm the agent is **Enabled** and its command is correct. **Reset to Defaults** restores the shipped configuration. ## Remote Host Won't Connect [#remote-host-wont-connect] The host machine must be awake, online, and connected to the relay. On the host, enable **Settings → Remote Access → Allow remote access to this device via relay** (desktop), or run `superset start --daemon` (CLI). In the mobile app: * **One step left** means the computer has never connected. Follow the Remote Access setup steps on that computer. * **Offline** with a last-seen time means it connected before. Check that it is awake, online, and running Paradev, then retry. * **Can’t check** means Paradev could not load connection status. Use **Try again**; this message does not establish that the computer is offline. See [Remote Access](/remote-access) for setup. ## Automation Run Failed While the Device Was Offline [#automation-run-failed-while-the-device-was-offline] A run whose target device isn't relay-connected at fire time records as **failed**, with the offline error shown inline under the run; the schedule advances normally. **Fix:** none needed for a one-off. Use **Retry all** in the Automations list once the device is back online, or retarget the automation to a device that stays online. See [Automations](/automations). ## Still Stuck? [#still-stuck] * Check the [FAQ](/faq) * [Open an issue](https://github.com/paradevai/paradev/issues) with steps to reproduce --- # Usage Source: https://docs.paradev.com/usage Subscription quota meters, token-cost analytics, machine resources, and multi-account switching ## Overview [#overview] The **Usage** page (gauge icon in the sidebar) tracks what your agents consume on this machine: signed-in agent accounts, their session logs, and local processes. Remote hosts aren't aggregated. A pill toggle switches between **Token usage** and **Machine resources**. The Usage page: quota meters per account and token-cost analytics ## Quota Meters [#quota-meters] The top of **Token usage** shows official subscription quota for every Claude Code and Codex login on this host, and for Grok, Antigravity, and OpenCode logins, refreshed every 5 minutes (use the refresh button to force it). Each account card shows the email, plan, and one meter per quota window, e.g. **Session (5h)** and **Weekly** for Claude, with the fill percentage and time until reset. Paradev reads quota from the providers' usage endpoints using the agent credentials stored on your host. Some plans (org-managed, education) don't expose limits. ## Multiple Accounts [#multiple-accounts] Run different agents on different subscriptions from one machine: Two Claude Code accounts with quota meters, one marked as the default * **Add account** creates a second profile. Pick a profile name and billing type, then complete Claude Code or Codex sign-in in the terminal inside the dialog. Click a login URL to open your system browser. Paradev detects a successful sign-in automatically. For a remote host, copy the shown command and run it in a terminal on that host. * **Make default** picks which account new agent launches use. When a provider has several accounts, the cards read as a radio group with the default checked. Switching reaches terminals you already have open too: a running agent keeps its account until you relaunch it. * Your setup comes along: skills, plugins, MCP servers, and settings are shared across accounts, and for Claude Code there's one conversation history: `--resume` shows the same sessions whichever account is active. * Logins, credentials, and account identity stay per account. The **…** menu on a card offers **Switch sign-in…** (re-login that profile to a different account) and, for secondary profiles, **Remove…**, which deletes that profile and its credentials, never your shared setup or history. The system-default login can't be removed. * If a sign-in expires, the card shows the exact login command to run, with click-to-copy. Under the hood, a profile is just a config dir the CLI is pointed at (`CLAUDE_CONFIG_DIR` / `CODEX_HOME`). Paradev's agent wrappers re-resolve the current default every time the agent starts in a Paradev terminal, so switching works for agents you launch by hand too, and a value you export yourself always wins. ## Token Costs [#token-costs] Below the meters, the **Token usage** chart estimates spend from the agents' local session logs, priced at API list rates. It covers Claude Code, Codex, OpenCode, Grok, Cursor Agent, Copilot, Devin, Muse Code, Pi, Oh My Pi, Antigravity, fx, and Hermes; see [Supported Agents](/supported-agents). Subscription usage isn't billed per token (the page shows **Cost to you: $0**); the estimate is what the same work would cost at API rates, plus how much caching saved. * Toggle **Cost** / **Tokens** and pick a **7d** / **30d** / **90d** range * Per-agent split; click an agent to show or hide it in the chart; click a day for that day's breakdown * **Model** table and **Workspace** bars break spend down; click a row for a per-model or per-workspace drilldown, or **All N →** for every workspace and project * Workspace drilldowns list the top sessions by cost; click one to copy its session ID for `claude --resume` ## Leaderboard History [#leaderboard-history] Joining or rejoining the leaderboard publishes available local usage history from the last 90 days, starting no earlier than July 29, 2026. Leaving deletes your published history. Rejoining restores only the history within that window that is still available in your local session logs. ## Machine Resources [#machine-resources] The **Machine resources** section is a live view (every 2 seconds) of local CPU and memory: Paradev's own usage, the system RAM split, and a process table covering the app and every workspace, grouped by project down to individual terminal panes. Click a workspace or session row to jump to it. Also reachable via **⌘⇧U** (Check Resources), the command palette, or the **Resources** menu. --- # IDE Integration Source: https://docs.paradev.com/use-with-ide Use with Cursor, VS Code, or other editors ## Open in Editor [#open-in-editor] Press **⌘O** (**Ctrl+Shift+O** on Windows and Linux), or click the open-in button in the workspace tab bar, to open the workspace in your editor. The command palette's open-in command does the same. Supported editors: * Cursor * VS Code * VS Code Insiders * Zed * Windsurf * Antigravity * Sublime Text * JetBrains IDEs (IntelliJ IDEA, WebStorm, PyCharm, and more) Open In Editor ## Configure Default Editor [#configure-default-editor] Settings → Editor → Select your preferred editor ## Window Title Tip [#window-title-tip] Show branch name in editor title bar: 1. Open VS Code/Cursor settings 2. Search `window.title` 3. Set to: `${activeRepositoryBranchName}${separator}${rootName}` This helps identify which window is which when you have multiple workspaces open. --- # Linear Integration Source: https://docs.paradev.com/use-with-linear Open Linear issues as Paradev workspaces with a custom script Linear's [custom coding tool](https://linear.app/docs/open-issues-with-custom-scripts) feature can hand an issue off to any local command. With a small wrapper script, **Work on issue → Custom script** creates a Paradev workspace for the issue (checked out on the issue's branch, with an agent already working on it) and opens it in the desktop app. To give a coding agent tools to read and update Linear issues, install the [Linear plugin](/plugins/available/linear). ## How it works [#how-it-works] Linear doesn't use a URL scheme here. It runs a local executable defined in `~/.linear/coding-tools.json` and passes issue context through `LINEAR_*` environment variables (`LINEAR_ISSUE_IDENTIFIER`, `LINEAR_ISSUE_BRANCH_NAME`, `LINEAR_PROMPT`, and others). The wrapper script chains two CLI calls: 1. `superset workspaces create`: creates a local workspace on the issue's branch and launches an agent with the issue as its prompt. 2. `superset workspaces open`: opens that workspace in the desktop app via its deep link. ## Prerequisites [#prerequisites] * The [Paradev CLI](/cli/getting-started) installed and signed in (`superset auth login`). * The Paradev desktop app installed (the script opens workspaces in it). * A project that's set up locally. Find its ID with: ```bash superset projects list ``` Copy the `id` of the project you want issues to open against. ## 1. Create the wrapper script [#1-create-the-wrapper-script] Save this as `~/.linear/open-in-superset.sh` and replace `PROJECT` with the ID from above: ```bash #!/usr/bin/env bash # Linear custom script -> open the issue as a Paradev workspace. set -euo pipefail PROJECT="" NAME="${LINEAR_ISSUE_IDENTIFIER:-linear-task}" BRANCH="${LINEAR_ISSUE_BRANCH_NAME:-$NAME}" PROMPT="${LINEAR_PROMPT:-Work on Linear issue ${NAME}.}" # Make sure the local host service is running (idempotent). superset start --daemon >/dev/null 2>&1 || true result="$( superset workspaces create \ --local \ --project "$PROJECT" \ --name "$NAME" \ --branch "$BRANCH" \ --skip-branch-prefix \ --agent claude \ --prompt "$PROMPT" \ --json )" id="$(printf '%s' "$result" | jq -r '.workspace.id')" superset workspaces open "$id" ``` Make it executable: ```bash chmod +x ~/.linear/open-in-superset.sh ``` The script depends on `superset` being on your `PATH` and `jq` being installed. If `superset` isn't on your `PATH`, use its full path (the desktop app installs a shim at `~/.superset/bin/superset`). The branch named by the issue won't exist yet. `workspaces create` forks it from the project's default branch automatically. `--skip-branch-prefix` keeps Linear's exact branch format (so Linear autolinks the branch back to the issue) even when the project has a branch prefix configured. Re-running on the same issue reuses the existing workspace instead of creating a duplicate. With the Linear integration connected, Paradev does this natively: linking an issue in the New Workspace flow (or opening a task in a workspace) uses Linear's branch name automatically and moves the issue to In Progress. The script above is for driving it from Linear's side. ## 2. Point Linear at the script [#2-point-linear-at-the-script] Create `~/.linear/coding-tools.json`: ```json { "openIssue": { "path": "/Users/you/.linear/open-in-superset.sh", "env": [ "LINEAR_ISSUE_IDENTIFIER", "LINEAR_ISSUE_BRANCH_NAME", "LINEAR_PROMPT" ] } } ``` Use the absolute path to your script (`~` is not expanded here). If Linear regenerates this file with a starter config when you enable the feature, merge the `openIssue` block back in rather than letting it overwrite your version. ## 3. Enable and run [#3-enable-and-run] 1. In Linear, open **Settings → Code & reviews → Configure coding tools** and enable **Custom script**. 2. On any issue, choose **Work on issue → Custom script**. The first time, Linear asks you to **Choose a directory**: this is the working directory passed to the script, so pick your repo. (The script above doesn't read it, but Linear requires one.) Linear runs the script, and the workspace opens in Paradev with the agent running on the issue. In any macOS file dialog, press **⌘⇧.** to reveal hidden dot-folders, or **⌘⇧G** to type a path directly. ## Customizing [#customizing] * **No agent.** To open an empty workspace on the branch without starting an agent, drop the `--agent` and `--prompt` flags (they're required together). * **A different agent.** Replace `claude` with any agent preset id (`codex`, `opencode`, …). * **Multiple repos.** The project ID is fixed in the script. To route different Linear teams or projects to different Paradev projects, branch on a `LINEAR_*` variable (for example `LINEAR_PROJECT_NAME`) and set `PROJECT` accordingly. The `env` array in `coding-tools.json` is an allowlist: any `LINEAR_*` variable you read in the script must also be added there, or it won't be present in the script's environment. --- # Slack Integration Source: https://docs.paradev.com/use-with-slack Mention @superset in Slack to file tasks or dispatch coding agents `@superset` in Slack is an agent, not just a task-filer. Mention it in a channel or DM it, describe what you want, and it acts. The Paradev Slack bot spinning up a workspace and reporting back in-thread To give a coding agent tools to read and post in Slack, install the [Slack plugin](/plugins/available/slack). ## What It Can Do [#what-it-can-do] * **Create, update, search, and triage tasks** from the conversation it's standing in, pulling assignees, statuses, and priorities from your team's Linear/Paradev setup * **Spin up a cloud workspace and launch a coding agent** to actually do the work. Code-change requests ("bump our Sentry SDK to v9 across all apps") default to spawning a workspace and agent rather than filing a ticket * **Read the thread or channel history** on its own to gather context, no copy-pasting prior messages * **Search the web with citations** when a request needs current information * **Unfurl Paradev task, workspace, and [Page](/pages) links** with rich previews ## Setup [#setup] 1. In the dashboard, go to **Integrations → Slack** 2. Click **Connect** to install the Paradev Slack app (OAuth) 3. Mention `@superset` in any channel, or DM the bot, and describe what you want done ## Page Links [#page-links] A shared [Page](/pages) link unfurls with its thumbnail, description, creator, and last update. Click the preview to open the page's details in Slack. * Public pages and pages shared with your organization unfurl in the Slack workspace connected to that organization. * A page only you can see unfurls only when you post it and your Slack account is linked to Paradev. If it is not linked, Slack asks you to connect it. * Deleted pages and pages taken down by the Paradev team do not unfurl. ## Connected Plugins [#connected-plugins] The Slack agent can use a linked user's connected Linear and GitHub plugins to read issues and repositories, file or update issues, comment, and open pull requests. It uses a limited tool set; plugin tools cannot delete resources, merge pull requests, or perform bulk writes. If a requested plugin is not connected, the reply offers a **Connect** button. ## Thread Follow-ups [#thread-follow-ups] These controls are available when thread follow-ups are enabled for your Slack team: * Once the agent has replied in a thread, follow-up replies reach it without another mention. Replies sent while it is working are queued for the next turn. * Send `!mute` to require mentions in that thread again, or `!unmute` to resume automatic follow-ups. Direct mentions still work in a muted thread. * Send `!stop` or `!cancel` in the thread or DM to end the running Slack turn. Work already completed remains in the reply's Changes footer. This does not undo actions or stop coding agents already launched in workspaces. Without thread follow-ups enabled, continue to mention `@superset` for each channel request. ## Good First Prompts [#good-first-prompts] ```text @superset file a bug: the export button 500s on reports over 10k rows. Assign to whoever owns reporting. ``` ```text @superset bump our Sentry SDK to v9 across all apps and open a PR. ``` The second one creates a workspace, runs an agent, and reports back in-thread. --- # Monorepos Source: https://docs.paradev.com/using-monorepos Working with monorepos ## Overview [#overview] Paradev works with monorepos. Workspaces are created at the repo root with access to all packages. ## Lifecycle Setup Script [#lifecycle-setup-script] ```json { "setup": [ "bun install", "cp \"$SUPERSET_ROOT_PATH/.env\" .env" ] } ``` ## Running Services [#running-services] Run multiple services from terminal: ```bash bun run dev # All services bun run --filter @myapp/web dev & # Specific package bun run --filter @myapp/api dev ``` ## Sparse Checkout [#sparse-checkout] List the folders your worktrees actually need in the project's **Sparse checkout** setting. New worktrees for that project then materialize only those folders plus the repo-root files (git cone mode). * Applies only to worktrees created after the setting changes; existing worktrees and the main repo are untouched * Leave the list empty for a full checkout * If git rejects the sparse cone, workspace creation falls back to a full checkout instead of failing ## Git Submodules [#git-submodules] Add to setup script: ```json { "setup": ["git submodule update --init --recursive", "bun install"] } ``` --- # Workspaces Source: https://docs.paradev.com/workspaces Isolated environments for each git branch ## Core Concept [#core-concept] A workspace gives a task its own directory, terminals, and ports. Local project workspaces use isolated git worktrees; cloud workspaces use separate clones. [Sessions](#sessions) use a managed scratch folder without requiring a project. ## Create Workspaces [#create-workspaces] Press **⌘N** or click "New Workspace". Create from: * **New branch** - Fresh branch from main * **Existing branch** - Continue work on a branch * **Pull request** - Review or continue a PR In the prompt-first workspace flow, **Link pull request** lets you search by title or PR number, or paste the full PR URL to match it directly. The prompt box also keeps a searchable history of your previous prompts; click the history icon to reuse one. If you type a workspace name yourself, the branch name is derived from it (slugified to kebab-case). Otherwise the workspace opens right away as **New workspace** (or **New session**), and Paradev names it in the background from your prompt and any linked GitHub issue or pull request, usually within a few seconds. The branch gets the generated name plus a short unique suffix; the worktree folder keeps the name it was created with. If the first name is vague or naming fails, Paradev tries again after the agent's next reply. The branch is renamed only while it is unpushed. Renaming the workspace yourself stops automatic naming. Per-project **Naming instructions** (in project settings) steer generated names, e.g. "prefix branches with fix/ or feat/". Each new branch-based workspace gets: * Own git branch * Own working directory * Own terminal sessions * Workspace-scoped port detection and controls New local worktrees use `//` directories. Existing worktrees keep their paths. ### Cloud Workspaces [#cloud-workspaces] Cloud workspaces run in the cloud and are available from desktop, iPhone, and iPad without keeping your own computer connected. Paradev creates a new working branch from the selected base. For multiple repositories, it uses the same working branch name in each. Attach images to the initial prompt to give the agent visual context when it starts. To set up environments and pick a machine size, see [Cloud Workspaces](/cloud-workspaces). ## Import Worktrees [#import-worktrees] If you have existing git worktrees on disk, use the **Import** tab in the New Workspace modal to bring them into Paradev. Click **Import all** to bulk-import all discovered worktrees at once. You can also right-click a project in the sidebar and choose **Import untracked worktrees**. A confirmation dialog lists the branches and paths that will be imported; the **Run setup script** checkbox is off by default, since existing worktrees are usually already set up. ## Sessions [#sessions] A **session** is a workspace without a project. Pick **No project** in the new-workspace picker, or click **+** on the sidebar's **Sessions** section. Each session gets its own git-initialized folder under `~/.superset/sessions`. Terminals, agents, chat, and the Changes panel work as usual; there's no branch or PR link. Sessions created outside the app (by the CLI or a session-mode automation) appear in the sidebar's **Sessions** section automatically. Placement happens once: if you later remove one from the sidebar, it stays removed. From the CLI, pass `--session` explicitly. Creating a host workspace requires either `--project ` or `--session`; omitting both is an error: ```bash superset workspaces create --session --local --agent claude --prompt "…" ``` On iPhone or iPad, choose **No project** in the composer's project picker, or tap **+** beside **No project** on Home. Sending your prompt creates a session on the selected online host. Automations can run in session mode too; see [Automations](/automations). ## Pin Workspaces [#pin-workspaces] Keep active workspaces at the top of the sidebar: * Right-click a workspace and choose **Pin to Sidebar** (or **Unpin**) * Drag into the **Pinned** section to pin, drag within it to reorder, drag out to unpin * Sessions work the same way * Pinned project workspaces show a project-name prefix, such as `project/workspace` If sorting or filtering prevents a sidebar drag, the notice offers an action to restore manual ordering or clear filters. ## List and Board Views [#list-and-board-views] The workspaces page toggles between **List** and **Board** layouts; Board is the default. Board columns follow workspace state, derived from agent status and PR state: **Idle**, **Working**, **Needs attention**, **Needs review**, **Merged**, and **Deleted**. Merged and Deleted are history: deleted workspaces keep a card instead of vanishing, and both auto-hide while empty when Archived is **Hidden** (the default). Toolbar controls live in two menus, shared by both layouts: * **Filter** - Project, PR state, Agent, Pinned (All workspaces / Pinned / Unpinned), and Device. Active filters show a count badge and sync to the URL. * **Display** - **Sort by**, the **Archived** window (Hidden, Past week, Past month, All), and, in Board view, **Lanes**: a checkbox per column to hide or show it. Lane visibility stays out of the URL and resets on restart. ## Restore a Workspace [#restore-a-workspace] Right-click an archived card in the **Deleted** or **Merged** lane (or an archived row in List view) and choose **Restore**. Paradev re-creates the worktree at its original path on its original branch and makes the workspace live again. * Only committed work comes back; uncommitted and untracked changes were already lost when the workspace was deleted. * Restore fails and the workspace stays archived if the branch no longer exists locally or on the remote. * Restore is unavailable while the device is offline. ## Ahead/Behind Status [#aheadbehind-status] For **local (branch-based) workspaces**, the sidebar shows how far the active branch is ahead or behind its remote branch: * **↑N** - N commits ahead of remote (unpushed) * **↓N** - N commits behind remote (needs pull/rebase) ## PR Status [#pr-status] PR-based workspaces show pull request state in the sidebar. Hover a workspace to see review status, CI checks, and GitHub links. If the branch has a deployment preview, you'll also see an **Open Preview** button. A branch can have more than one PR. The badge shows a count; click it to list them, open one on GitHub, or remove a stale link. Right-click the workspace for **Remove PR Link** and **Restore PR Link**. Removals get an undo toast. ## Bulk Actions [#bulk-actions] Select multiple workspaces within a project to act on them at once: * **⌘-click** toggles a workspace in and out of the selection; **Shift-click** selects a range * While workspaces are selected, the Projects header becomes a toolbar with **Move**, **Ungroup**, **Delete**, and **Clear** * **Move** puts the selection into a new or existing group; **Ungroup** removes grouped members from their group * Bulk delete previews every workspace and flags dirty or unpushed changes before you confirm ## Delete a Project [#delete-a-project] Right-click a project in the sidebar and choose **Delete Project…**, or use **Delete project** in the project's settings. An organization owner or the owner of the device can delete a project. * Choose the devices to delete it from. The dialog shows what other people have running on each device. If someone else has terminals or agents running, you type the project name to confirm. * Deleting stops the project's terminals and agents and archives its workspaces. Worktrees stay on disk while the project can be restored. * From the sidebar, **Hide from sidebar** removes the project only for you. * Click **Undo** in the toast, or restore the project from **Settings → Projects → Recently deleted** for 30 days. After 30 days, Paradev removes the project and its clean worktrees. Worktrees with uncommitted changes and the repository folder stay on disk. * **Delete permanently** on the Recently deleted page removes the project now. ## Use Cases [#use-cases] * **Parallel features** - Work on multiple features simultaneously * **AI agents** - Run Claude Code in separate workspaces * **Code review** - Review PRs while continuing your work ## Best Practices [#best-practices] * Use descriptive branch names: `feature/auth`, `fix/login-bug` * Don't work directly on `main` * Delete workspaces after merging --- # Claude Code in Paradev Source: https://docs.paradev.com/agents/claude-code Run Claude Code in parallel workspaces, with status, resume, subagents, and multiple accounts ## Overview [#overview] Claude Code is Paradev's most deeply integrated agent. Each session runs in its own workspace, with its own Git worktree and terminal, on your Claude plan or API key. Paradev never proxies model calls. ## Launch [#launch] Paradev starts Claude Code with: ```bash claude --dangerously-skip-permissions ``` This turns off Claude Code's approval prompts, so the agent can edit files and run commands in its worktree without asking. To keep the prompts, open **Settings → Agents → Claude** and remove the flag from **Command** and **Resume args**. Worktrees separate files, but do not sandbox processes; see [Workspaces](/workspaces). ## What Paradev Adds [#what-paradev-adds] * **Status and notifications** - The sidebar shows when Claude Code is working, needs input, or is done, and you get a notification. See [Agent Status](/agent-status). * **Resume and fork** - Paradev restores a session after a restart with `--resume`, and can fork a session with `--fork-session`. See [Agent Sessions](/agent-sessions). * **Subagents** - Subagents appear under their parent session in the terminal header's **Subagents** menu. * **Handoff** - Moving a conversation to another agent carries Claude Code's structured transcript. * **Model and effort** - Pick a Claude model and a reasoning effort when you launch. See [AI Agents](/agent-integration#models-and-reasoning-effort). * **Usage and accounts** - The [Usage](/usage) page shows quota meters and token costs, and lets you add several Claude accounts and choose the default. ## Run Several Sessions [#run-several-sessions] Press **⌘N** for each task. Each workspace gets its own worktree, so sessions never edit the same files. To give the same task to Claude Code and another agent and keep the best result, see [Race Agents on One Task](/recipes/race-agents). --- # Codex in Paradev Source: https://docs.paradev.com/agents/codex Run OpenAI Codex in parallel workspaces, with status, resume, subagents, and multiple accounts ## Overview [#overview] Codex is one of Paradev's most deeply integrated agents. Each session runs in its own workspace, with its own Git worktree and terminal, on your ChatGPT plan or OpenAI API key. Paradev never proxies model calls. ## Launch [#launch] Paradev starts Codex with: ```bash codex --dangerously-bypass-approvals-and-sandbox --dangerously-bypass-hook-trust ``` This turns off Codex's approval prompts and sandbox, so the agent can edit files and run commands in its worktree without asking. To keep them, open **Settings → Agents → Codex** and remove the flags from **Command**, **Resume args**, and **Fork args**. Worktrees separate files, but do not sandbox processes; see [Workspaces](/workspaces). ## What Paradev Adds [#what-paradev-adds] * **Status and notifications** - The sidebar shows when Codex is working, needs input, or is done, and you get a notification. See [Agent Status](/agent-status). * **Resume and fork** - Paradev restores a session after a restart with `codex resume`, and can fork one with `codex fork`. See [Agent Sessions](/agent-sessions). * **Subagents** - Subagents appear under their parent session in the terminal header's **Subagents** menu. * **Handoff** - Moving a conversation to another agent carries Codex's structured transcript. * **Model and effort** - Pick a GPT model and a reasoning effort when you launch. See [AI Agents](/agent-integration#models-and-reasoning-effort). * **Usage and accounts** - The [Usage](/usage) page shows quota meters and token costs, and lets you add several Codex accounts and choose the default. ## Run Several Sessions [#run-several-sessions] Press **⌘N** for each task. Each workspace gets its own worktree, so sessions never edit the same files. To give the same task to Codex and another agent and keep the best result, see [Race Agents on One Task](/recipes/race-agents). --- # Overview Source: https://docs.paradev.com/plugins/overview Give your coding agents new tools and skills, and which agents support them A plugin connects your coding agents to another service, such as an issue tracker or an error monitor. Each plugin is a bundle of two things: * **MCP tools** the agent can call, such as "create an issue" or "search errors". * **Skills** that teach the agent when and how to use those tools. You install a plugin from the desktop app, and Paradev sets it up for the agents on that machine. When a plugin needs an account, you connect it in Paradev; the agent never sees your credentials. See [Available Plugins](/plugins/available) for guides to individual plugins. The Plugins page in the desktop app, with plugins grouped by category ## Install a Plugin [#install-a-plugin] 1. Open **Plugins** in the sidebar. 2. Select a plugin and click **Install**. The Granola plugin page, showing its app, its skills, and the Install plugin button 3. If the plugin needs an account, click **Connect an account** and sign in to the service. The GitHub plugin page after install, with Connect an account under Connected accounts Start a new agent session to pick up the new tools and skills. ## Supported Agents [#supported-agents] | Agent | MCP tools | Skills | | :--------------- | :-------: | :----: | | Claude Code | ✅ | ✅ | | Codex | ✅ | ✅ | | Kimi, Vibe, Grok | — | ✅ | | Other agents | — | — | — means not supported yet. ## MCP Tools [#mcp-tools] When you install a plugin, Paradev adds its MCP server to each supported agent's own config file. You do not edit these files yourself. | Agent | Config file | How Paradev writes it | | :---------- | :----------------------------------- | :----------------------------------------------------------------------------------------- | | Claude Code | `~/.claude.json` (user `mcpServers`) | Adds one entry per plugin and records it in `~/.superset/plugins/mcp-ledger.json` | | Codex | `~/.codex/config.toml` | Adds `[mcp_servers.]` tables inside a `# >>> superset managed mcp servers >>>` block | * **Your entries win.** If you already configured a server for that agent with the same name as the plugin, Paradev leaves yours in place and does not add a copy. This is per agent: a server you added to Codex does not stop Paradev from adding it to Claude Code. * **Uninstall cleans up.** Removing a plugin removes the entries Paradev wrote. In Claude Code, an entry you edited is now yours and stays. In Codex, Paradev owns everything inside its marked block, so put your own servers outside it. * **Credentials stay on Paradev.** The entries point at the Paradev proxy. Your OAuth tokens are never written to these files. The [Chat UI](/chat) runs the same CLI, so a plugin's tools work there too. ## Skills [#skills] A plugin's skills go to the same places as the built-in [Paradev skills](/skills): | Location | Read by | | :--------------------------- | :------------------------------------ | | `~/.claude/skills/superset/` | Claude Code, as the `superset` plugin | | `~/.agents/skills/` | Codex, Kimi, Vibe, Grok | Skills refresh at every app launch, and skills from an uninstalled plugin are removed. --- # Paradev CLI Reference Source: https://docs.paradev.com/cli/cli-reference Complete reference for Paradev command-line interface, including commands and flags. The CLI is currently in Beta. Commands and flags are still evolving. Make sure you're on the latest version of the CLI if you run into issues. ## Synopsis [#synopsis] ```text superset [subcommand] [options] ``` Run `superset --help` for the top-level command list, or `superset --help` for any group. ## Global options [#global-options] These flags are accepted by every command: | Flag | Env | Description | | ----------------- | ------------------ | ------------------------------------------------------------------------------- | | `--json` | | Print the data payload as formatted JSON. | | `--quiet` | | One ID per line for arrays; the ID for single objects; JSON fallback otherwise. | | `--api-key ` | `SUPERSET_API_KEY` | Use an API key instead of stored OAuth login. | | `--help`, `-h` | | Show help for the current command. | | `--version`, `-v` | | Print the version number and exit. | *** ## Commands [#commands] ### scripts [#scripts] Reusable terminal launches. These are called terminal scripts in the app; setup, run, and teardown entries in `.superset/config.json` are project lifecycle scripts. The legacy `presets` command name remains an alias. Add a terminal script to the desktop app on this machine. The desktop app must have been launched once so its local database exists, and the CLI must have an active organization so the script is imported into the correct v2 profile. When iterating on one script, pass `--upsert` so each revision replaces the last instead of piling up copies in the Scripts bar. ```bash superset scripts add --name dev --command "bun run dev" superset presets add --name services \ --command "docker compose up" --command "bun run dev" \ --execution-mode split-pane superset scripts add --name "Open in GitHub" --command "gh pr view --web" --upsert ``` The created terminal script, including its generated ID. List the terminal scripts on this machine with the id each other command takes. `status` is `importing` or `deleting` while a change is waiting for the desktop app to open or refocus with the same organization active. Scripts created in the desktop app's Settings are stored in the app profile only and do not appear here. ```bash superset scripts list superset scripts list --json ``` Change fields on an existing script. Unspecified fields keep their values, and the desktop app updates its copy in place, so the script keeps its position in the Scripts bar. Edits made in the desktop app's Settings do not flow back to the CLI: an edit here replaces the app's copy with what `superset scripts list` shows plus your changes. ```bash superset scripts edit --command "gh pr view --web" superset scripts edit --name "Open PR" --hidden superset scripts edit --all-projects --no-hidden ``` Delete a script. The desktop app removes its copy the next time it opens or refocuses with the same organization active (immediately when it is running); until then the script lists with status `deleting`. ```bash superset scripts delete ``` *** ### auth [#auth] Authentication and session inspection. Authenticate via browser OAuth and store a session token at `~/.superset/config.json`. Single-org accounts are selected automatically. With multiple orgs and a TTY, the CLI prompts; with multiple orgs and no TTY, you must pass `--organization` or the command exits 1 listing the available slugs. ```bash superset auth login superset auth login --organization acme ``` To sign in with an API key (useful for CI or any environment where the OAuth browser flow isn't an option), pass `--api-key`. The CLI validates the key, stores it at `~/.superset/config.json`, and clears any prior OAuth session. ```bash superset auth login --api-key sk_live_… superset auth login --api-key sk_live_… --organization acme ``` The newly authenticated user and active organization. ```text ◇ Authorized! │ Satya Patel (you@example.com) │ Organization: Acme └ Logged in successfully. ``` ```ts { userId: string; organizationId: string; organizationName: string; } ``` Clear stored credentials: both an OAuth session and a stored API key. Does not call the API and does not clear the active organization (your preferred org persists across re-logins). ```bash superset auth logout ``` A confirmation message. ```text Logged out. ``` ```ts { message: "Logged out." } ``` Show the current user, active organization, and auth source. ```bash superset auth whoami ``` The current user and organization context. ```text Signed in as Satya Patel (you@example.com) Organization: Acme Auth: Session (expires in 32 min) ``` ```ts { userId: string; email: string; name: string; organizationId: string; organizationName: string; authSource: "override" | "config" | "oauth"; } ``` *** ### start [#start] Start the local host server: the daemon the CLI and desktop app both talk to when targeting this machine. If a manifest exists and the PID is alive, returns the existing instance's `{ pid, endpoint }`. Otherwise spawns the host server binary, polls `/trpc/health.check` for up to 10 seconds, and writes the manifest. Binds to `127.0.0.1` only. ```bash superset start --daemon ``` The running host server. ```ts // Freshly started { pid: number; port: number; organizationId: string; } // Already running { pid: number; endpoint: string; } ``` ### stop [#stop] Stop the local host server. Sends SIGTERM, waits up to 10 seconds, sends SIGKILL if still alive, then removes the manifest. If sending SIGTERM itself throws, the command errors and the manifest is left in place. The terminal daemon keeps running after the host server stops, so the next `superset start` picks up the same terminals. With `--terminals`, the command stops the host server first, then the terminal daemon, the same way. It signals only the pid the daemon reports over its socket, never the pid in its manifest, which can be stale. If the socket is missing or refuses the connection, the manifest is removed without a signal. If the socket accepts the connection but the daemon does not answer, the command errors after it has stopped the host server, and leaves the daemon and its manifest in place. ```bash superset stop superset stop --terminals ``` The processes the command stopped, if any were running. ```ts // Nothing running { running: false } // Something stopped { pid: number | null; // host server; null if none was running terminalDaemonPids: number[]; // empty without --terminals or if none was running organizationId: string; } ``` ### status [#status] Inspect the local host server. `healthy` reflects a live `health.check` request (2-second timeout). ```bash superset status ``` The host server state. Three shapes depending on what's running. ```ts // No manifest { running: false; organizationId: string; hostId: string } // Manifest exists but PID is dead { running: false; stale: true; pid: number; organizationId: string; hostId: string; } // Running { running: true; healthy: boolean; pid: number; port: number; endpoint: string; organizationId: string; hostId: string; hostName: string; uptimeSec: number; } ``` ### update [#update] Update the Paradev CLI and host server binary. Downloads the matching `superset-.tar.gz` from GitHub Releases and atomically replaces the install root. Only available in built binaries; running from `bun run dev` errors out. ```bash superset update # upgrade to the latest release superset update --check # show current → target without installing superset update --version 0.1.2 # install a specific version (up or down) ``` The current and target version, plus whether anything changed. ```text Updated 0.1.4 → 0.1.5 (/Users/you/.local/share/superset) ``` ```ts // --check { current: string; target: string; upToDate: boolean; pinned: boolean; } // install { current: string; target: string; updated: boolean; installRoot?: string; } ``` *** ### organization (alias: `org`) [#organization-alias-org] Manage which organization the CLI targets. List organizations available to the current auth context. Marks the active one. Set the active organization in `~/.superset/config.json`. ```bash superset organization switch acme superset org switch org_… ``` List members in the active organization. ```bash superset organization members list superset org members list -s satya ``` *** ### projects [#projects] A project is a repository checked out on a host. Projects are host-owned: each host serves the projects set up on that machine; there is no org-wide listing. Workspaces branch off a host's checkout. List projects on a host. Defaults to this machine; pass `--host ` for another host. Create a fresh project on a host. Two modes: * **Clone**: pass `--clone ` and `--parent-dir`. The host clones the repo into `//`. * **Import**: pass `--import ` to register a repo that already exists on disk. Either way, the project is registered on the host with no workspaces yet; create one with `superset ws create --project --name local --checkout local --local` (the repo's checkout as it is) or `--branch ` (its own worktree). `create` always creates a new cloud project, even if your org already has one for the same Git URL. Use [`projects setup`](#superset-projects-setup-id) when adopting an existing project on a fresh machine. ```bash superset projects create --name "my-app" --local --clone https://github.com/org/my-app.git --parent-dir ~/code superset projects create --name "my-app" --local --import ~/code/my-app ``` Adopt an existing project onto a host without creating a duplicate cloud record. Counterpart to [`create`](#superset-projects-create) for the "new machine, repo already in the org" case. Find the project ID via [`projects list`](#superset-projects-list). Idempotent: re-running against a project that's already set up at the same path is a no-op. ```bash # Pick an ID from `superset projects list`, then clone it onto this machine superset projects setup 47c31b04-… --local --parent-dir ~/code # Or register an existing local checkout superset projects setup 47c31b04-… --local --import ~/code/my-app ``` *** ### hosts [#hosts] Discover hosts registered to the active organization. To control the host server running on this machine, use [`start`](#start), [`stop`](#stop), and [`status`](#status). List hosts registered to the active organization. A machine registers itself when `superset start` runs on it, or when you set it up over SSH with [`hosts add`](#hosts). ```bash superset hosts list ``` Set up a machine you can SSH into as a host, with nothing typed on it: installs this CLI's version there, signs it in with a new API key sent over ssh stdin, runs it as a user service, and waits for it to come online. Running it again on the same target repairs only what is wrong. The remote must be macOS or glibc Linux on x64 or arm64 (not Alpine or Windows) and have `curl`. On Linux it also needs a valid `/etc/machine-id`, and lingering (`loginctl enable-linger`) to keep running after you log out. Install and sign in `gh` there to clone private repos. ```bash superset hosts add me@build-box superset hosts add build-box --name "Build box" --yes ``` Undo `hosts add`: stop the host over SSH and remove its service. If it finds the API key `hosts add` created, it revokes it and signs the host out; otherwise it leaves the host's sign-in alone. The CLI stays installed, and the host stays listed (offline) until you delete it in Settings → Hosts. ```bash superset hosts remove me@build-box ``` Set (or clear) the command used to wake a host. ```bash superset hosts set-wake my-sandbox vercel sandbox resume my-box superset hosts set-wake my-sandbox --clear ``` Wake a host by running its configured wake command locally, streaming its output. ```bash superset hosts wake my-sandbox ``` *** ### workspaces (alias: `ws`) [#workspaces-alias-ws] Workspaces use a shared project checkout, an isolated worktree, or a project-less session folder on a host. **Routing:** when `--host` resolves to the local machine, the CLI calls the host server directly over loopback HTTP: no cloud roundtrip, works offline. Otherwise it routes through the cloud API and the relay. If the resolved host is the local machine but the host server isn't responding, the CLI errors out and points you at `superset start` rather than silently falling through to the cloud. List workspaces on a host. Defaults to this machine; pass `--host ` for another host. Workspaces are host-owned; there is no org-wide listing (the desktop app is the cross-host view). `projectName` falls back to the raw project id when the host doesn't know the project's name. Create a workspace on the target host. With `--project`, specify one of `--checkout local`, `--branch`, `--pr`, or `--task` (`--branch` and `--pr` are mutually exclusive). If you pass `--agent`, you must also pass `--prompt`. `--command` runs a one-off shell command in the workspace directory and is independent of `--agent`/`--prompt`. Pass either or both. `--model` and `--effort` require `--agent`; see the [agent effort levels](#agent-effort-levels) below. `--checkout local` shares the project's existing files, git index and checked-out branch. It does not switch branches or run setup. Do not combine it with `--branch`, `--pr`, `--base-branch`, or `--skip-branch-prefix`. Local creation requires a host that supports local workspaces; older hosts reject it without creating a worktree. `--local` selects this machine and is independent of `--checkout local`. Pass `--session` explicitly to create a **session**: a project-less workspace backed by a managed folder under `~/.superset/sessions`, initialized as its own git repo. Sessions have no branch semantics, so `--branch`, `--pr`, `--task`, `--base-branch`, `--checkout`, `--skip-branch-prefix`, and `--tag` are rejected, `--name` is optional, and the output has no `alreadyExists` field. Host workspace creation requires either `--project ` or `--session`; omitting both is an error. Without `--host` or `--local`, the command creates a [cloud workspace](/cloud-workspaces) if your account has cloud workspaces. A cloud workspace takes no project: it starts from an environment, and Paradev creates a new working branch from `--branch`. `--project`, `--session`, `--checkout`, `--pr`, `--task`, `--base-branch`, `--skip-branch-prefix`, `--tag`, `--attachment`, and `--command` are rejected for a cloud workspace. The command returns while the workspace is still provisioning. ```bash superset workspaces create \ --project prj_… \ --name "fix-login-bug" \ --branch fix/login-bug \ --local superset workspaces create \ --project prj_… \ --name "review-pr-123" \ --pr 123 \ --local # Project-less session with an agent superset workspaces create --session --local --agent claude --prompt "…" # Tags group the workspace into sidebar folders — no folder setup needed superset workspaces create --project prj_… --name "perf-spike" --branch perf/spike --local --tag perf ``` Archive one or more workspaces. Without `--host` or `--local`, this targets cloud workspaces if your account has them, else this machine. The old name `delete` remains an alias. * **Cloud workspace:** the sandbox stops within a minute and is deleted after 7 days. A restore within those 7 days keeps its disk; after that, the workspace starts again from a fresh sandbox. * **Worktree workspace on a host:** its folder is removed, with any uncommitted changes. Its branch stays, so a restore brings back only committed work. A workspace that shares the project's own checkout keeps that folder. `deleted` lists the archived IDs; the field keeps its old name so existing scripts still work. Each ID is reported on its own: unknown IDs land in `notFound`, errors land in `failed` with a reason, and the rest of the batch still runs. The command exits non-zero if either list is not empty. ```bash superset workspaces archive ws_a ws_b ws_c ``` Put a cloud workspace to sleep. Its sandbox stops, every terminal and agent in it ends, and it costs storage only. Files are kept, and opening the workspace wakes it. An agent can run this as its last step, inside its own workspace. ```bash superset workspaces sleep ws_a ``` Show details for a single workspace on its host. `--field` is handy in scripts: `superset workspaces get --field worktreePath`. ```bash superset workspaces get ws_… superset workspaces get --field branch # inside a workspace ``` Update a workspace on its host (default: this machine). `--tag` replaces the whole tag set: tagging is how workspaces group into sidebar folders, so retagging moves the workspace between folders. ```bash superset workspaces update ws_… --name "better-name" superset workspaces update ws_… --task-id tsk_… superset workspaces update ws_… --tag perf --tag infra superset workspaces update ws_… --clear-task ``` Open a workspace in the Paradev desktop app. ```bash superset workspaces open ws_… superset workspaces open ws_… --print ``` #### Opening a specific session [#opening-a-specific-session] `workspaces open` targets a workspace, not a session. Terminal sessions started with [`agents create`](#superset-agents-create) are automatically adopted into panes while their workspace is open. Opening the workspace later also creates panes for running terminal sessions that aren't already attached, without stealing focus from the active tab. `workspaces open` can't focus a specific session, so use a session deep link when focus matters. The same deep link creates or focuses the pane for a Paradev chat session. Choose the query param from the session `kind` returned by `agents create`: | `kind` | Example agents | Query param | | ---------- | ----------------- | ---------------------------- | | `chat` | `superset` | `?chatSessionId=` | | `terminal` | `claude`, `codex` | `?terminalId=` | ```bash # Run the agent with --json, then pull kind + sessionId out of the payload: session=$(superset agents create --workspace ws_… --agent claude --prompt "…" --json) kind=$(echo "$session" | jq -r '.kind') # "chat" or "terminal" sessionId=$(echo "$session" | jq -r '.sessionId') # Open the session using the query param that matches its kind: # chat session (kind: "chat") open "superset://v2-workspace/?chatSessionId=$sessionId" # terminal session (kind: "terminal") open "superset://v2-workspace/?terminalId=$sessionId" ``` Append `&focusRequestId=` to force a re-focus when opening the same link more than once. The session must belong to the workspace in the URL. On Linux/Windows substitute your platform's URL opener (`xdg-open`, `start`) for `open`. *** ### agents [#agents] Agents are terminal-agent rows configured on a host (the same rows shown in Settings → Agents on that machine). Each row stores a `command`, `args`, prompt-transport mode, and environment used to launch the agent in a fresh terminal session inside a workspace. List agents configured on a host. First call on a fresh host seeds the bundled defaults. ```bash superset agents list --local superset agents list --host host_… ``` Create an agent session in an existing workspace on its host (default: this machine): starts the named preset (or HostAgentConfig instance) in a fresh terminal session there. ```bash superset agents create --workspace ws_… --agent claude --model sonnet --effort high --prompt "Audit the login flow" superset agents create --workspace ws_… --agent codex --prompt "Review this diff" --attachment ./trace.log # Restore a killed agent session by the agent's own session id superset agents create --workspace ws_… --agent claude --resume-session 0b7c… # Fork a session: a new Claude session with the same conversation superset agents create --workspace ws_… --agent claude --fork-session 0b7c… # Hand a terminal's recent output to a different agent superset agents create --workspace ws_… --agent codex --from-terminal term_… superset agents create --workspace ws_… --agent codex --from-terminal term_… --context-chars 12000 ``` Pass at most one of `--resume-session`, `--fork-session`, and `--from-terminal`. See [Fork and hand off sessions](/agent-sessions#fork-and-hand-off-sessions) for which agents can fork and what a handoff sends. Read the agent's saved transcript, beyond the visible screen returned by `terminals read`. Without `--host` or `--local`, the target defaults to cloud when your account has cloud workspaces, otherwise this machine. The command fails if Paradev cannot read a transcript for that terminal. ```bash superset agents read --local --workspace --terminal ``` The transcript object in JSON mode, or its text in human-readable mode. Block until an agent reaches a state, instead of polling `terminals read`. Returns at once if it is already there. Exits 1 on timeout, and at once if the agent exits. ```bash T=$(superset agents create --workspace ws_… --agent claude --prompt "Add a /health route" --json | jq -r .sessionId) superset agents wait --workspace ws_… --terminal "$T" ``` ```ts { terminalId: string; state: "starting" | "working" | "blocked" | "idle"; lastEventType: string | null; } ``` Explain why an agent shows its state: its last hook event and when it arrived, how an ended session ended, or that no hook has arrived (an agent Paradev can't see). Useful when `agents wait` or `panes list` shows something unexpected. ```text claude is idle. Why: its recorded event is Stop, which means its turn ended: it finished, or it was interrupted. The last hook arrived 1 second ago; the session started 2 seconds ago. ``` ```ts { terminalId: string; state: "starting" | "working" | "blocked" | "idle" | "exited" | "none"; because: string; details: string[]; lastEventType: string | null; lastEventAt: number | null; } ``` #### Agent models [#agent-models] Model is an explicit override for one launch. If you omit `--model`, Paradev passes no model flag and the agent uses its own configured default. Ids match the desktop model picker: Claude takes a family alias (`fable`, `opus`, `sonnet`, `haiku`) that tracks the newest release, or a pinned id such as `claude-opus-5-5` or `claude-sonnet-5-5`. Codex includes `gpt-6-astra`, `gpt-6-sol`, and `gpt-6-luna`. The host rejects an unknown id before launching the agent, and the error names every id that agent accepts. Agents without a model picker, including Paradev chat, reject an explicit model override. #### Agent effort levels [#agent-effort-levels] Effort is an explicit override for one launch. If you omit `--effort`, Paradev passes no effort flag and the agent uses its own configured default. The host rejects unsupported values before launching the agent. | Agent | Supported levels | | ---------- | -------------------------------------------------------------------------------- | | Claude | `low`, `medium`, `high`, `xhigh`, `max` | | Amp | `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` | | Codex | `low`, `medium`, `high`, `xhigh`; `max` and `ultra` depend on the selected model | | Mastracode | `off`, `low`, `medium`, `high`, `xhigh` | | Pi | `off`, `minimal`, `low`, `medium`, `high`, `xhigh` | | Copilot | `low`, `medium`, `high`, `xhigh` | GPT-6 Astra and GPT-6 Sol support `max` and `ultra`; GPT-6 Luna supports `max`. Other agents, including Paradev chat, currently use their own default and reject an explicit effort override. *** ### terminals (alias: `term`) [#terminals-alias-term] Terminals are PTY sessions on a host, scoped to a workspace. Create one to run a one-off command in a worktree or to open an interactive shell. Create a terminal session in an existing workspace on its host (default: this machine): opens a fresh PTY in the worktree, optionally running a command. ```bash superset terminals create --workspace ws_… --command "bun install && bun test" superset terminals create --workspace ws_… ``` List the live terminal sessions in a workspace. Presence in the list means the PTY exists, not that an agent inside it is working or idle. Read a terminal's current screen back as text without mutating the session. ```bash superset terminals read --workspace ws_… --terminal term_… --max-lines 240 ``` Send a follow-up message or key presses to a terminal already running in a workspace, e.g. to give an agent new instructions mid-session, approve a prompt, or interrupt it. ```bash superset terminals send --workspace ws_… --terminal term_… --text "Now add a test" --wait superset terminals send --workspace ws_… --terminal term_… --keys esc ``` Block until a terminal's screen matches a pattern, e.g. a dev server's "listening on". `matched` is the text the pattern matched, which can span lines. Exits 1 on timeout, or at once if the terminal exits first. ```bash superset terminals wait --workspace ws_… --terminal term_… --match "listening on :\d+" ``` ```ts { terminalId: string; matched: string; } ``` Attach this shell to a running terminal. `Ctrl+]` detaches; the terminal keeps running. Needs an interactive terminal and refuses to run in CI. ```bash superset terminals attach --workspace ws_… --terminal term_… superset terminals attach --ssh me@build-box --workspace ws_… --terminal term_… ``` Close (dispose) a terminal running in a workspace. This ends the session. *** ### snapshot [#snapshot] One read of a host: every workspace, its live terminals, the agent in each with its state, and the pane layout when the desktop app is attached. Use it instead of listing terminals and panes workspace by workspace. An unknown `--workspace` is an error. ```text acme-web / health-check [health-check] ws_… terminal ebed… "/health route README section" claude · working terminal 63c9… ``` ```ts { workspaces: Array<{ id: string; name: string; project: string | null; branch: string | null; terminals: Array<{ id: string; title: string | null; agent: { id: string; state: "starting" | "working" | "blocked" | "idle" } | null }>; layout: PaneLayout | null; // as in `panes list`; null without a desktop app layoutError: string | null; // set when a desktop app is attached but the layout could not be read }>; } ``` ### panes [#panes] Script the pane layout of a workspace in the desktop app. Commands go to the host, then to the desktop app, which applies them to the live layout. Works for workspaces on the machine running the desktop app. Only `focus` moves focus. Tabs and the split tree. `row` splits are side by side and `column` splits are stacked, as in CSS flexbox; `ratio` is the first pane's share. Each terminal pane carries its title and the agent running in it with its state. ```text row 50/50 pane-5f00… terminal terminal 63c9… (active) pane-03e1… terminal "/health route README section" claude · working terminal ebed… ``` ```ts { activeTabId: string | null; tabs: Array<{ id: string; active: boolean; activePaneId: string | null; layout: PaneNode; // { type: "split", direction: "row" | "column", ratio, first, second } | { type: "pane", paneId } panes: Array<{ id: string; kind: string; title: string | null; terminalId: string | null; active: boolean; terminalTitle?: string | null; agent?: { id: string; state: "starting" | "working" | "blocked" | "idle" } | null; }>; }>; } ``` Open a new tab with a terminal pane, without moving focus. Split a pane and show a terminal in the new half. Set a pane's share of the split it sits in. `superset panes equalize --workspace [--tab ]` evens out every split instead. Move a pane. A tab left empty closes. `superset panes swap --workspace --pane A --with B` exchanges two panes, and `superset panes focus --workspace --pane P` focuses one. Close a pane and end its terminal, as the close button in the app does. ### notifications [#notifications] Show a desktop notification. Run from a Paradev terminal, clicking it opens that terminal, so an agent can say "tests pass" and take you straight back. With `--host`, pass `--workspace` and `--terminal` for a click target; without them the click only brings the app forward. ```bash superset notifications show "Tests pass" --body "12 passed" --sound ``` ### browser [#browser] Drive a workspace's [in-app browser](/browser) panes: open and navigate URLs, screenshot, read console, evaluate JavaScript, and get a raw Chrome DevTools Protocol endpoint for click/type/scroll automation. Every operation runs in the pane the user sees, against the browser's real session. Browser panes live in the desktop app, so a standalone host with no desktop attached has no panes and these commands error. A `paneId` is scoped to its workspace; pass the same `--workspace` it was opened under. See the [`browser` skill](/skills) for the agent-facing protocol. List the browser panes open in a workspace. Open a URL in a browser pane and return its `paneId`. Requires the workspace to be visible in the desktop app (the renderer creates the pane). ```bash superset browser open --workspace ws_… --url http://localhost:3000 --target new-tab ``` Point an existing pane at a new URL. `file://`, `chrome://`, and custom schemes are refused. Capture a PNG screenshot of the pane's page. Evaluate JavaScript in the page and return the result for reading or nudging the DOM. ```bash superset browser eval --workspace ws_… --pane pane_… \ --code "document.querySelector('h1')?.textContent" ``` Read the pane's captured console output. Print a raw Chrome DevTools Protocol WebSocket endpoint for the pane, for browser-use / Playwright-class tools (mouse, keyboard, scroll, DOM, network). The URL embeds an auth token; treat it as a secret. *** ### pages [#pages] Publish and manage [Pages](/pages) in the active organization. Without `--limit` or `--cursor`, fetches all matching pages and returns a plain array. Either pagination flag selects one batch and returns `{ items, nextCursor }`; `nextCursor` is null at the end. A cursor without a limit uses 50 rows per batch. Pages are ordered newest-created first. `--quiet` prints page IDs in either mode. Linked workspaces appear in the WORKSPACE column and in each row's `workspaceLinks`. ```bash superset pages list --workspace '' --search onboarding --json superset pages list --workspace '' --limit 20 --json superset pages list --workspace '' --limit 20 --cursor '' --json ``` Publishing the same entry path from the same workspace adds a version to the existing page. Without a workspace, keep the returned ID and pass `--page` on later publishes to avoid creating another page. Existing visibility is preserved unless explicitly supplied. Publishing does not open the page in the desktop. ```bash superset pages publish report.html --title "Weekly report" --visibility everyone superset pages publish report.html --page --label "Addressed feedback" ``` Page metadata including `id`, `title`, `version`, and `url`, plus `unanchored`, `watching`, and asset upload/reuse counts. Unlinked publishes include a `republish` command. When the publish tries to register the session for comments, `watchNote` says whether it worked. Delete a page and every version. Interactive terminals ask for confirmation unless `--yes` is passed; non-interactive input does not prompt. Read what viewers stored with `window.superset.storage` on a page. Without `--key`, lists each key with its record count (KEY, RECORDS, UPDATED). With `--key`, lists each person's value for that key (NAME, VALUE, UPDATED). On a `just_me` page only the creator can read storage. On an `org` or `everyone` page, members of the page's organization can read it, even when the page is public. ```bash superset pages storage weekly-report superset pages storage weekly-report --key votes --json ``` *** ### plugins (alias: `plugin`) [#plugins-alias-plugin] Install and connect plugins on this machine, and author them in a marketplace repo. Installing records the plugin on your account and writes its skills and MCP servers to Claude, Codex, and pdev. List installed plugins, or everything available with `--available`. Connects the plugin's account first if it needs one, then writes its skills locally and records the install on your account. ```bash superset plugins install google-calendar ``` Connect an account to an installed plugin. Enable an installed plugin. Disable an installed plugin without dropping it. Uninstall a plugin and drop its skills. Reconcile installed plugins with the skill directories agents read and the MCP entries Claude, Codex, and pdev read, adding, refreshing, and reaping both. `add [--name ]` adds a marketplace from a GitHub repo or local path. `list` shows the marketplaces on your account. `remove ` removes one. Scaffold a new plugin and add it to the marketplace. Validate a plugin or a whole marketplace: manifest, release tag, and whether the built server matches its source. Cut a version of a plugin: build, record it in the marketplace and the generated bundle, and name the tag to publish it at. *** ### mcp [#mcp] Call the tools of a plugin you have connected. The call goes through Superset's API, which attaches the stored credential, so no token is written to this machine. List the tools a connected plugin exposes (PLUGIN, TOOL, DESCRIPTION). ```bash superset mcp tools --plugin slack ``` Call a tool on a connected plugin and print its result. ```bash superset mcp call-tool search_messages --plugin slack '{"query":"deploy"}' ``` *** ### skills [#skills] List the skills installed from plugins on this machine (SKILL, PLUGIN, PATH). *** ### tasks (alias: `t`) [#tasks-alias-t] Tasks are units of work in your organization's task tracker. When the organization tracks tasks in Linear (an owner's setting), these commands work on its Linear issues through your own Linear connection; otherwise on Paradev tasks. A command works on one tracker only: in an organization that tracks in Linear, Paradev tasks are not listed or resolved, and the reverse. Pass `--tracker superset|linear` to reach the other one for a single command. List tasks in the active organization. ```bash superset tasks list --assignee-me superset t list -s "auth" --json ``` Get a task by ID or slug. ```bash superset tasks get tsk_… superset tasks get fix-login-bug ``` Create a task. ```bash superset tasks create --title "Audit auth flow" --priority high ``` Update a task. Same fields as `create`, all optional. ```bash superset tasks update fix-login-bug --priority urgent ``` Delete one or more tasks. Linear issues are archived. ```bash superset tasks delete tsk_a tsk_b ``` List task statuses in the active organization. Paradev status IDs work with `tasks list --status`, `tasks create --status-id` and `tasks update --status-id`. Linear statuses belong to a team: pass their names or IDs to `--status-id` on create and update; `tasks list --status` takes a category (`active`, `started`, …) for Linear. ```bash superset tasks statuses list ``` *** ### automations (alias: `auto`) [#automations-alias-auto] Agent runs on a schedule or on events. Schedules use RFC 5545 RRULE bodies, e.g. `FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=9;BYMINUTE=0`. Event triggers (GitHub, Slack, Linear, Sentry, Notion, Microsoft Teams, webhook) are passed as a JSON trigger set; see [Automations](/automations#triggers). List automations in the active organization. Get an automation's metadata. The prompt body is omitted. Use [`automations prompt get`](#superset-automations-prompt-get-id) to read it. Use [`automations logs`](#superset-automations-logs-id) for run history. Create an automation. Pass `--rrule` for a schedule, or `--triggers` / `--triggers-file` for event triggers; one of them is required. Automations are a Pro feature: `create`, `run`, and `resume` need a Pro or Enterprise subscription on the active organization and fail with `Automations require the Pro plan.` otherwise. Provide `--prompt` or `--prompt-file`; if both are present, the inline `--prompt` value is used. A `--project` or `--workspace` must exist on the target host; the CLI verifies this before creating the automation. Omit both for **session mode**: each run creates a project-less session workspace on the target host. Every run's created workspace carries the automation's tags, which group it into the matching sidebar folders. By default automations are tagged `automation`, so their runs collect in an **automation** folder per project; pass `--tag` to file runs elsewhere. ```bash superset automations create \ --name "Weekday triage" \ --project prj_… \ --workspace ws_… \ --rrule "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=9;BYMINUTE=0" \ --prompt-file ./prompts/triage.md ``` List the values an event trigger can filter on (Slack channels, GitHub repositories, Linear teams, ...), with the ids to put in a trigger set. Reports when the provider isn't connected. ```bash superset automations trigger-options --group slack ``` Update an automation (name, schedule, triggers, agent, host). All flags optional. Omitting a flag preserves the existing value: `undefined` means "no change", not "clear". Use [`automations prompt get`](#superset-automations-prompt-get-id) or [`automations prompt set`](#superset-automations-prompt-set-id) to read or replace the prompt body. Print an automation's prompt body to stdout. The output is the raw prompt with no trailing newline added, so `prompt get` and `prompt set` round-trip byte-exactly. ```bash # Read to a file superset automations prompt get aut_… > prompt.md # Verify a push landed superset automations prompt get aut_… | diff - ./prompt.md ``` Replace an automation's prompt body. The new prompt fully overwrites the old one. ```bash # Write from file superset automations prompt set aut_… --from-file ./prompt.md # Write from stdin cat ./prompt.md | superset automations prompt set aut_… --from-file - ``` Delete an automation. ```bash superset automations delete aut_… ``` Pause an automation (sets `enabled: false`). ```bash superset automations pause aut_… ``` Resume an automation (sets `enabled: true`). The API recomputes `nextRunAt` on resume. ```bash superset automations resume aut_… ``` Dispatch an automation immediately. Does not wait for completion. ```bash superset automations run aut_… ``` List recent runs for an automation. ```bash superset automations logs aut_… ``` *** ### settings [#settings] Read and update the Paradev desktop app's settings on this machine: behavior, git, notifications, terminal, terminal/editor appearance, and the app theme. These commands work offline and don't require login. After every write the CLI nudges the running desktop app, which refreshes immediately, themes included, no restart (the command output confirms with "refreshed immediately" / "applied to the running desktop app"). Without a running app (or on older app versions) settings apply on next window focus and theme changes on next launch. Git settings (`branchPrefixMode`, `branchPrefixCustom`, `worktreeBaseDir`) are host-wide and written through the local host service, so the desktop app or `superset start` must be running for those. List every settable key with its current value, default, and allowed values. `isSet: false` means the app is using its built-in default. ```bash superset settings list ``` Print the effective value of one setting (falls back to the app default when unset). ```bash superset settings get terminalFontSize ``` Set a setting. Booleans accept `true/false/on/off/1/0/yes/no`; enums and numeric ranges are validated the same way the desktop settings UI validates them. ```bash superset settings set confirmOnQuit false superset settings set terminalFontSize 16 superset settings set defaultEditor cursor superset settings set selectedRingtoneId ping ``` Reset a setting to the app default. ```bash superset settings reset terminalFontSize ``` List available themes: `system` (follows OS appearance), the built-ins (`dark`, `light`, `monokai`, `catppuccin-latte`, `solarized-light`, `vellum`), and any custom themes imported through the app. ```bash superset settings theme list ``` Print the active theme. ```bash superset settings theme get ``` Export a theme's full JSON definition, the starting point for creating a custom theme: export a built-in, edit the colors, then import it. ```bash superset settings theme export dark --out my-theme.json ``` Import custom themes, using the same validation and normalization as the desktop's Appearance UI (ids are slugified; missing colors are filled from the built-in base theme; reserved ids like `dark` are rejected). Re-importing an id replaces that custom theme. ```bash superset settings theme export dark --out my-theme.json # edit my-theme.json (id, name, ui/terminal/editor colors) superset settings theme import my-theme.json superset settings theme set my-theme ``` Remove a custom theme. If it was the active theme (or a system light/dark mapping), that reference falls back to the default. ```bash superset settings theme remove my-theme ``` Set the active theme and/or the system light/dark mappings. A running desktop app restyles live; without one the theme applies on next launch. (On app versions without live reload, quit the app first, then set, then relaunch, or the app may overwrite the change.) ```bash superset settings theme set monokai superset settings theme set system --system-light light --system-dark monokai ``` *** ### completion [#completion] Shell completion for bash and zsh, generated from the installed version's command tree, so it never drifts from what the binary accepts. Prints the script to stdout, byte for byte, in every output mode: `--json`, `--quiet` and agent environments do not wrap it. The script completes command names at every level and walks through an alias already typed (`superset ws cr`), each command's flags and their aliases, enum values for flags (`--priority=u` included) and arguments, and the global options. ```bash # This shell session source <(superset completion zsh) eval "$(superset completion bash)" # bash 3.2 (macOS's /bin/bash) cannot source a process substitution # Every session: put the line above in ~/.zshrc or ~/.bashrc, or for zsh # install the script on fpath so compinit autoloads it superset completion zsh > ~/.zfunc/_superset # with fpath=(~/.zfunc $fpath) before compinit ``` ### schema [#schema] Prints every command, option and argument as JSON, for tooling that must not parse `--help`. Commands hidden from this run (internal-only, or unavailable in a cloud workspace) are left out, as they are from `--help`. Commands and options are sorted and absent fields are omitted, so the output of two versions diffs cleanly. ```bash superset schema | jq '.commands[] | select(.path == ["terminals"]) | .commands[].path' ``` ```ts { name: "superset"; version: string; globalOptions: SchemaOption[]; commands: SchemaCommand[]; } // SchemaCommand { path: string[]; // e.g. ["terminals", "read"] description?: string; aliases?: string[]; options: SchemaOption[]; args: SchemaArg[]; commands: SchemaCommand[]; // empty for a leaf command } // SchemaOption { name: string; // flag name without the dashes aliases: string[]; type: "string" | "number" | "boolean"; required: boolean; description?: string; default?: unknown; enum?: string[]; variadic?: true; int?: true; min?: number; max?: number; env?: string; // environment variable that can supply the value } // SchemaArg { name: string; required: boolean; description?: string; enum?: string[]; variadic?: true; } ``` ### config [#config] Inspect the CLI's local config file: `config.json` under `~/.superset`, or under `$SUPERSET_HOME_DIR` when that is set. Validates the file before a hand edit or a bad restore surfaces as a confusing auth failure: JSON syntax, the shape of `auth`, `apiKey` and `organizationId`, an expired token, and keys this version does not read. An error exits 1; a warning does not. A missing file is not an error, it only means nobody has logged in yet. ```bash superset config check superset config check --json ``` ```ts { path: string; exists: boolean; valid: boolean; // false when any issue is an error loggedIn: boolean; // the file holds a usable credential issues: { severity: "error" | "warning"; message: string }[]; } ``` *** ## Output modes [#output-modes] **JSON mode** (`--json`): raw payloads. Lists print arrays, get/create/update print objects, delete prints summary objects. No `{ "data": ... }` wrapper. Empty results print `null`. **Quiet mode** (`--quiet`): IDs only. Arrays of objects with an `id` field print one ID per line; single objects print their `id`; everything else falls back to JSON. When `CLAUDE_CODE`, `CLAUDECODE`, `CLAUDE_CODE_ENTRYPOINT`, `CODEX_CLI`, `GEMINI_CLI`, `SUPERSET_AGENT`, or `CI` is set to a non-empty value, output defaults to JSON unless `--quiet` is provided. --- # Environment variables Source: https://docs.paradev.com/cli/env-vars Complete reference for environment variables that control Paradev CLI behavior. The Paradev CLI supports the following environment variables to control its behavior. Set them in your shell before running `superset`, or export them from your shell profile (`~/.zshrc`, `~/.bashrc`) or your CI environment to apply them across every session. | Variable | Description | | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `SUPERSET_API_KEY` | API key (`sk_live_…` / `sk_test_…`) used in place of stored OAuth login. Equivalent to `--api-key`. | | `SUPERSET_HOME_DIR` | Directory the CLI uses for `config.json` and the host server tree. Default: `~/.superset`. Shared with the desktop app. | | `GH_TOKEN` / `GITHUB_TOKEN` | Read by the `gh` CLI the host server shells out to for PR checkout and metadata. Set this for sandboxes or CI instead of running `gh auth login` interactively. | The standalone install script also reads: | Variable | Description | | ------------------ | --------------------------------------------------------------------------------------------------- | | `SUPERSET_HOME` | Install root for the standalone CLI and host binary. Default: `~/superset`. | | `SUPERSET_VERSION` | Release tag to install. Default: `latest`, which resolves through the rolling `cli-latest` release. | --- # Getting Started Source: https://docs.paradev.com/cli/getting-started Install the Paradev CLI, sign in, and run your first commands. The CLI is currently in Beta. Commands and flags are still evolving. Make sure you're on the latest version of the CLI if you run into issues. The Paradev CLI (`superset`) is a single static binary that drives the same backend as the desktop app. Use it to manage workspaces, tasks, automations, and the local host server from your terminal or from CI. `paradev` is an alias for `superset`: every install below puts both on `PATH`, and either name runs the same binary. ## Install [#install] ### Desktop app [#desktop-app] The desktop app includes the Paradev CLI. When the app launches, it writes app-managed shims at `~/.superset/bin/superset` and `~/.superset/bin/paradev`, and Paradev terminals prepend `~/.superset/bin` to `PATH` automatically. To use the bundled CLI from a normal shell, add the directory to your shell profile: ```bash export PATH="$HOME/.superset/bin:$PATH" ``` ### Standalone install [#standalone-install] ```bash curl -fsSL https://superset.sh/cli/install.sh | sh ``` The script auto-detects your platform (macOS on Apple Silicon or Intel, Linux on x64 or arm64), installs Paradev under `~/superset` by default, and adds `~/superset/bin` to your shell `PATH`. ### Homebrew [#homebrew] ```bash brew install paradevai/tap/superset ``` ## Sign in [#sign-in] ```bash superset auth login ``` The CLI starts a loopback callback server on `127.0.0.1:51789` (or `51790` through `51793` if earlier ports are busy), opens your browser to the consent page, and stores a session token at `~/.superset/config.json`. If you belong to multiple organizations, you'll be prompted to pick one. To skip the prompt and pick directly: ```bash superset auth login --organization acme ``` For CI or other non-interactive environments (where there's no browser to complete the OAuth flow), use an API key instead. You can either store it once with `auth login --api-key`: ```bash superset auth login --api-key sk_live_… superset auth whoami ``` …or set `SUPERSET_API_KEY` per-invocation without writing anything to disk: ```bash export SUPERSET_API_KEY=sk_live_… superset auth whoami ``` API keys are issued from the **Settings → API Keys** page in the desktop app. ## Verify your session [#verify-your-session] ```bash superset auth whoami ``` ```text Signed in as Satya Patel (you@example.com) Organization: Acme Auth: Session (expires in 32 min) ``` ## Explore interactively [#explore-interactively] Bare `superset` in a terminal opens an interactive command browser: arrow-key through the commands, read their flags, and fill in required inputs with guided prompts. The confirmation screen shows the exact command before running it. `superset --help` prints the same catalog as static, grouped help. Agents and CI always get static help; the browser never opens there. The interactive command browser ## Run your first commands [#run-your-first-commands] List the projects in your organization: ```bash superset projects list ``` If your repo isn't there yet, register it on this machine. Clone from a Git URL or import an existing checkout: ```bash # Clone from a URL superset projects create --name "my-app" --local \ --clone https://github.com/org/my-app.git \ --parent-dir ~/code # Or register an existing local checkout superset projects create --name "my-app" --local --import ~/code/my-app ``` If the project already exists in your org but isn't on this machine, attach to it instead of creating a duplicate: ```bash superset projects setup --local --parent-dir ~/code ``` Then create a workspace against it: ```bash superset workspaces create \ --project prj_… \ --name "fix-login-bug" \ --branch fix/login-bug \ --local ``` Trigger an automation immediately: ```bash superset automations list superset automations run aut_… superset automations logs aut_… ``` ## Output modes [#output-modes] Every command prints a TTY-friendly view by default. Two flags switch the shape of the output for scripting: | Flag | Output | | --------- | ------------------------------------------------------------------------------------------- | | `--json` | The data payload as formatted JSON. No envelope. | | `--quiet` | One ID per line for arrays of objects with `id`; the ID for single objects; JSON otherwise. | ```bash superset tasks list --status in_progress --json | jq '.[].title' superset workspaces list --quiet | xargs -L1 superset workspaces archive ``` When the CLI detects an agent or CI environment (`CLAUDE_CODE`, `CLAUDECODE`, `CLAUDE_CODE_ENTRYPOINT`, `CODEX_CLI`, `GEMINI_CLI`, `SUPERSET_AGENT`, or `CI` set to a non-empty value), it defaults to JSON output unless you pass `--quiet`. ## Local vs. remote hosts [#local-vs-remote-hosts] Commands that touch a host accept `--host ` to pick which host handles the request, or `--local` for this machine. Local-targeted calls go straight to the host server over loopback (offline-friendly); remote calls route through the cloud API and the relay. ```bash superset hosts list superset workspaces list # this machine superset workspaces list --host h_… # another host ``` Every host-scoped command targets exactly one host. Reads (`workspaces list`, `projects list`) default to this machine; mutating host commands (`projects create`, `projects setup`, `workspaces create`) require an explicit `--host` or `--local`; there's no default. There is no org-wide listing; the desktop app is the cross-host view. ## Where state lives [#where-state-lives] ```text ~/.superset/config.json # auth, active organization ~/.superset/host//manifest.json # host server endpoint + token ~/.superset/host//host.db # local host server DB ``` `SUPERSET_HOME_DIR` relocates the whole tree, matching the desktop app. ## Next steps [#next-steps] Continue to the [CLI reference](/cli/cli-reference) for every command, flag, and output shape. --- # Host Server Source: https://docs.paradev.com/cli/host-server Set up the daemon the CLI and desktop app talk to when targeting the local machine. The `superset start` command runs a headless HTTP server that any Paradev desktop app or CLI can communicate with. It manages workspaces, ports, and agent runs on the machine it's running on. The desktop app starts it automatically; on a CLI-only or headless machine you start it yourself. If you installed the desktop app, it already includes the CLI and installs a `~/.superset/bin/superset` shim on app launch. Paradev terminals prepend that directory to `PATH` automatically. On a headless machine, use the standalone installer from [Getting Started](/cli/getting-started). ## Prerequisites [#prerequisites] `git` and `gh` need to be on your `PATH`. `git` handles clone, worktree, and branch ops; `gh` handles PR checkout and metadata. ```bash gh auth login ``` The host server reuses your existing `gh` auth. For sandboxes or CI, set `GH_TOKEN` (or `GITHUB_TOKEN`) instead of running `gh auth login`. `gh` picks it up automatically. ### Agent CLIs (optional) [#agent-clis-optional] If you plan to run AI agents inside workspaces, install whichever agent CLIs you want available. The host server launches them based on which are on your `PATH`: | Agent | Install | | ------------ | ------------------------------------------------ | | Claude Code | `npm install -g @anthropic-ai/claude-code` | | Codex | `npm install -g @openai/codex` | | Cursor Agent | install via Cursor's website | | Amp | `npm install -g @sourcegraph/amp` | | Gemini CLI | `npm install -g @google/gemini-cli` | | OpenCode | see [opencode.ai/docs](https://opencode.ai/docs) | None are required to start the host server or create workspaces. Install only what you plan to run. ## Authenticate the Paradev CLI [#authenticate-the-paradev-cli] The host server starts under your Paradev session. If you haven't already: ```bash superset auth login ``` See [Getting Started](/cli/getting-started) for the full sign-in flow, including API-key auth for CI. ## Start the host server [#start-the-host-server] ```bash superset start --daemon ``` Spawns the daemon in the background and writes a manifest at `~/.superset/host//manifest.json` so other clients can find it. Binds to `127.0.0.1` only. Verify it's healthy: ```bash superset status ``` ### Keep it updated [#keep-it-updated] Automatic updates are off by default. To turn them on, start the host with `--auto-update`: ```bash superset start --daemon --auto-update ``` * `--auto-update` requires `--daemon`. * The first check runs one hour after start, then every hour. A newer release installs, and the host restarts with its health check and rollback. Terminals reconnect after the restart. * Updates never downgrade the host. A release that fails its health check is skipped on later automatic checks; `superset update` can still install it. * The flag applies to a new start only. To change it, stop the host and start it again. If an update fails with a permission error on `superset.update-lock`, the host user cannot write the directory that contains the install. The error names the install path, the lock path, and the user. Give that user ownership of the install and its parent directory, or reinstall as that user. ### Run it under systemd [#run-it-under-systemd] On a server, let systemd start the host server at boot and restart it on failure. Run `superset start` without `--daemon` so systemd tracks the process: ```ini # /etc/systemd/system/superset-host.service [Unit] Description=Paradev host server After=network-online.target Wants=network-online.target [Service] User= ExecStart=/home//superset/bin/superset start Restart=on-failure KillMode=process [Install] WantedBy=multi-user.target ``` Keep `KillMode=process`. Other kill modes stop the terminal daemon, and with it every terminal and agent, whenever the service stops or restarts. The terminal daemon keeps running after the service stops, so the next start picks up the same terminals. This setup needs a CLI released after 1.30.2. With 1.30.2 and older, `systemctl restart` hangs until systemd kills the CLI, and the old host keeps running. ```bash sudo systemctl daemon-reload sudo systemctl enable --now superset-host ``` To end every terminal and agent too, stop the unit first, then stop the terminal daemon. If you run `superset stop` while the unit is active, systemd starts the host again. ```bash sudo systemctl stop superset-host superset stop --terminals ``` ## Getting started [#getting-started] ### Create or adopt a project [#create-or-adopt-a-project] A workspace branches off a project: a repo registered with Paradev. Each repo gets one cloud project record, shared across the organization. The first machine to register the repo runs `projects create`; every machine after that uses `projects setup` to attach to the existing project instead of creating a duplicate. Start by checking what's already in your org: ```bash superset projects list ``` #### First machine: `projects create` [#first-machine-projects-create] If the project doesn't exist yet, clone a remote repo or import an existing local one: ```bash # Clone from a Git URL superset projects create \ --name "My Project" \ --local \ --clone https://github.com/org/repo.git \ --parent-dir ~/code # Or import a repo that's already on disk superset projects create \ --name "My Project" \ --local \ --import ~/code/existing-repo ``` The host server clones (or registers) the repo, creates the cloud project record, and ensures the main workspace. #### Subsequent machines: `projects setup ` [#subsequent-machines-projects-setup-id] If a previous machine of yours already created the project, adopt it instead of running `create` again: `create` would register a second, unrelated project for the same repo. Projects are host-owned, so pick the ID from a machine that has it (`projects list --host `), then: ```bash # Clone the project's repo onto this machine superset projects setup 47c31b04-… --local --parent-dir ~/code # Or attach to an existing local checkout superset projects setup 47c31b04-… --local --import ~/code/repo ``` The URL for clone mode comes from the cloud project record, so `setup` doesn't need `--clone `. `setup` is idempotent: re-running against a project that's already set up here is a no-op. ### Create your first workspace [#create-your-first-workspace] ```bash superset projects list superset workspaces create \ --project prj_… \ --name "fix-login-bug" \ --branch fix/login-bug ``` The host server clones the project (if it isn't already on disk), creates a git worktree at the chosen branch, and registers the workspace. You can also create a workspace from a pull request number: ```bash superset workspaces create \ --project prj_… \ --name "review-pr-123" \ --pr 123 \ --local ``` ## Stop the host server [#stop-the-host-server] ```bash superset stop ``` Your terminals and agents keep running in the terminal daemon, and the next `superset start` picks them up. To end them as well: ```bash superset stop --terminals ``` ## Shared state [#shared-state] State lives under `~/.superset/host//`: ```text ~/.superset/host//manifest.json # endpoint + auth token ~/.superset/host//host.db # local host server DB ``` A host server started by the desktop app is visible to the CLI and vice-versa. `SUPERSET_HOME_DIR` relocates the whole tree. ## Command details [#command-details] For full flags, exit codes, and output shapes: * [`superset start`](/cli/cli-reference#superset-start) * [`superset status`](/cli/cli-reference#superset-status) * [`superset stop`](/cli/cli-reference#superset-stop) --- # Drive Paradev from Your Agent Source: https://docs.paradev.com/recipes/agent-driven-superset Delegate work in parallel, then make it recurring with the automate skill, without leaving the conversation you're mid-conversation with an agent and the next step is a Paradev action (fan this work out in parallel, or make it recur on a schedule) and you'd rather say so than click through the app. ## The Idea [#the-idea] Paradev ships [skills](/skills) to your coding agents automatically, so the agent in front of you already knows how to run Paradev itself. `superset:orchestrate` makes it a coordinator of parallel workers; that has [its own page](/orchestration). This recipe is about the move that follows: `superset:automate` turns anything you've asked for twice into a scheduled [automation](/automations), in the same conversation. ## Steps [#steps] 1. Delegate something splittable to the agent you're talking to: "split this migration into independent slices and run a worker on each" ([Agent Orchestration](/orchestration) covers what to ask for and how the coordination works). Review each workspace's diff as it lands. 2. When the job turns out to be recurring (a dependency sweep, a triage pass, a weekly cleanup), promote it without switching surfaces: ```text That worked. Make it a Paradev automation that runs every Monday at 7am on this project, and walk me through the first run. ``` 3. The agent writes the automation prompt, schedules it, and reviews the first run with you. From then on it's a [workspace waiting for you](/recipes/nightly-audit) instead of a task on your list. ## Variations [#variations] * **Catch up instead of fan out**: "what did my agents do overnight?" gets you a standup digest of finished, blocked, and needs-review work * **When Paradev itself misbehaves**: "diagnose why this host shows offline" has the agent fix it instead of you reading logs * The full list of shipped skills, and how they're delivered and updated, is on the [Skills](/skills) page --- # Command Your Fleet from the CLI Source: https://docs.paradev.com/recipes/command-your-fleet Read every agent's screen and broadcast follow-ups across workspaces with two shell loops several agents are running across workspaces (from a fan-out, a race, or a busy day) and you want status or course-corrections without clicking through panes. ## The Idea [#the-idea] Every terminal Paradev runs is addressable from the [CLI](/cli/getting-started): `terminals list`, `read`, and `send`. Compose them with `workspaces list` and one shell loop sweeps a whole project: every agent's screen in one scroll, or one instruction delivered to all of them. Workspaces are host-owned, and these loops target the machine you run them on. If your fleet spans hosts, add `--host ` to each command to sweep a remote host's share of it. ## Read the Whole Fleet [#read-the-whole-fleet] Print the last few lines of every terminal in every workspace of a project: ```bash superset workspaces list --project my-app --quiet | while read ws; do superset terminals list --workspace "$ws" --json 2>/dev/null \ | jq -r '.sessions[].terminalId' | while read t; do echo "=== $ws / $t ===" superset terminals read --workspace "$ws" --terminal "$t" --max-lines 5 --json | jq -r '.text' done done ``` `--quiet` prints one workspace ID per line; the inner loop asks each workspace for its live sessions. Raise `--max-lines` when you want more than a glance. ## Broadcast a Follow-Up [#broadcast-a-follow-up] Send the same instruction to every running agent in the project: ```bash superset workspaces list --project my-app --quiet | while read ws; do superset terminals list --workspace "$ws" --json 2>/dev/null \ | jq -r '.sessions[].terminalId' | while read t; do superset terminals send --workspace "$ws" --terminal "$t" \ --text "Status check: summarize what you have done and what remains in 2 sentences." done done ``` Follow with the read loop a minute later to collect the answers. One caveat: `send` delivers to *every* terminal, including plain shells, where the text just lands at the prompt. Broadcast when the fleet is all agents, or filter by workspace name first (`workspaces list --search worker- --quiet`). ## Clean Up When You're Done [#clean-up-when-youre-done] ```bash superset workspaces list --project my-app --quiet | xargs -L1 superset workspaces archive ``` Archives every listed workspace (the project's `main` workspace cannot be archived). An archived workspace loses its uncommitted changes. Filter with `--search` to target only the fleet you launched. ## Variations [#variations] * **Scope by name**: prefix fleet workspaces (`worker-1`, `race-claude`) at creation, then drive only them with `workspaces list --search worker- --quiet` * **Let an agent do this**: the [`superset:orchestrate` skill](/orchestration) runs these same loops for you; monitoring workers and delivering follow-ups is exactly how it coordinates * **Watch continuously**: wrap the read loop in `watch -n 30` for a poor-man's fleet dashboard --- # Fan Out a Big Refactor Source: https://docs.paradev.com/recipes/fan-out-refactor Split a large change into independent slices and run one workspace per slice a refactor is too big for one PR: a rename that touches 200 files, a library migration, deleting a deprecated pattern across the codebase. ## The Idea [#the-idea] The failure mode of big refactors is one giant branch that rots while it waits for review. Instead: delegate in workspaces, integrate through small PRs. Slice the work so each piece can merge independently, then run one agent per slice. One workspace per slice, integrated as small PRs ## Steps [#steps] 1. **Plan the slices first.** In a scratch workspace, have an agent do the survey: ```text We're migrating from moment to date-fns. Find every usage and propose a split into 3-6 slices that can each merge independently, in any order. For each slice: name, files touched, and any shared prep work that must land first. Don't change anything yet. ``` 2. If the plan names shared prep (a compat helper, a codemod script), run that slice first and merge it before fanning out. 3. Press **⌘N** once per slice. Same prompt template, one slice each: ```text Migrate the files in [slice] from moment to date-fns, per the plan below. Only touch files in your slice. Run the affected tests before finishing. [paste the slice plan] ``` 4. Review each workspace's diff as it finishes and open a PR per slice from the diff viewer. Small PRs merge fast; that's the point. 5. Delete each workspace as its PR merges. ## Why Slices Must Be Independent [#why-slices-must-be-independent] Two agents editing the same file on different branches means merge conflicts, and you inherit them. The planning step exists to make slice boundaries follow file boundaries. If two slices genuinely overlap, merge them into one workspace. ## Variations [#variations] * **Race the risky slice**: if one slice is much harder than the rest, [race two agents on it](/recipes/race-agents) while the easy slices run * **Rolling fan-out**: for very large migrations, keep 2-3 slice workspaces active and start the next slice as each PR merges, instead of opening all of them at once * **From the CLI**: once the plan names the slices, launch every worker in one paste: ```bash for slice in api cli web; do superset workspaces create --project \ --name "migrate-$slice" --branch "migrate/$slice" --local \ --agent claude \ --prompt "Migrate the $slice slice from moment to date-fns, per plan.md. Only touch files in your slice. Run the affected tests before finishing." done ``` --- # Wake Up to a Finished Audit Source: https://docs.paradev.com/recipes/nightly-audit Schedule an agent to audit your repo overnight and review the results over coffee there's recurring maintenance work nobody prioritizes during the day: dependency updates, dead code, TODO triage, security sweeps. ## The Idea [#the-idea] [Automations](/automations) run an agent session on a schedule, and the output is a real workspace you can open, review, and continue. Schedule the boring sweep for 3 AM; your morning job is just reviewing a diff. ## Steps [#steps] 1. Go to **Automations → New automation**. 2. Pick the project, this device, an agent, and a daily schedule: `FREQ=DAILY;BYHOUR=3;BYMINUTE=0`. 3. Write a prompt that produces a reviewable diff and is safe to re-run: ```text Audit this repo's dependencies. Find outdated packages with known vulnerabilities or major-version lag. Apply the safe minor/patch updates, run the test suite, and revert anything that breaks it. Write a summary of what you updated and what needs a human decision to AUDIT.md. If a previous audit branch already covered today's findings, stop. ``` 4. In the morning, open the run from the automation's detail page. Each run in "new workspace" mode gets a fresh workspace from the project's repo. 5. Review the diff, read `AUDIT.md`, commit and open a PR, or discard by deleting the workspace. The Automations list ## Prompt Rules for Unattended Runs [#prompt-rules-for-unattended-runs] * **Idempotent**: delivery is at-least-once, so a rare double-dispatch must be harmless. "Stop if already done" costs one sentence. * **Self-verifying**: "run the tests, revert what breaks" is the difference between a reviewable diff and a mess * **Escalate, don't guess**: anything requiring judgment goes in the summary file, not the diff ## Variations [#variations] * **Weekly instead of nightly**: `FREQ=WEEKLY;BYDAY=MO;BYHOUR=3;BYMINUTE=0` for lower-churn repos * **Rotate the sweep**: separate automations for deps (Monday), dead code (Wednesday), TODO triage (Friday); one prompt per automation * **Test it now**: use **Run now** on the detail page instead of waiting for 3 AM ```bash superset automations create --name "Nightly audit" \ --rrule "FREQ=DAILY;BYHOUR=3;BYMINUTE=0" \ --project --prompt-file prompt.md --agent claude superset automations run ``` Or create it and fire the first run in one pipe: ```bash superset automations create --name "Nightly audit" \ --rrule "FREQ=DAILY;BYHOUR=3;BYMINUTE=0" \ --project --prompt-file prompt.md --agent claude \ --json | jq -r '.id' | xargs -I{} superset automations run {} ``` --- # Run Three Workstreams at Once Source: https://docs.paradev.com/recipes/parallel-workstreams A feature, a bugfix, and a PR review in parallel without branch juggling your day is a mix of unrelated work: something to build, something to fix, something to review. This is the everyday shape of parallel work, no racing involved. ## The Idea [#the-idea] Each workstream gets its own workspace, so switching between them is a click, not a stash-checkout-rebuild cycle. Agents keep making progress on the streams you're not looking at. Every workstream is a workspace with its own branch ## Steps [#steps] 1. **Feature** (⌘N → new branch): prompt an agent with the feature task and let it run. ```text Build the CSV export button on the reports page. Match the existing export patterns in this codebase. Stop and ask before adding dependencies. ``` 2. **Bugfix** (⌘N → new branch): paste the bug report as the prompt. ```text Users report the login form clears on validation errors. Reproduce it, find the root cause, and fix it. Include the repro steps in your final message. ``` 3. **Review** (⌘N → pull request): link the PR by number, title search, or URL. Read the diff in the **Changes** tab, run the branch locally with the **Run** button, and leave your review on GitHub. 4. Rotate your attention to whichever workspace needs you. The sidebar shows agent status, ahead/behind counts (**↑N**/**↓N**), and PR checks on hover. 5. As each stream lands: commit and push from the diff viewer, then delete the workspace. ## Tips [#tips] * Descriptive branch names (`feature/csv-export`, `fix/login-clear`) keep the sidebar readable at a glance * The review workspace is fully functional: if the PR needs a small fix, make it there and push rather than writing a comment * Never work directly on `main`; the whole model assumes every stream is a branch ## Variations [#variations] * **Interrupt-driven days**: keep one empty "incident" workspace pattern in mind. When something urgent lands, ⌘N and delegate it without disturbing the other streams. * **More than three**: nothing special happens at four or five streams; the limit is your review attention, not the tool. --- # Clear PR Feedback in the Background Source: https://docs.paradev.com/recipes/pr-feedback An agent addresses review comments on your PR while you work on something else a PR comes back with review comments that are legitimate but mechanical: rename this, add a test for that, handle the nil case. ## The Idea [#the-idea] Addressing review feedback is high-interruption, low-creativity work. Create a workspace from the PR, hand the comments to an agent, and stay in whatever you were doing. PR checks and changes in the diff viewer ## Steps [#steps] 1. Press **⌘N** and choose **Pull request**. Search by title or number, or paste the PR URL. 2. Prompt an agent to work through the feedback. The `gh` CLI is already authenticated in every workspace: ```text Read all review feedback on this PR. `gh pr view --comments` misses inline code comments, so also run `gh api repos/{owner}/{repo}/pulls/{pr}/comments --paginate` with this repo's owner/name and this PR's number. Address each comment: make the change, or reply explaining why not. Commit with one commit per comment, referencing it. Do not force-push. Summarize what you changed and what you pushed back on in your final message. ``` 3. Get notified when it finishes. Check the **Changes** tab to review what was done against each comment before it re-requests review. 4. Push from the diff viewer if the agent didn't, and re-request review on GitHub. 5. Delete the workspace once the PR merges. ## Tips [#tips] * Hover the workspace in the sidebar to watch review status and CI checks without opening GitHub * "One commit per comment" keeps the reviewer's second pass trivial * If a comment requires a judgment call, the agent should punt: telling it to reply rather than guess is what makes this safe to run unattended ## Variations [#variations] * **Teammate's PR**: same recipe works on any PR you can push to, not just your own * **CI fixups**: replace the prompt with "CI is failing on this PR; read the failing check logs with `gh`, fix the failures, and push" --- # Race Agents on One Task Source: https://docs.paradev.com/recipes/race-agents Run the same prompt across multiple agents and merge the best result the task is self-contained, you're not sure which approach (or agent) will do it best, and reviewing three diffs is cheaper than iterating on one. ## The Idea [#the-idea] Agent output varies a lot between attempts and between agents. Instead of prompting, reviewing, and re-prompting one agent serially, run the attempts in parallel on isolated branches and pick the winner. Two agents working the same task in isolated workspaces ## Steps [#steps] 1. Press **⌘N** three times. Same prompt each time, different agent each time (or the same agent three times: variance alone makes racing worth it). 2. Keep **Auto-run command** on so each agent starts immediately. 3. Write the prompt once and reuse it verbatim. End it with a self-report so comparison is fast: ```text Add rate limiting to the public API endpoints. Use the middleware pattern already in this codebase. In your final message, list the files you changed and any tradeoffs you made. ``` 4. Do something else. Notification sounds tell you when each agent finishes. 5. Open each workspace's **Changes** tab. Focus mode (target icon) makes stepping through a diff file-by-file fast. 6. Ship the winner: stage, commit, push, **Create PR** from the diff viewer. 7. Before deleting the losers, skim their diffs for ideas the winner missed. Select and copy any lines worth keeping. 8. Delete the losing workspaces. ## Picking a Winner Quickly [#picking-a-winner-quickly] * Read the final messages first; disqualify anything that misunderstood the task before reading diffs * Prefer the smallest diff that fully does the job * Run the test suite in the winner's terminal before you push ## Variations [#variations] * **Two agents, two approaches**: same agent, but prompt one toward each design ("use middleware" vs "use a decorator") when you're unsure which is right * **Best-of-N on hard bugs**: for a bug that has resisted one agent, three fresh attempts beat continuing a stuck session * **From the CLI**: write the prompt to `prompt.md`, then start the whole race in one paste, one workspace per agent with the same prompt: ```bash for agent in claude codex opencode; do superset workspaces create --project \ --name "race-$agent" --branch "race/$agent" --local \ --agent "$agent" --prompt "$(cat prompt.md)" done ``` --- # Review Pull Requests When Your Review Is Requested Source: https://docs.paradev.com/recipes/review-requested-prs An agent reviews a pull request when someone requests your review you get many review requests and want the agent to check each pull request for bugs, missing tests, and risky changes before you read it. ## The Idea [#the-idea] A GitHub **Review requested** trigger starts a run when someone asks you to review a pull request. The agent gets the pull request in its prompt, and the run's workspace checks out its branch, so it can read and run the code. ## Steps [#steps] 1. Connect GitHub under **Integrations**, including your personal GitHub account. A trigger that filters by **Me** doesn't fire without it. 2. Go to **Automations → New automation**. Pick the project linked to the repository, a device that stays online, and an agent. 3. Under **Triggers**, click **Add Trigger → GitHub → Pull request… → Review requested**. Set the sentence to "Review requested from **Me** in **your repository** by **Anyone**", then press **Save**. 4. Write a prompt that leaves comments and stops there: ```text You were asked to review the pull request in the event above. The branch is checked out. Read the description and every changed file. Run the tests that cover the changed code. Post one review with `gh pr review --comment --body-file review.md`: bugs first, then missing tests, then risky changes. Quote file and line for each point. Skip style nits. Do not approve, request changes, push, or merge. If you already posted a review on this pull request's latest commit, stop. ``` 5. When a request comes in, open the run from **Run History** to see what the agent checked, then read its review on GitHub before you write yours. ## Tips [#tips] * **Comment, don't approve**: `--comment` keeps the decision with you. The agent's review shows up as yours, because `gh` uses your account. * **No loop**: the agent's own review doesn't request a review, so it doesn't start another run. If you also add a **Comment added** trigger, filter it by people so the agent's comments don't fire it. * **Forks**: GitHub triggers skip pull request events from forks, so reviews requested on fork pull requests don't start a run. * **Offline device**: a request that comes in while the device is offline is a missed run, and it isn't retried. Use **Run now** on the detail page to review it later. ## Variations [#variations] * **Review every new pull request**: use **Pull request… → Opened** instead, with **Anyone** as the author. * **Re-review after pushes**: add a second trigger, **Pull request… → Pushed**, scoped to the same repository. --- # Triage New Sentry Issues Source: https://docs.paradev.com/recipes/sentry-triage An agent reproduces each new Sentry error and opens a draft pull request with a fix Sentry gets more new errors than your team has time to look at, and most of them are small bugs with a clear stack trace. ## The Idea [#the-idea] A Sentry **Issue created** trigger starts a run for each new issue. The agent gets the issue's title, link, and event payload in its prompt, finds the code in the stack trace, reproduces the bug in a test, and opens a draft pull request. ## Steps [#steps] 1. Connect Sentry under **Integrations**. 2. Go to **Automations → New automation**. Pick the project for the repository the Sentry project reports from, a device that stays online, and an agent. 3. Under **Triggers**, click **Add Trigger → Sentry → Issue created**. Pick the Sentry project and set the level to **Error** and **Fatal**, so warnings don't start runs. Press **Save**. 4. Write a prompt that proves the bug before it fixes it: ```text A new Sentry issue is in the event above. Find the code in its stack trace. Write a failing test that reproduces the error. If you can't reproduce it, stop and write what you found to TRIAGE.md. If you can, fix it, run the test suite, and open a draft pull request with `gh pr create --draft`. Link the Sentry issue in the description, and say what caused the error and how the test proves the fix. If a pull request for this Sentry issue already exists, stop. ``` 5. Open the run from **Run History**, read `TRIAGE.md` or the draft pull request, and mark it ready for review when you agree. ## Tips [#tips] * **Reproduce first**: a failing test shows that the fix works. Without one, you cannot tell. * **Draft only**: `--draft` keeps CI and reviewers out until you have looked at it. * **Duplicates**: the same event can be delivered twice. The "already exists" check stops the second run. ## Variations [#variations] * **Regressions**: use **Issue unresolved** to catch a bug that came back after it was marked resolved. * **Assign to the agent**: use **Issue assigned** so only the issues someone hands over start a run. --- # Fix Bugs Reported in Slack Source: https://docs.paradev.com/recipes/slack-bug-reports An agent investigates each bug report posted in a Slack channel people report bugs in a channel like #bugs, and each report starts with the same work: find the code and reproduce the bug. ## The Idea [#the-idea] A Slack **Message in channel** trigger starts a run for each new message in the channels you pick. The agent gets the message text, who posted it, and a link to it in its prompt, so it starts from the report itself. ## Steps [#steps] 1. Connect Slack under **Integrations**. 2. Go to **Automations → New automation**. Pick the project, a device that stays online, and an agent. 3. Under **Triggers**, click **Add Trigger → Slack → Message in channel** and pick the channel. Press **Save**. The Paradev bot joins public channels when you save. For a private channel, invite **@Paradev** to it first. 4. Optional: set the message filter to a word your team puts in reports, like `bug`, so other messages don't start runs. 5. Write a prompt that works from the report: ```text A bug report was posted in Slack; it's in the event above. Find the code it's about and try to reproduce it with a test. If you reproduce it, fix it, run the test suite, and open a draft pull request with `gh pr create --draft` that quotes the report and links the Slack message. If you can't, write what you checked and what you need from the reporter to TRIAGE.md. Do not guess at a fix. ``` 6. Open the run from **Run History** to read the result, and reply to the reporter with the pull request or the questions in `TRIAGE.md`. ## Tips [#tips] * **Top-level messages only**: thread replies don't fire **Message in channel**, so a discussion under a report doesn't start more runs. * **Bot messages**: Slack triggers ignore the Paradev bot's own messages and reactions. * **Reply in Slack**: to have the agent answer in the thread itself, give it a Slack tool it can call, such as a Slack MCP server set up for your agent. ## Variations [#variations] * **Opt in with an emoji**: use **Reaction added** with an emoji like `:bug:` on any message, so people choose which reports the agent picks up. --- # Start a Run with a Webhook Source: https://docs.paradev.com/recipes/webhook-runs Use a webhook trigger to start an agent from CI, a deploy script, or any tool that can send a POST the event comes from a tool Paradev doesn't connect to: a failed deploy, a CI job, an alert, a form, or your own script. ## The Idea [#the-idea] A **Webhook triggered** trigger gives the automation a URL. Every POST to it starts a run, and the JSON body you send goes into the agent's prompt. Put the details the agent needs in the body and refer to them in the prompt. ## Steps [#steps] 1. Go to **Automations → New automation**. Pick the project, a device that stays online, and an agent. 2. Under **Triggers**, click **Add Trigger → Webhook triggered** and press **Save**. 3. Click **Generate token**, then **Copy URL with token** or **Copy auth header**. The token starts with `sset_wh_` and is shown once, so store it as a secret in the service that calls the URL. 4. Write a prompt that reads the body: ```text A deploy failed; the webhook body above has the service, the commit, and a link to the logs. Read the logs with the link, find the cause, and fix it on a new branch. Run the tests and open a draft pull request with `gh pr create --draft` that links the logs. If the failure is in infrastructure, not code, write what you found to DEPLOY.md and stop. ``` 5. Call the URL from your service: ```bash curl -X POST "https://api.superset.sh/api/automations/webhook/" \ -H "Authorization: Bearer $SUPERSET_WEBHOOK_TOKEN" \ -H "Content-Type: application/json" \ -d '{"service": "checkout", "commit": "4f2a9c1", "logs": "https://ci.example.com/runs/812"}' ``` ## Tips [#tips] * **Body**: a JSON object or array up to 1 MiB. An empty body counts as `{}`. * **Every POST is a run**: webhook triggers have no filters and no de-duplication, so send only the events you want a run for. * **Responses**: `200` when the delivery is accepted, `400` if the automation is paused or the body isn't JSON, `401` for a missing or invalid token, `413` for a body over 1 MiB, `429` past 300 requests per minute. * **Rotate**: **Regenerate token** replaces the token, and the old one stops working immediately. ## Variations [#variations] * **From GitHub Actions**: add a final step with `if: failure()` that runs the `curl` above, with the token in a repository secret. --- # Advanced Usage Source: https://docs.paradev.com/sdk/advanced Real-world recipes that combine the SDK's primitives (webhooks, triage scripts, and on-demand agents). The SDK is in early alpha. It is not meant for production use and may be removed in the future. Stay on the latest version (`@superset_sh/sdk@latest`) while we iterate. The SDK's individual methods are simple. The interesting part is what you compose them into. These are end-to-end recipes you can copy as starting points. ## Sentry webhook → agent on the bug [#sentry-webhook--agent-on-the-bug] When Sentry fires an alert, file a task and spawn an agent to investigate, all in two SDK calls. (In production, verify the Sentry signature header before trusting any payload. That part is omitted here for clarity.) ```ts title="sentry-webhook.ts" import { Hono } from 'hono'; import Superset from '@superset_sh/sdk'; const app = new Hono(); const client = new Superset(); // reads SUPERSET_API_KEY + SUPERSET_ORGANIZATION_ID from env const TARGET_HOST_ID = process.env.SUPERSET_TARGET_HOST_ID!; // see hosts.list() const PROJECT_ID = process.env.SUPERSET_PROJECT_ID!; // see projects.list() app.post('/webhooks/sentry', async (c) => { const event = await c.req.json(); const { title, web_url: sentryUrl, culprit, short_id } = event.data.issue; const slug = `sentry-${short_id.toLowerCase()}`; // 1. File a task so the bug shows up in the dashboard const task = await client.tasks.create({ title: `[Sentry] ${title}`, description: `Triggered by ${culprit}\n\nSentry: ${sentryUrl}`, priority: 'high', labels: ['sentry', 'bug'], }); // 2. Spin up a worktree on a developer's machine and dispatch an agent // inside it. The SDK creates the worktree, then runs the agent with // your prompt; you don't manage the dispatch loop. const result = await client.workspaces.create({ hostId: TARGET_HOST_ID, projectId: PROJECT_ID, name: slug, branch: slug, agents: [ { agent: 'claude', prompt: [ `A Sentry alert just fired:`, ` Title: ${title}`, ` Culprit: ${culprit}`, ` URL: ${sentryUrl}`, ``, `Reproduce the failure, fix it, push a branch, and update task`, `${task.id} with what you found.`, ].join('\n'), }, ], }); return c.json({ ok: true, taskId: task.id, workspaceId: result.workspace.id, sessionId: result.agents[0]?.ok ? result.agents[0].sessionId : null, }); }); export default app; ``` What just happened, end-to-end: * The task lives in the cloud and shows up in the dashboard for everyone. * The workspace is a real `git worktree` on the target machine, ready for a human to take over if the agent gets stuck. * The agent runs inside the new workspace, with the prompt above and access to the codebase + whatever MCP servers the host has configured. You can spawn multiple agents in parallel by adding more entries to `agents`: ```ts agents: [ { agent: 'claude', prompt: 'Reproduce the bug and write a failing test.' }, { agent: 'claude', prompt: 'Investigate related Sentry issues from the last 7 days.' }, ], ``` ## Burn down the P0 backlog overnight [#burn-down-the-p0-backlog-overnight] Pick up every urgent task in the queue and spawn an agent on each one in parallel. Comes back the next morning with a branch and a comment per task. ```ts title="burn-p0s.ts" import Superset from '@superset_sh/sdk'; const client = new Superset(); const HOST_ID = process.env.SUPERSET_HOST_ID!; const PROJECT_ID = process.env.SUPERSET_PROJECT_ID!; // see projects.list() const p0s = await client.tasks.list({ priority: 'urgent', limit: 50 }); const dispatched = await Promise.all( p0s.map((task) => client.workspaces.create({ hostId: HOST_ID, projectId: PROJECT_ID, name: task.slug, branch: task.slug, agents: [ { agent: 'claude', prompt: [ `Pick up task ${task.slug}: "${task.title}".`, ``, task.description ?? '(no description; read recent changes for context)', ``, `Investigate, make the fix, run the relevant tests, push the branch, and`, `update task ${task.id} with a one-paragraph summary of what changed and why.`, `If you can't make confident progress in ~30 minutes, leave a comment with`, `where you got stuck and stop.`, ].join('\n'), }, ], }), ), ); console.log(`dispatched ${dispatched.length} agents across the P0 backlog`); ``` Run it from a daily cron on a beefy host and you wake up to a branch per bug. Ones the agent could fix have a PR-ready branch; ones it couldn't have a comment explaining why so a human picks up where the agent stopped. ## Sweep a refactor across every repo [#sweep-a-refactor-across-every-repo] Internal API rename, dependency bump, lint rule rollout. Anything that has to land identically in dozens of repos is a one-loop, fan-out problem: ```ts title="sweep-rename-getUser.ts" import Superset from '@superset_sh/sdk'; const client = new Superset(); const HOST_ID = process.env.SUPERSET_HOST_ID!; const projects = await client.projects.list({ hostId: HOST_ID }); const wave = await Promise.all( projects.map((p) => client.workspaces.create({ hostId: HOST_ID, projectId: p.id, name: `rename-getUser-${p.name}`, branch: 'refactor/rename-getUser', agents: [ { agent: 'claude', prompt: [ `Rename every caller of \`getUser()\` to \`fetchUser()\` across this repo.`, ``, `1. Find call sites with grep.`, `2. Update each one and re-run the test suite.`, `3. If green, push the branch and open a draft PR titled`, ` "refactor: rename getUser → fetchUser".`, `4. If a repo doesn't actually use getUser, exit cleanly with a note.`, ].join('\n'), }, ], }), ), ); const totalAgents = wave.reduce( (n, result) => n + result.agents.filter((agent) => agent.ok).length, 0, ); console.log(`launched ${totalAgents} agents across ${projects.length} repos`); ``` Same loop works for "bump TypeScript to 5.7", "swap Sentry SDK for the new one", "add a `lint:strict` script to every package.json". Anything you'd otherwise farm out to a long Slack thread. ## On-demand agent dispatch from your tools [#on-demand-agent-dispatch-from-your-tools] If you've already created a recurring automation in the dashboard, the SDK can fire it off-schedule from anywhere (a Slack slash command, a CI job, an internal admin panel): ```ts const run = await client.automations.run(''); console.log(`dispatched run ${run.runId} for automation ${run.automationId}`); ``` The automation's pinned host has to be online and tunneling. The SDK will surface a `503 Host not connected` error if it isn't, so you can retry later or page someone. --- # Getting Started Source: https://docs.paradev.com/sdk/getting-started Drive Paradev programmatically from any TypeScript or JavaScript codebase. The SDK is in early alpha. It is not meant for production use and may be removed in the future. Stay on the latest version (`@superset_sh/sdk@latest`) while we iterate. The Paradev TypeScript SDK lets you create and manage your workspaces, tasks, projects, and automations from code. Anything you can do in the dashboard, your scripts and services can do too. A few things you might use it for: * **Bulk task management**: script the creation, triage, or cleanup of tasks across one or many projects. * **Integrations**: sync tasks to/from your CRM, issue tracker, or internal tools. * **Provisioning**: spin up workspaces on a developer's machine when an issue is opened, a PR is reviewed, or a customer ticket lands. * **On-demand agents**: kick off a recurring automation off-schedule when a webhook fires. Everything is fully typed and works in Node, Bun, and Deno. The bundle also runs in browsers, but **don't ship `sk_live_…` keys to a frontend**: they're long-lived and grant full org access. From the browser, talk to a thin server proxy that holds the key. ## Install [#install] ```bash npm install @superset_sh/sdk ``` ```bash pnpm add @superset_sh/sdk ``` ```bash yarn add @superset_sh/sdk ``` ```bash bun add @superset_sh/sdk ``` We're under active development. The SDK follows the API as it grows, so **stay on the latest version** rather than pinning. New methods get added; existing ones don't change shape without a version bump and a note in the changelog. ## Get an API key [#get-an-api-key] 1. Open the [Paradev desktop app](https://superset.sh/download) → **Settings → API Keys** → **Create**. The key starts with `sk_live_…`. Copy it now (you won't be able to see it again). 2. Note your **organization ID**. Find it in the org switcher inside the desktop app. ```bash export SUPERSET_API_KEY=sk_live_… export SUPERSET_ORGANIZATION_ID=… ``` ## Create the client [#create-the-client] ```ts import Superset from '@superset_sh/sdk'; const client = new Superset(); // reads SUPERSET_API_KEY and SUPERSET_ORGANIZATION_ID from env ``` That's all the setup. From here, every resource works the same way: ```ts // Create a task const task = await client.tasks.create({ title: 'Wire up auth', priority: 'high', }); // Update it await client.tasks.update({ id: task.id, statusId: '' }); // Look one up by id or slug const got = await client.tasks.retrieve('SUPER-172'); // returns null if missing // Find tasks with rich filters const urgent = await client.tasks.list({ priority: 'urgent', search: 'auth', creatorMe: true, }); // Inspect what else you have: projects and workspaces are host-owned const [host] = await client.hosts.list(); if (!host) throw new Error('No hosts registered; run `superset start` on a machine'); const projects = await client.projects.list({ hostId: host.id }); const automations = await client.automations.list(); // Trigger an automation off-schedule await client.automations.run(''); // Create a workspace on a developer's machine await client.workspaces.create({ hostId: '', projectId: '', name: 'fix-auth-bug', branch: 'fix/auth', }); ``` See the [reference](/docs/sdk/reference) for every method, parameter, and return type. ## Configuration [#configuration] You can configure the client explicitly instead of (or alongside) the env vars: ```ts const client = new Superset({ apiKey: 'sk_live_…', organizationId: '…', timeout: 60_000, // default: 60s per request maxRetries: 2, // default: 2 retries with exponential backoff logLevel: 'warn', // 'off' | 'error' | 'warn' | 'info' | 'debug' }); ``` The client retries automatically on network errors and 429/5xx responses, so transient failures usually fix themselves. ## Handling errors [#handling-errors] The SDK throws typed errors for any non-success response, so you can catch what you actually care about: ```ts import Superset, { APIError, NotFoundError, RateLimitError } from '@superset_sh/sdk'; const client = new Superset(); try { await client.tasks.create({ title: '' }); } catch (err) { if (err instanceof RateLimitError) { // 429: already retried up to maxRetries; back off further if you keep hitting it } else if (err instanceof NotFoundError) { // 404 } else if (err instanceof APIError) { // anything else: err.status, err.headers, err.error (the parsed body) console.error(`Paradev returned ${err.status}:`, err.error); } } ``` ## Next [#next] Head to the [reference](/docs/sdk/reference) for the complete surface. --- # Paradev SDK Reference Source: https://docs.paradev.com/sdk/reference Method-by-method reference for the Paradev TypeScript SDK. The SDK is in early alpha. It is not meant for production use and may be removed in the future. Stay on the latest version (`@superset_sh/sdk@latest`) while we iterate. ## Client [#client] ```ts import Superset from '@superset_sh/sdk'; const client = new Superset({ apiKey: 'sk_live_…', organizationId: '…', // optional: baseURL: 'https://api.superset.sh', relayURL: 'https://relay.superset.sh', timeout: 60_000, maxRetries: 2, logLevel: 'warn', // 'off' | 'error' | 'warn' | 'info' | 'debug' }); ``` ### Telemetry [#telemetry] The SDK reports one `sdk_method_called` event per resource call: the method name (for example `tasks.list`), SDK version, runtime, whether the call succeeded, and how long it took. Request and response data are never included. The report is sent after your call settles and is best-effort, so it cannot slow down or fail a call. Set `SUPERSET_TELEMETRY=0` to turn it off. *** ## tasks [#tasks] ### `tasks.create(body)` [#taskscreatebody] Create a task. ```ts const task = await client.tasks.create({ title: 'Wire up auth', description: 'See SUPER-100', priority: 'high', // 'urgent' | 'high' | 'medium' | 'low' | 'none' assigneeId: '', // optional statusId: '', // optional, defaults to first backlog status estimate: 4, // optional, story points dueDate: '2026-12-31', // optional, ISO date labels: ['bug'], // optional }); ``` Returns a `Task`. ### `tasks.list(params?)` [#taskslistparams] List tasks with rich filters. All filters AND-combine. ```ts const tasks = await client.tasks.list({ assigneeMe: true, // tasks assigned to you creatorMe: true, // tasks you created priority: 'high', statusId: '', assigneeId: '', // someone else's tasks search: 'auth', // substring of title labels: ['acme'], // all must match; 'acme' also matches 'acme/web' limit: 50, // max 500 offset: 0, }); ``` Returns `Array`. Each row is a `Task` denormalized with `assigneeName`, `assigneeImage`, `creatorName`, `creatorImage`, and `statusName` so you don't need follow-up calls for display. ### `tasks.retrieve(idOrSlug)` [#tasksretrieveidorslug] Look up a single task by id or slug. ```ts const task = await client.tasks.retrieve('SUPER-172'); if (!task) throw new Error('not found'); // returns null when missing ``` Returns `Task | null`. ### `tasks.update(body)` [#tasksupdatebody] Patch a task. ```ts const task = await client.tasks.update({ id, priority: 'urgent', statusId: '', prUrl: 'https://github.com/…', }); ``` Returns the updated `Task`. ### `tasks.delete(id)` [#tasksdeleteid] Soft-delete a task. ```ts await client.tasks.delete(id); ``` ### `tasks.statuses.list()` [#tasksstatuseslist] List the task statuses (workflow states) configured for the active organization, in display order. Useful for resolving status ids before [`tasks.create`](#taskscreatebody) or [`tasks.update`](#tasksupdatebody). ```ts const statuses = await client.tasks.statuses.list(); const todo = statuses.find((s) => s.type === 'unstarted'); ``` Returns `Array`. Each entry is `{ id, name, color, type, position }`. *** ## workspaces [#workspaces] ### `workspaces.list({ hostId, projectId?, search? })` [#workspaceslist-hostid-projectid-search-] List workspaces on a host. Workspaces are host-owned. There is no org-wide listing; enumerate hosts with [`hosts.list()`](#hostslist) and query each one you care about. ```ts const workspaces = await client.workspaces.list({ hostId: '' }); ``` Returns `Array`. Rows include the host-served `projectName` (`string | null`; null when the workspace's project row is missing on that host, so don't assume it's always present). ### `workspaces.create({ hostId, projectId, name, branch?, pr?, baseBranch?, taskId?, agents?, command? })` [#workspacescreate-hostid-projectid-name-branch-pr-basebranch-taskid-agents-command-] Create a worktree on a specific host. Provide exactly one of `branch` or `pr` (a pull request number; the host checks out the verified PR head and derives the branch). `baseBranch` picks the fork point when `branch` doesn't exist yet, and `taskId` links the new workspace to a task. Optionally spawn one or more agents inside it as soon as the worktree is ready, and/or run a one-off shell `command` in the worktree. Goes through the relay tunnel: the host must be online. Each entry in `agents` takes a preset id (e.g. `"claude"`) or a `HostAgentConfig` instance UUID: the host service resolves it against its configured rows and copies their stored `command`, `args`, and `env`. Set `model` or `effort` to override the agent's model or reasoning effort for that launch, or omit them to use the agent's own defaults. Use [`agents.list({ hostId })`](#agentslist-hostid-) to enumerate what's installed. `command` is independent of `agents`. Pass either or both. ```ts const result = await client.workspaces.create({ hostId: '', // see hosts.list() projectId: '', // see projects.list() name: 'wire-up-auth', branch: 'feat/auth', agents: [ // optional: spawn agents on creation { agent: 'claude', model: 'sonnet', effort: 'high', prompt: 'Implement the auth flow described in SUPER-100.' }, { agent: 'claude', prompt: 'Write integration tests for the new auth flow.' }, ], }); console.log(result.workspace.id); for (const agent of result.agents) { if (agent.ok) console.log(agent.kind, agent.sessionId, agent.label); else console.error(agent.error); } ``` Returns a `WorkspaceCreateResult`: * `workspace`: the created workspace row (`id`, `name`, `branch`, `hostId`, `projectId`, `type`, `taskId`, …). * `terminals`: terminals opened on the host (`{ terminalId, label? }`). * `agents`: one entry per agent in the request (empty if `agents` was omitted). Each entry is either `{ ok: true, kind: 'terminal' | 'chat', sessionId, label }` or `{ ok: false, error }`. * `alreadyExists`: true when a workspace for that branch already existed and was reused instead of created. ### `workspaces.update(id, params, { hostId })` [#workspacesupdateid-params--hostid-] Update fields on an existing workspace on its host. Moving a workspace to a different branch or host requires host-side orchestration and is not safe to drive directly. ```ts await client.workspaces.update('', { name: 'wire-up-auth-v2' }, { hostId: '' }); ``` Returns the updated workspace row (`id`, `name`, `branch`, `hostId`, `projectId`, `type`, `taskId`, …). ### `workspaces.delete(id, { hostId })` [#workspacesdeleteid--hostid-] Delete a workspace on its host. ```ts await client.workspaces.delete('', { hostId: '' }); ``` *** ## projects [#projects] ### `projects.list({ hostId })` [#projectslist-hostid-] List projects set up on a host. Projects are host-owned; there is no org-wide project registry. ```ts const projects = await client.projects.list({ hostId: '' }); ``` Returns `Array` (`id`, `name`, `repoPath`, `repoUrl`, …). *** ## hosts [#hosts] ### `hosts.list()` [#hostslist] List developer machines registered in the org. Returns `Array` with `id` (machineId), `name`, `online`, and `organizationId`. ```ts const hosts = await client.hosts.list(); const online = hosts.filter((h) => h.online); ``` *** ## agents [#agents] Terminal-agent rows configured on a specific host (the same rows shown in Settings → Agents on that machine). Reads route through the relay tunnel: the target host must be online. ### `agents.list({ hostId })` [#agentslist-hostid-] List configured agents on a host in persisted display order. First call on a fresh host seeds the bundled defaults. Returns `Array`. Each row carries `id`, `presetId`, `label`, `command`, `args`, `env`, and prompt-transport fields used to launch the agent. ```ts const agents = await client.agents.list({ hostId: '' }); ``` ### `agents.create({ hostId, workspaceId, agent, prompt, model?, effort?, attachmentIds? })` [#agentscreate-hostid-workspaceid-agent-prompt-model-effort-attachmentids-] Create (launch) an agent session in an existing workspace on its host. `agent` accepts either a preset id (e.g. `"claude"`) or a `HostAgentConfig` instance UUID. `model` and `effort` are agent-specific launch overrides; omit them to use the agent's own configured defaults. Unsupported values for either fail before launch with a message naming the supported ids. Returns `{ kind, sessionId, label }`. ```ts const { sessionId } = await client.agents.create({ hostId: '', workspaceId: '', agent: 'claude', model: 'sonnet', effort: 'high', prompt: 'Audit the login flow for race conditions.', }); ``` *** ## terminals [#terminals] Terminal (PTY) sessions on a host, scoped to a workspace. ### `terminals.create({ hostId, workspaceId, command?, cwd? })` [#terminalscreate-hostid-workspaceid-command-cwd-] Create a terminal session in an existing workspace on its host. Pass `command` to run a one-off shell command, or omit it to open an interactive shell. Returns `{ terminalId, status }`. ```ts const { terminalId } = await client.terminals.create({ hostId: '', workspaceId: '', command: 'bun install && bun test', }); ``` *** ## automations [#automations] Recurring agent runs scheduled by RRULE. Automations are a Pro feature: `create`, `run`, and `resume` are refused with `FORBIDDEN` unless the org has a Pro or Enterprise subscription. Reading, `update`, `pause`, and `delete` stay available so a downgraded org keeps control of what it has. ### `automations.list(params?)` [#automationslistparams] ```ts const automations = await client.automations.list(); // or filter by case-insensitive substring on name: const triage = await client.automations.list({ name: 'triage' }); ``` Each row is an `AutomationSummary`: the `prompt` body is omitted (it can be large markdown). Fetch one with `automations.getPrompt(id)`. Each row includes `scheduleText`, a human-readable rendering of the rrule. ### `automations.retrieve(id)` [#automationsretrieveid] ```ts const a = await client.automations.retrieve(id); ``` Returns an `AutomationSummary` (no `prompt` body: call `getPrompt(id)`). ### `automations.create(body)` [#automationscreatebody] Create a recurring automation. ```ts const a = await client.automations.create({ name: 'Daily leads', prompt: 'Find new leads from Linear and update the CRM…', agent: 'claude', // host agent presetId, instance UUID, or 'superset' for built-in chat rrule: 'FREQ=DAILY;BYHOUR=6;BYMINUTE=0', timezone: 'America/Los_Angeles', v2ProjectId: '', // one of v2ProjectId or v2WorkspaceId required // optional: v2WorkspaceId: '', // pin to a specific workspace targetHostId: '', // pin to a specific host dtstart: new Date().toISOString(), mcpScope: ['linear', 'notion'], }); ``` ### `automations.update(body)` [#automationsupdatebody] ```ts await client.automations.update({ id, rrule: 'FREQ=WEEKLY;BYDAY=MO' }); ``` ### `automations.delete(id)` [#automationsdeleteid] ### `automations.run(id)` [#automationsrunid] Dispatch immediately, off-schedule. Goes through the relay to the automation's target host. Returns identifiers for the dispatched run, not the full run row; use [`automations.logs(id)`](#automationslogsid-params) for status. ```ts const run = await client.automations.run(id); console.log(run.automationId, run.runId); ``` ### `automations.pause(id)` / `automations.resume(id)` [#automationspauseid--automationsresumeid] Toggle the `enabled` flag. A paused automation stops running on its schedule until you resume it. ### `automations.logs(id, params?)` [#automationslogsid-params] Run history. Owner-only: returns 404 if the automation isn't owned by the calling user. ```ts const runs = await client.automations.logs(id, { limit: 20 }); ``` ### `automations.getPrompt(id)` / `automations.setPrompt(id, prompt)` [#automationsgetpromptid--automationssetpromptid-prompt] Read or replace the automation's prompt without going through the full update. *** ## organization [#organization] ### `organization.members.list()` [#organizationmemberslist] List members of the active organization. ```ts const members = await client.organization.members.list(); ``` --- # Circleback Source: https://docs.paradev.com/plugins/available/circleback Search meeting notes, action items, and transcripts from Circleback Search meeting notes, action items, and transcripts from Circleback. ## Skills [#skills] | Skill | What it does | | :----------------------------- | :-------------------------------------------------------------------------------------------------- | | `find-in-circleback` | Answers "what did we say, decide, or promise" by searching on attendee, company, tag, or date | | `prep-with-circleback` | Builds a brief for an upcoming meeting from past meetings with the same people and open commitments | | `work-circleback-action-items` | Finds the action items assigned to you, does the ones the agent can do, and updates their status | Skills are named `circleback-`. In Claude Code they appear as `superset:circleback-`. ## MCP Server [#mcp-server] Tools come from Circleback's own MCP server at `https://circleback.ai/api/mcp`. Paradev proxies each call and adds your credentials. Circleback decides which tools the server offers, so see Circleback's documentation for the current list. ## Authentication [#authentication] | Method | Details | | :-------- | :---------------------------------------------------------------------------------------------------------------------------------------- | | OAuth 2.0 | You sign in to Circleback in your browser. Paradev registers itself with Circleback when you connect, so there is no app to set up first. | Connect from the plugin's page in **Plugins**. Paradev keeps the credentials. The agent and your machine never see them. --- # GitHub Source: https://docs.paradev.com/plugins/available/github Work with issues, pull requests, and CI across your repositories Work with issues, pull requests, and CI across your repositories. ## Skills [#skills] | Skill | What it does | | :------------- | :--------------------------------------------------------------------------------------------------------------------------------- | | `ci-triage` | Finds the first real error in a failing GitHub Actions run, tells a flake from a real failure, and finds the commit that caused it | | `issue-triage` | Reproduces an issue, finds duplicates, judges severity, and sets labels, milestone, and assignee | Skills are named `github-`. In Claude Code they appear as `superset:github-`. ## MCP Server [#mcp-server] Tools come from GitHub's own MCP server at `https://api.githubcopilot.com/mcp/`. Paradev proxies each call and adds your credentials. GitHub decides which tools the server offers, so see GitHub's documentation for the current list. ## Authentication [#authentication] | Method | Details | | :-------- | :--------------------------------------------------------------------------------- | | OAuth 2.0 | Sign in to GitHub. Paradev asks for the `repo`, `read:org`, and `workflow` scopes. | Connect from the plugin's page in **Plugins**. Paradev keeps the credentials. The agent and your machine never see them. --- # Gmail Source: https://docs.paradev.com/plugins/available/gmail Read, search, send, and organize mail, drafts, labels, and filters Read, search, send, and organize mail, drafts, labels, and filters. ## Skills [#skills] This plugin adds no skills. The agent uses the tools directly. ## MCP Server [#mcp-server] Paradev hosts the tools for this plugin itself. Calls go from the Paradev API to the Gmail API with your credentials. **Access** shows what a tool does: Read changes nothing, Write creates or changes data, and Destructive deletes, removes, or sends something. | Tool | Access | What it does | | :---------------------------- | :---------- | :------------------------------------------------------------------------------------------------- | | `send_email` | Destructive | Sends a new email immediately | | `draft_email` | Write | Creates a draft email without sending it | | `read_email` | Read | Retrieves the full content of a specific email, including headers, body, and attachment references | | `read_email_thread` | Read | Retrieves every message in a thread in readable order | | `search_emails` | Read | Searches emails using Gmail search syntax | | `modify_email` | Write | Adds or removes labels on a single message, which is how mail is archived, starred, or marked read | | `delete_email` | Destructive | Permanently deletes a message | | `batch_modify_emails` | Write | Adds or removes labels on up to 1000 messages in one call | | `batch_delete_emails` | Destructive | Permanently deletes up to 1000 messages | | `get_attachment` | Read | Fetches an attachment's bytes as base64 | | `list_history` | Read | Lists mailbox changes since a history ID, for detecting what changed | | `list_drafts` | Read | Lists draft emails | | `get_draft` | Read | Retrieves a draft's full content | | `update_draft` | Write | Replaces a draft's content | | `delete_draft` | Destructive | Permanently deletes a draft | | `send_draft` | Destructive | Sends an existing draft | | `modify_thread` | Write | Adds or removes labels on every message in a thread | | `trash_thread` | Write | Moves a whole thread to Trash, which is reversible with untrash\_thread | | `untrash_thread` | Write | Restores a thread from Trash | | `delete_thread` | Destructive | Permanently deletes a whole thread | | `mark_message_spam` | Write | Marks a message as spam and removes it from the inbox | | `unmark_message_spam` | Write | Removes a message from spam and returns it to the inbox | | `mark_thread_spam` | Write | Marks a whole thread as spam and removes it from the inbox | | `unmark_thread_spam` | Write | Removes a thread from spam and returns it to the inbox | | `list_email_labels` | Read | Lists every label in the mailbox | | `create_label` | Write | Creates a label, optionally with a color from Gmail's fixed palette | | `update_label` | Write | Renames or recolors an existing label | | `delete_label` | Destructive | Deletes a label and removes it from every message carrying it | | `get_or_create_label` | Write | Returns a label by name, creating it if it does not exist | | `list_filters` | Read | Lists every Gmail filter | | `get_filter` | Read | Retrieves one filter's criteria and actions | | `create_filter` | Write | Creates a filter from raw criteria and actions | | `create_filter_from_template` | Write | Creates a filter from a named template instead of raw criteria | | `delete_filter` | Destructive | Deletes a filter | ## Authentication [#authentication] | Method | Details | | :------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------- | | OAuth 2.0 (Sign in with Google) | Sign in to your Google account. Paradev asks for full Gmail access (read, compose, modify, labels, and filter settings) and read-only Calendar access. | Connect from the plugin's page in **Plugins**. Paradev keeps the credentials. The agent and your machine never see them. --- # Granola Source: https://docs.paradev.com/plugins/available/granola Search and read your Granola meeting notes and transcripts Search and read your Granola meeting notes and transcripts. ## Skills [#skills] | Skill | What it does | | :----------------------- | :-------------------------------------------------------------------- | | `find-in-granola` | Answers "what did we say, decide, or promise" from your meeting notes | | `follow-up-from-granola` | Finds your commitments in a meeting and does each one, or drafts it | Skills are named `granola-`. In Claude Code they appear as `superset:granola-`. ## MCP Server [#mcp-server] Tools come from Granola's own MCP server at `https://mcp.granola.ai/mcp`. Paradev proxies each call and adds your credentials. Granola decides which tools the server offers, so see Granola's documentation for the current list. ## Authentication [#authentication] | Method | Details | | :-------- | :---------------------------------------------------------------------------------------------------------------------------------- | | OAuth 2.0 | You sign in to Granola in your browser. Paradev registers itself with Granola when you connect, so there is no app to set up first. | Connect from the plugin's page in **Plugins**. Paradev keeps the credentials. The agent and your machine never see them. --- # Available Plugins Source: https://docs.paradev.com/plugins/available Guides to Paradev plugins and the services they connect to Install these from **Plugins** in the sidebar. Each one adds MCP tools to [supported agents](/plugins/overview#supported-agents) and skills that teach the agent when to use them. | Plugin | Category | Connects to | | :------------------------------------------ | :-------------- | :----------------------- | | [GitHub](/plugins/available/github) | Developer tools | Your GitHub account | | [Sentry](/plugins/available/sentry) | Developer tools | Your Sentry organization | | [Stripe](/plugins/available/stripe) | Data & APIs | Your Stripe account | | [Linear](/plugins/available/linear) | Productivity | Your Linear workspace | | [Notion](/plugins/available/notion) | Productivity | Your Notion workspace | | [Granola](/plugins/available/granola) | Productivity | Your Granola account | | [Circleback](/plugins/available/circleback) | Productivity | Your Circleback account | | [YNAB](/plugins/available/ynab) | Productivity | Your YNAB account | | [Slack](/plugins/available/slack) | Communication | Your Slack workspace | | [Gmail](/plugins/available/gmail) | Communication | Your Google account | | [Superhuman](/plugins/available/superhuman) | Communication | Your Superhuman account | The built-in Paradev skills are not a plugin you install. They come with the app; see [Skills](/skills). --- # Linear Source: https://docs.paradev.com/plugins/available/linear Create, search, and update Linear issues Create, search, and update Linear issues. This plugin gives a coding agent Linear tools. To open a Linear issue as a Paradev workspace, see [Use with Linear](/use-with-linear). ## Skills [#skills] | Skill | What it does | | :---------------- | :------------------------------------------------------------------------------------------------------------ | | `file-issue` | Turns a rough report into an issue: reproduces it, checks for duplicates, and sets team, priority, and labels | | `duplicate-sweep` | Groups issues about the same bug, picks one to keep, and moves the evidence to it | | `project-status` | Drafts a project status update from what actually moved: progress, risks, and the decision that is needed | Skills are named `linear-`. In Claude Code they appear as `superset:linear-`. ## MCP Server [#mcp-server] Tools come from Linear's own MCP server at `https://mcp.linear.app/mcp`. Paradev proxies each call and adds your credentials. Linear decides which tools the server offers, so see Linear's documentation for the current list. ## Authentication [#authentication] | Method | Details | | :--------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | OAuth 2.0 | You sign in to Linear in your browser. Paradev registers itself with Linear when you connect, so there is no app to set up first. Paradev asks for `read` and `write`. | | Personal API key | Paste a key from Linear's **Settings → Security & access**. | Connect from the plugin's page in **Plugins**. Paradev keeps the credentials. The agent and your machine never see them. --- # Notion Source: https://docs.paradev.com/plugins/available/notion Search, read, and write pages, databases, and comments Search, read, and write pages, databases, and comments. ## Skills [#skills] | Skill | What it does | | :---------------- | :--------------------------------------------------------------------------------------------------------------- | | `find-in-notion` | Searches Notion before the agent answers or writes, finds the current page, and cites it | | `write-to-notion` | Writes a page under the right parent, checks for an existing page first, and structures it so people can find it | Skills are named `notion-`. In Claude Code they appear as `superset:notion-`. ## MCP Server [#mcp-server] Tools come from Notion's own MCP server at `https://mcp.notion.com/mcp`. Paradev proxies each call and adds your credentials. Notion decides which tools the server offers, so see Notion's documentation for the current list. ## Authentication [#authentication] | Method | Details | | :-------- | :-------------------------------------------------------------------------------------------------------------------------------- | | OAuth 2.0 | You sign in to Notion in your browser. Paradev registers itself with Notion when you connect, so there is no app to set up first. | Connect from the plugin's page in **Plugins**. Paradev keeps the credentials. The agent and your machine never see them. --- # Sentry Source: https://docs.paradev.com/plugins/available/sentry Debug with production error context: search issues, read stack traces, and manage alerts Debug with production error context: search issues, read stack traces, and manage alerts. ## Skills [#skills] | Skill | What it does | | :------------------ | :----------------------------------------------------------------------------------------------------- | | `debug-with-sentry` | Finds the root cause of a production error from the stack trace and breadcrumbs before it changes code | | `find-in-sentry` | Answers "what's breaking" by finding the right project and searching issues and events | Skills are named `sentry-`. In Claude Code they appear as `superset:sentry-`. ## MCP Server [#mcp-server] Tools come from Sentry's own MCP server at `https://mcp.sentry.dev/mcp`. Paradev proxies each call and adds your credentials. Sentry decides which tools the server offers, so see Sentry's documentation for the current list. ## Authentication [#authentication] | Method | Details | | :-------- | :-------------------------------------------------------------------------------------------------------------------------------- | | OAuth 2.0 | You sign in to Sentry in your browser. Paradev registers itself with Sentry when you connect, so there is no app to set up first. | Connect from the plugin's page in **Plugins**. Paradev keeps the credentials. The agent and your machine never see them. --- # Slack Source: https://docs.paradev.com/plugins/available/slack Search, read, and post in channels, DMs, and threads Search, read, and post in channels, DMs, and threads. This plugin gives a coding agent Slack tools. To mention `@superset` in Slack and have it file tasks or start agents, see [Use with Slack](/use-with-slack). ## Skills [#skills] This plugin adds no skills. The agent uses the tools directly. ## MCP Server [#mcp-server] Paradev hosts the tools for this plugin itself. Calls go from the Paradev API to the Slack API with your credentials. **Access** shows what a tool does: Read changes nothing, Write creates or changes data, and Destructive deletes, archives, or removes something. | Tool | Access | What it does | | :-------------------- | :---------- | :------------------------------------------- | | `send_message` | Write | Sends a message to a Slack channel or DM | | `update_message` | Write | Updates an existing message | | `delete_message` | Destructive | Deletes a message | | `get_message` | Read | Gets details of a specific message | | `list_messages` | Read | Lists messages from a channel or DM | | `search_messages` | Read | Searches for messages across workspace | | `get_unread` | Read | Gets unread messages from a specific channel | | `get_thread_replies` | Read | Gets all replies in a thread | | `add_reaction` | Write | Adds a reaction emoji to a message | | `remove_reaction` | Write | Removes a reaction from a message | | `get_reactions` | Read | Gets all reactions on a message | | `list_channels` | Read | Lists all channels in workspace | | `get_channel` | Read | Gets details of a specific channel | | `create_channel` | Write | Creates a new channel | | `archive_channel` | Destructive | Archives a channel | | `unarchive_channel` | Write | Unarchives a channel | | `invite_to_channel` | Write | Invites users to a channel | | `kick_from_channel` | Destructive | Removes a user from a channel | | `join_channel` | Write | Joins a channel | | `leave_channel` | Write | Leaves a channel | | `rename_channel` | Write | Renames a channel | | `set_channel_topic` | Write | Sets channel topic | | `set_channel_purpose` | Write | Sets channel purpose | | `list_users` | Read | Lists all users in workspace | | `get_user` | Read | Gets details of a specific user | | `get_user_by_email` | Read | Finds a user by email address | | `get_user_presence` | Read | Gets user presence status | | `set_user_presence` | Write | Sets your presence status | | `get_team_info` | Read | Gets workspace/team information | ## Authentication [#authentication] | Method | Details | | :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ | | OAuth 2.0 (Add to Slack) | Install the Paradev app to your workspace. It reads and writes channels, DMs, group DMs, messages, reactions, and users, and can search messages. | Connect from the plugin's page in **Plugins**. Paradev keeps the credentials. The agent and your machine never see them. --- # Stripe Source: https://docs.paradev.com/plugins/available/stripe Trace charges and subscriptions, read billing data, and search Stripe's docs Trace charges and subscriptions, read billing data, and search Stripe's docs. ## Skills [#skills] | Skill | What it does | | :--------------------------- | :------------------------------------------------------------------------------------------------------------- | | `trace-a-payment` | Answers questions about money that already moved: why a charge failed, what a customer paid, where a payout is | | `refund-and-dispute` | Refunds a customer or responds to a dispute, with checks before each write that cannot be undone | | `build-a-stripe-integration` | Writes Stripe code against the current API, checking every parameter in Stripe's docs | Skills are named `stripe-`. In Claude Code they appear as `superset:stripe-`. ## MCP Server [#mcp-server] Tools come from Stripe's own MCP server at `https://mcp.stripe.com`. Paradev proxies each call and adds your credentials. Stripe decides which tools the server offers, so see Stripe's documentation for the current list. ## Authentication [#authentication] | Method | Details | | :-------- | :-------------------------------------------------------------------------------------------------------------------------------- | | OAuth 2.0 | You sign in to Stripe in your browser. Paradev registers itself with Stripe when you connect, so there is no app to set up first. | Connect from the plugin's page in **Plugins**. Paradev keeps the credentials. The agent and your machine never see them. --- # Superhuman Source: https://docs.paradev.com/plugins/available/superhuman Find and read threads, triage your inbox, draft replies, and schedule meetings Find and read threads, triage your inbox, draft replies, and schedule meetings. ## Skills [#skills] | Skill | What it does | | :------------------------- | :---------------------------------------------------------------------------------------------- | | `find-in-superhuman` | Finds the thread where something was said, sent, or promised | | `triage-superhuman-inbox` | Sorts the inbox into needs a reply, waiting, worth knowing, and noise, then archives and labels | | `reply-from-superhuman` | Drafts a reply or follow-up in your own voice after it reads the whole thread | | `schedule-with-superhuman` | Checks calendars and availability, proposes times, and books the meeting | Skills are named `superhuman-`. In Claude Code they appear as `superset:superhuman-`. ## MCP Server [#mcp-server] Tools come from Superhuman's own MCP server at `https://mcp.mail.superhuman.com/mcp`. Paradev proxies each call and adds your credentials. Superhuman decides which tools the server offers, so see Superhuman's documentation for the current list. ## Authentication [#authentication] | Method | Details | | :-------- | :---------------------------------------------------------------------------------------------------------------------------------------- | | OAuth 2.0 | You sign in to Superhuman in your browser. Paradev registers itself with Superhuman when you connect, so there is no app to set up first. | Connect from the plugin's page in **Plugins**. Paradev keeps the credentials. The agent and your machine never see them. --- # YNAB Source: https://docs.paradev.com/plugins/available/ynab Read and update accounts, categories, budgets, and transactions in YNAB Read and update accounts, categories, budgets, and transactions in YNAB. ## Skills [#skills] This plugin adds no skills. The agent uses the tools directly. ## MCP Server [#mcp-server] Paradev hosts the tools for this plugin itself. Calls go from the Paradev API to the YNAB API with your credentials. **Access** shows what a tool does: Read changes nothing, Write creates or changes data, and Destructive deletes, removes, or sends something. | Tool | Access | What it does | | :---------------------------- | :---------- | :--------------------------------------------------------------------------------------------------------- | | `list_budgets` | Read | Lists the budgets this token can reach, with currency and last-modified date | | `list_accounts` | Read | Lists accounts with their working, cleared, and uncleared balances | | `list_categories` | Read | Lists category groups with budgeted, activity, and available amounts for one month | | `get_month_summary` | Read | Reads one budget month: income, budgeted, activity, to-be-budgeted, age of money, and overspent categories | | `list_payees` | Read | Lists payees, for resolving a name to a payee id | | `list_transactions` | Read | Lists transactions, newest first | | `get_transaction` | Read | Reads one transaction, including its splits | | `list_scheduled_transactions` | Read | Lists scheduled transactions with their next date and frequency | | `create_transaction` | Write | Records a transaction in an account | | `update_transaction` | Write | Changes fields on one transaction | | `delete_transaction` | Destructive | Deletes a transaction | | `set_category_budget` | Write | Sets how much is budgeted to a category in one month, replacing the current amount | ## Authentication [#authentication] | Method | Details | | :-------------------- | :------------------------------------------------------------------- | | Personal access token | Paste a token from YNAB's **Account Settings → Developer Settings**. | Connect from the plugin's page in **Plugins**. Paradev keeps the credentials. The agent and your machine never see them.