Paradev Monorepo

Paradev is an agent-first development platform, with an Electron desktop IDE, Next.js web apps, and an Expo mobile app as the main customer-facing surfaces. It's a Turborepo monorepo, deployed apps are in apps/ and supporting packages are in packages/, and we use tRPC for the api.

You're working inside a Paradev workspace, an isolated checkout of this repo — a git worktree on a machine someone owns, a plain clone at /workspace in a cloud workspace. "Workspace" in a user message means that, not an editor workspace.

Project Structure

All projects in this repo should be structured like this:

app/
├── page.tsx
├── dashboard/
│   ├── page.tsx
│   ├── components/
│   │   └── MetricsChart/
│   │       ├── MetricsChart.tsx
│   │       ├── MetricsChart.test.tsx      # Tests co-located
│   │       ├── index.ts
│   │       └── constants.ts
│   ├── hooks/                             # Hooks used only in dashboard
│   │   └── useMetrics/
│   │       ├── useMetrics.ts
│   │       ├── useMetrics.test.ts
│   │       └── index.ts
│   ├── utils/                             # Utils used only in dashboard
│   │   └── formatData/
│   │       ├── formatData.ts
│   │       ├── formatData.test.ts
│   │       └── index.ts
│   ├── stores/                            # Stores used only in dashboard
│   │   └── dashboardStore/
│   │       ├── dashboardStore.ts
│   │       └── index.ts
│   └── providers/                         # Providers for dashboard context
│       └── DashboardProvider/
│           ├── DashboardProvider.tsx
│           └── index.ts
└── components/
    ├── Sidebar/
    │   ├── Sidebar.tsx
    │   ├── Sidebar.test.tsx               # Tests co-located
    │   ├── index.ts
    │   ├── components/                    # Used 2+ times IN Sidebar
    │   │   └── SidebarButton/             # Shared by SidebarNav + SidebarFooter
    │   │       ├── SidebarButton.tsx
    │   │       ├── SidebarButton.test.tsx
    │   │       └── index.ts
    │   ├── SidebarNav/
    │   │   ├── SidebarNav.tsx
    │   │   └── index.ts
    │   └── SidebarFooter/
    │       ├── SidebarFooter.tsx
    │       └── index.ts
    └── HeroSection/
        ├── HeroSection.tsx
        ├── HeroSection.test.tsx           # Tests co-located
        ├── index.ts
        └── components/                    # Used ONLY by HeroSection
            └── HeroCanvas/
                ├── HeroCanvas.tsx
                ├── HeroCanvas.test.tsx
                ├── HeroCanvas.stories.tsx
                ├── index.ts
                └── config.ts

components/                                # Used in 2+ pages (last resort)
└── Header/

1. One folder per component: ComponentName/ComponentName.tsx + index.ts for barrel export
2. Co-locate by usage: If used once, nest under parent's components/. If used 2+ times, promote to highest shared parent's components/ (or components/ as last resort)
3. One component per file: No multi-component files
4. Co-locate dependencies: Utils, hooks, constants, config, tests, stories live next to the file using them

Exception: shadcn/ui Components

The src/components/ui/ and src/components/ai-elements directories contain shadcn/ui components. These use kebab-case single files (e.g., button.tsx, base-node.tsx) instead of the folder structure above. This is intentional—shadcn CLI expects this format for updates via bunx shadcn@latest add.

Database

Drizzle ORM, schema in packages/db/src/. Follow .agents/skills/db-migrations/SKILL.md to generate migrations and to clear its production safety checklist before opening the PR. Never hand-edit packages/db/drizzle/ (SQL, meta/_journal.json, snapshots) without explicit user confirmation, and never apply migrations against a shared or production database.

Releases

Desktop, host-service, and cli share one version; cut releases on a dedicated branch. Runbook: scripts/release/README.md. A canary is a separate thing: bash scripts/release-canary.sh [commit] builds the rolling internal desktop-canary prerelease, not a versioned release.

Plugins

First-party plugins live in plugins/<name>/: a plugin.json manifest and skills/. A plugin ships no code — agents reach its tools through /mcp/plugins/<marketplace>/<plugin> on the API, which proxies to the vendor's MCP server or, for the plugins named in the SUPERSET_HOSTED_PLUGINS constant, serves them from packages/trpc/src/router/plugins/servers/. A release is the git tag <name>@<version> on this repo — that tree is what a host downloads — and packages/shared/src/plugins/manifests.generated.ts is the bundle the API resolves against, which is generated and must never be hand-edited. Change the source, then superset plugins publish <name> --bump patch, which rewrites the marketplace entry in .agent-marketplace.json and the generated manifests; merging to main tags it. bun run check:plugins is what CI runs to catch a change that skipped that step; run it before pushing.

Installed plugins are recorded once per machine in $SUPERSET_HOME_DIR/plugins/installed_plugins.json (SUPERSET_HOME is the CLI's install prefix and means nothing here). Every provisioner reads that one file — the desktop at boot, plugins sync, the host-service — because provisioning is declarative and reaps whatever is absent from the desired set. A caller that passes its own list instead makes the last writer delete the others' skills. Details: docs/plugins.md.

Orchestrating agents and workspaces

When work wants a fresh isolated environment, a parallel agent, or a long-running job, reach for the superset CLI instead of hand-rolling git worktrees or doing it all serially in this one. It's already on PATH in Paradev terminals, and we dogfood it. paradev is an alias for the same binary; write superset in code and docs here.

Replace the capitalized placeholders before running these:

superset ws create --local --project PROJECT_ID --name NAME --branch BRANCH --agent claude --prompt "..."
superset agents create --local --workspace WORKSPACE_ID --agent claude --prompt "..."
superset ws list --local
superset terminals read --local --workspace WORKSPACE_ID --terminal TERMINAL_ID
superset ws archive --local WORKSPACE_ID

In order: an isolated workspace with an agent already working in it, another agent in an existing workspace, what's running, what an agent is doing right now, and cleanup when you're done.

Those agents run in terminals. A user who asks for a new session or a chat means a chat agent session, which is a different namespace: use superset sessions, not agents create or terminals. terminals read and send cannot control a chat session.

superset sessions create --local --workspace WORKSPACE_ID --agent claude --prompt "..."
superset sessions list --local --workspace WORKSPACE_ID
superset sessions read --local --workspace WORKSPACE_ID --session SESSION_ID
superset sessions send --local --workspace WORKSPACE_ID --session SESSION_ID --prompt "..."
superset sessions close --local --workspace WORKSPACE_ID --session SESSION_ID

resume, open, and import, and which agents chat supports: docs/agent-tooling.md.

Spawning several related workspaces? Add --tag SOME_TAG (repeatable) to ws create — tagged workspaces group into a sidebar folder of that name automatically, so a batch files itself instead of scattering across the project. ws list --local --tag SOME_TAG filters to them, and ws update WORKSPACE_ID --tag ... retags (--clear-tags ungroups). Automation-created workspaces are tagged automation by default and collect in an "automation" folder.

superset schema prints every command, option and argument as JSON; read it with jq to learn the rest (tasks, automations, hosts, settings) instead of parsing --help text. To check only that a command exists, the exit code of superset <command> --help is enough. Details and the version caveat: docs/agent-tooling.md.

superset schema | jq '.commands[] | select(.path==["terminals"]) | .commands[] | {path, options: [.options[].name]}'

Pass --json for parsable output; it's on by default under agent environments.

Internationalization

User-facing strings use Lingui macros with the English text as the message id — <Trans>Text</Trans> or useLingui()'s t({ message }) in React, i18n._(msg({ message })) outside React (Electron main). Identical English with different meanings gets a context so it translates separately. Numbers, currencies, and dates go through @superset/i18n/format helpers, never new Intl.*("en-US") or toLocale* with a hardcoded locale. After adding or changing strings, run bun run check:i18n (CI enforces it): it regenerates the catalogs and lists every untranslated message per locale. Write those translations yourself into each locales/<locale>/messages.po and commit the catalogs with the change — nothing on CI fills translations for you. Conventions: packages/i18n/README.md; terms that never translate: packages/i18n/glossary.md; strategy and phasing: plans/20260826-i18n-strategy.md. Directories listed in packages/i18n/test/enforced-dirs.ts must not contain hardcoded JSX text — add a directory there once it is fully converted. errorMessage() output is potentially translated and is display-only: logs, Sentry/PostHog, and error classification use rawErrorMessage() or the error object (enforced by packages/i18n/test/display-only.test.ts).

Shipping locales. SUPPORTED_LOCALES in packages/i18n/src/locales.ts is the single source of truth — adding a locale there is what makes it appear in the Settings picker and the optional onboarding step, and what lingui.config.ts must list. Every enabled locale must be fully translated: compile --strict fails the build on a missing message, so finish a translation before adding its locale. Native language names live in LOCALE_LABELS and are never translated — someone stuck in the wrong language has to recognize their own. Relative times use formatRelativeTime/formatCompactRelativeTime, not hand-rolled "3d ago" helpers; Intl already knows every locale's wording.

Three traps worth knowing before you touch catalogs:

• Editing English copy re-keys the message. The text is the id, so an edit creates a new entry that is empty in every locale and check:i18n lists it. If the edit was cosmetic, the old translations are still in git diff on the catalogs to copy from.
• Regenerate from a clean tree. lingui.config.ts keeps messages.po deterministic: orderBy: "message" fixes entry order, and origins: false drops the #: file references, whose order follows filesystem traversal and differs between macOS and Linux. A catalog regenerated on top of local experiments will still commit noise.
• bun test runs uncompiled source. The Lingui macro rewrites message: `${n} items` into a placeholder message plus values at build time, so the catalog stores {n} items. Tests see neither, which is why apps/desktop/test-setup.ts shims the macros and i18n._. Mock that module with a Proxy, never a spread — i18n is a class instance and a spread drops load/activate.

Comments

Never comment unless the thing can never be self-describing in the code. Name it, structure it, or type it first; a comment is the last resort for what the code genuinely cannot say — a constraint that lives outside the repo, or a trap the next reader would walk into. Rationale goes in the commit message and the PR.

Tests

CI runs every suite on each push, and the whole run is meant to stay near two minutes. A test earns its place by catching a regression quickly.

• No real waiting. A test that needs more than bun's default 5 s timeout is too slow. Do not raise the timeout: pass the delay, clock or retry count in and test with a small value. Never wait for a real network or process timeout to fire.
• One test per behaviour. Stress, fuzz and "adversarial" suites that build many real git repositories or processes do not go in the repo. When a probe finds a bug, keep the one regression test for it.
• Any order, clean checkout. Each package's suite runs in one process, in an order that differs between machines, with no root .env. Do not mock.module a module that other files import for real (env, a client, a logger). Give the code its input instead: a parameter, a placeholder in the package's test preload, or a local server.
• A flaky test is a broken test. Fix the cause or delete it. Do not add retries or longer timeouts.
• Node-only suites (real PTYs, node:test) are *.node-test.ts files run by a turbo task, so they run beside the bun suites and not after them.

Further reading

• .agents/skills/: CDP UI verification, mobile simulator verification, DB migrations, tRPC compatibility, ticket format, and more. Read the matching SKILL.md when a task fits its description.
• docs/agent-tooling.md: where commands, skills, and per-agent-CLI config live.
• docs/plugins.md: authoring, publishing, and installing marketplace plugins — the manifest contract, the credential proxy, and which files are generated.
• docs/environment-variables.md: read before adding an environment variable. Five places, and missing one fails silently.
• docs/deploy-workflows.md: read before writing or testing a deploy workflow step. run: has no pipefail by default, and production secrets exist only in GitHub.
• packages/trpc/AGENTS.md: read before changing any tRPC procedure, in packages/trpc or packages/host-service. Released desktop, mobile, and CLI builds still call it.
• apps/desktop/AGENTS.md: desktop specifics (notices, persisted renderer state).
• apps/mobile/AGENTS.md: mobile structure and iOS-only scope.
• docs/cloud-sandbox-mismatches.md: where cloud workspace sandboxes don't fit assumptions the app makes about a machine someone owns. Read it before touching sandboxes, and add to it when you find a new one.
• docs/cloud-sandbox-considerations.md: what cloud sandboxes still owe before they leave the team — billing, credential blast radius, untested behaviour.

Contributor responsibility

Contributors are responsible for every change they submit, including agent-generated code. They must understand the changes, review the diff, and verify the behavior before requesting review.

• Ask for clarification when a request lacks enough context to make a correct change.
• Explain changes and validation so the contributor can review and understand the result.
• Agents may write commit messages and PR descriptions, commit changes, push branches, create PRs, and address review feedback when authorized by the user.
• Only post replies to reviewers when the user explicitly authorizes it.
• Never claim that checks passed or behavior was verified unless it actually was.

Code standards

• Keep code comments concise (usually 1-2 lines)
• Avoid redundant or excessive inline commentary
• Use ASD-STE100 Simplified Technical English, simple wordings

Examples

  // Good (no comment)

  std::string module_name =
    fmt::format("{}_{:x}", name_, std::hash<std::string>{}(source_));

  // Bad (excessive comment for explicit code)

  // The module cache is keyed on this name, so it has to include the source:
  // two kernels sharing a name but not a body would otherwise both run
  // whichever was compiled first. Same fix as 3833 on the Metal side.