Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Project Overview
This repository is public. Everything written here is world-readable and
permanent, git history included. See "This repository is public" in the root
CLAUDE.md for what that rules out — credentials, internal hostnames and
infrastructure names, personal addresses. It applies to test fixtures too.
Switch Console is a cross-platform, local-first Electron app for orchestrating multiple AI coding agents in parallel. Each agent runs in its own session in its location's directory (there are no Git worktrees). An agent runs either locally or — when configured remote — on an SSH host — through a persistent SDK host. The supported providers are Claude Code, Codex, OpenCode, Antigravity and Cursor. Local and SSH sessions use the same adapters, durable commands and transcript recovery. See SDK sessions.
The name: display vs identity (CHOO-2008)
Switch Console is a fork; upstream attribution is recorded in NOTICE. The app was
previously called switchdash, and before that emdash.
The rename covered the display name, the source tree and the release artifacts. What did not move is anything already written to a user's disk or already spoken to something deployed — those names are frozen, and the split is load-bearing.
Renamed: PRODUCT_NAME, the workspace packages (@switch-console/*), the app
directory (apps/switch-console-desktop/), the binary and package names
(APP_NAME_LOWER), the release artifacts (ARTIFACT_PREFIX) and tags
(switch-console-v*), the Windows signing profile, and every name that lives
only inside this repo — log filenames, the renderer-log IPC channel, temp-file
prefixes, TERM_PROGRAM, the oxlint plugin namespace, the icon asset folder,
the Nix package, the updater cache directories and the BYOI tooling names.
Still switchdash, deliberately — do not "fix" these:
- the user-data directory (
USER_DATA_DIR_NAME) and the SQLite fileswitchdash.db— it holds the database, and the compose project names derive from it, so renaming starts an existing install empty and orphans its Postgres volume - the macOS app id (
com.switchdash.*) — it carries registration and update continuity for copies installed before the rename, and nobody reads it - the name the app announces to the OS (
OS_APP_NAME, passed toapp.setName) —safeStorageencrypts against a key the OS files under it, bound the first time the app touches the keychain and never re-read, so a renamed build gets an empty key and cannot read the saved sign-ins or the local server's credentials sitting in the shared database. Measured on macOS: the bundle names are not consulted, only this call. Nothing a user reads comes from it — display strings takePRODUCT_NAME - the
switchdash://deeplink scheme — links already posted into Slack and Mattermost are permanent, and deployed Mattermost stacks whitelist the scheme in their config - the per-project config file (
.switchdash.json) and per-repo state dir (.switchdash/) SWITCHDASH_*environment variables and theX-Switchdash-*hook headers — baked into hook commands already written into users' own agent config files, and into sidecars already deployed on remote hosts
One cost was accepted rather than avoided: because APP_NAME_LOWER moved, apt and
dnf treat switch-console as a new package rather than an upgrade of switchdash,
so a Linux user upgrading across the rename has to remove the old package by hand.
The update feed points at GitHub Releases on the public
sandbox-quantum/switch repo (see electron-builder.config.ts publish): the feed is
read unauthenticated, so the updater needs no token. The SQLite database file is switchdash.db;
installs upgrading from a pre-rebrand build are migrated forward from their legacy database
on first launch — see LEGACY_DB_FILENAMES in src/main/db/default-path.ts and the
copy-migration in database-file.ts (those legacy filenames are the only place the
pre-rebrand name is retained).
Repository Structure
This is a pnpm workspace monorepo. The Electron app lives in apps/switch-console-desktop/
(package @switch-console/desktop). Unless prefixed otherwise, src/..., drizzle/,
scripts/, build/, and config-file paths in this document and in agents/ docs are
relative to apps/switch-console-desktop/.
Repo root:
.claude/- Local Claude agent settings for this checkout.agents/- Agent-facing architecture, workflow, convention, integration, and risk docs.apps/switch-console-desktop/- The Electron desktop app (everything below).packages/- Shared workspace packages.packages/core/- Transport-agnostic core runtime primitives.packages/shared/- Shared workspace primitives, including theResult<T, E>type (@switch-console/shared).packages/plugins/- Plugin interfaces and helpers, and the agent provider plugins undersrc/agents/impl/<id>/.packages/switch-agent-runtime/- The published agent runtime; sessions run a pinned version of it (see "Versioned Artifacts").
- Root config files -
pnpm-workspace.yaml, rootpackage.jsonwith aggregate scripts,.nvmrc,.oxfmtrc.json,.oxlintrc.json.
Inside apps/switch-console-desktop/:
build/- Electron packaging assets; avoid edits unless working on packaging or signing.drizzle/- Generated Drizzle SQL migrations and metadata.scripts/- Build and verification support scripts (sidecar bundle, postinstall, deeplink reset, compose sync). Releasing is a GitHub Actions workflow at the repo root, not a script here.src/main/- Electron main process, RPC controllers, services, database, SDK host.src/preload/- Typed Electron preload bridge exposed to the renderer.src/renderer/- React app organized aroundapp/,features/,lib/, and tests.src/shared/- Shared IPC primitives, provider metadata, events, MCP, skills, and types.src/types/- Ambient and cross-cutting TypeScript declarations.tooling/- App-level dev and test infrastructure that is not bundled into production.- App config files - Electron Vite, Vitest, TypeScript, Drizzle, Nix, and packaging config.
Build & Development Commands
The repo root has aggregate scripts (dev, build, test, lint, format,
format:check, typecheck) that fan out through the pnpm workspace. App-specific
commands run from apps/switch-console-desktop/.
Install dependencies (repo root):
pnpm install
Start the full workspace dev setup from the repo root. This builds packages/**
once, then runs package watch builds and the Electron app in parallel:
pnpm run dev
Start only the Electron app from apps/switch-console-desktop/:
cd apps/switch-console-desktop
pnpm run dev
pnpm run d
Switch Cloud, the hosted deployment the first-run page and the Add server dialog
offer, has no URL in source. Point a run at one with SWITCH_CLOUD_URL, or bake
one into a build with MAIN_VITE_SWITCH_CLOUD_URL (inlined into the main
process by electron-vite). Either must be a bare https origin; with neither set
the Cloud choice reads "Coming soon".
SWITCH_CLOUD_URL=https://cloud.example.com pnpm run dev
Run main-process or renderer-only dev watches:
pnpm run dev:main
pnpm run dev:renderer
Run with debug logging:
pnpm run dev:debug
Use an isolated development database for schema or migration work by pointing
SWITCHDASH_DB_FILE at a scratch path. From the repo root this starts the full workspace
dev setup:
SWITCHDASH_DB_FILE=/tmp/switchdash-scratch.db pnpm run dev
From apps/switch-console-desktop/, this starts only the Electron app:
cd apps/switch-console-desktop
SWITCHDASH_DB_FILE=/tmp/switchdash-scratch.db pnpm run dev
Reset the dev databases from apps/switch-console-desktop/:
pnpm run db:reset
Build the app:
pnpm run build
pnpm run build:main
pnpm run build:renderer
Package desktop artifacts locally:
pnpm run package
pnpm run package:mac # arm64
pnpm run package:mac:x64
pnpm run package:linux # x64
pnpm run package:linux:arm64
pnpm run package:win
Two things these scripts do NOT do for you:
- Build the workspace packages. They package the app only, so on a fresh
clone the renderer build fails with
Failed to resolve entry for package "@switch-console/shared"— itsexportspoint at adist/that no one has written yet. Runpnpm run buildfrom the repo root (orpnpm -r --filter './packages/**' run build) first. - Rebuild the native modules.
npmRebuildis off, so whateverpnpm --filter @switch-console/desktop run rebuildlast produced is what gets copied into the package.
The macOS and Linux scripts name an arch for that second reason: the natives are
built for the host, so packaging the other arch yields a package that installs,
launches, and dies on the first wrong-arch .node. Build each arch on that arch
— which is also why the release workflow runs macOS twice, on an Apple silicon
runner and an Intel one, rather than passing both flags to one job.
The two macOS builds share one auto-update channel file. electron-builder writes
latest-mac.yml for every macOS arch (the per-arch suffix it gives Linux is
Linux-only), so neither release job publishes its own — merge-mac-manifest
combines them into one manifest listing both, which is what electron-updater
reads and how it routes each Mac to its own build. Anything that changes macOS
artifact names has to keep arm64 in the Apple silicon file names: that
substring is the whole of the updater's routing rule.
Run formatting, linting, type checks, and tests:
pnpm run format
pnpm run lint
pnpm run typecheck
pnpm run test
Run focused database validation:
pnpm run db:setup
pnpm run db:fixtures
pnpm run test:migrations
Rebuild native Electron dependencies after native dependency changes:
pnpm run rebuild
Clean and reset dependencies:
pnpm run clean
pnpm run reset
Code Style & Conventions
- Use Node
24.14.0from.nvmrcand[email protected]. - Use
pnpmfor root project work; do not introduce npm or yarn lockfile churn. - Format with
oxfmt; config is.oxfmtrc.json. - Keep formatted lines near the configured
printWidthof 100 characters. - Use 2 spaces, semicolons, single quotes in TS, double quotes in JSX, LF endings, trailing commas where valid in ES5, and sorted imports.
- Lint with
oxlint; config is.oxlintrc.jsonwith correctness errors, TypeScript, React hooks, and local repo rules enabled. - TypeScript strict mode is enabled in
apps/switch-console-desktop/tsconfig.json, the single tsconfig for all app targets. - Avoid
any; if a registry or boundary needs it, keep the escape local and documented. - Use top-level
importstatements; do not userequire(). - Never re-export as a shortcut; import from the original source.
- Components use
PascalCase; hooks useuseXcamelCase or an existing local pattern. - Tests use
*.test.tsor*.test.tsx. - Main-process RPC handlers live in
src/main/core/*/controller.tsand delegate to imported operation or service functions. - Renderer RPC calls go through
rpcfromsrc/renderer/lib/ipc.ts. - Feature UI lives under
src/renderer/features/<feature>/; shared renderer primitives, stores, hooks, modal infrastructure, hotkeys, and UI live undersrc/renderer/lib/. - New modals must be registered in
src/renderer/app/modal-registry.ts. - New views must be registered in
src/renderer/app/view-registry.ts. - New commands should use
src/renderer/lib/commands/registry.tsand view-levelcommandProviderhooks where possible. - Commit messages should follow Conventional Commits:
<type>(<scope>): <short imperative summary>
Examples:
fix(opencode): change initialPromptFlag from -p to --prompt for TUI
feat(docs): add changelog tab with GitHub releases integration
Architecture Notes
flowchart LR
User[User] --> Renderer[React renderer]
Renderer --> RPC[Typed RPC client and event emitter]
RPC --> Preload[Electron preload bridge]
Preload --> Main[Electron main process]
Main --> Controllers[src/main/core controllers]
Controllers --> Services[Domain services and providers]
Services --> DB[(SQLite via Drizzle)]
Services --> SDK[Persistent SDK host]
Services --> MCP[MCP and skills services]
SDK --> Agents[Native provider adapters]
Main --> Events[Typed events]
Events --> Renderer
The app boots from src/main/index.ts, loads environment and database state,
registers RPC controllers through src/main/rpc.ts, creates the Electron window,
and exposes a typed preload API from src/preload/index.ts. The renderer is a
React app that calls typed RPC methods, subscribes to typed events, and coordinates
views, modals, command providers, project state, and session workflows.
Shared IPC primitives, provider metadata, events, MCP types, skills types, and
domain types live under src/shared/.
Main-process work is split into domain modules under src/main/core/: agent hooks,
agent runtime, agents (Switch agents), app, dependencies, embedded controller, execution context, fs,
locations (an agent's working dir on a host — formerly the project/workspace split),
managed Switch server, prompt library, providers (the CLI-provider registry), SDK host,
remote hosts, resource monitor, search, secrets, sessions, settings, SDK host, SSH,
switch rooms, switch servers, switch setup, command shells, lifecycle scripts, updates, and
view state. agents and providers are different things — see
agents/architecture/main-process.md. Stateful main-process concerns use singleton
services; expected failures should use the Result<T, E> pattern from the
@switch-console/shared workspace package.
Logging
createLogger() in src/shared/logger.ts backs all three processes. The console and
the file sink are levelled independently: the console follows LOG_LEVEL (default
warn), the file follows LOG_FILE_LEVEL (default info), so a shipped build records
the run that led to a failure without a noisy terminal.
Entries carry structured context. Do not add a parameter to a function only so a log line can mention it — the identity is ambient:
- Main: an
AsyncLocalStoragescope (src/main/lib/log-context.ts) is opened at the RPC chokepoint, so anything beneath a call inherits itssessionId. UserunWithLogContext()when adding a new entry point, andbindLogContext()for callbacks that outlive the operation that created them (streams, intervals) — ALS follows promises and timers but such emitters otherwise keep a stale scope forever. - Renderer: no ALS in the browser; attach ids with
log.child({ … }). - Enrichment:
registerLogContextResolver()derives the remaining fields from the ids present (session → room, id → name). Resolvers must stay synchronous and best-effort; never query the database from the logging path, which runs during shutdown and inside error handlers.
Names come from a cache pushed to by the row mappers (mapSessionRowToSession,
mapAgentRowToAgent) — never fetched on demand.
At the boundaries that fail (sidecar launch, migrations, updater, SDK host, RPC), log an
event plus an enumerated stage/errorCode rather than prose, so failures can be
grepped and counted.
Testing Strategy
- Local merge gate:
pnpm run format
pnpm run lint
pnpm run typecheck
pnpm run test
- Unit tests run with Vitest in the
nodeproject forsrc/**/*.test.ts. - Main database integration tests run in the
main-dbVitest project. - Migration tests run in the
migrationsproject viapnpm run test:migrations. - Fixture generation runs in the
fixturesproject viapnpm run db:fixtures. - Renderer browser tests run in the
browserproject using Playwright-backed@vitest/browser-playwright. Agents: skip these — do not run or try to fix them. They need a real Chromium and its system libraries (e.g.libnspr4), which dev VMs generally lack, so they fail for environment reasons unrelated to your change. CI is the gate for them. Run the node projects instead:
pnpm vitest run --project node --project main-db
If pnpm run test reports failures only from the browser project (a
Playwright launch error rather than an assertion), treat the run as green and
say so — do not install browsers or chase the failure.
- Main-process tests are colocated in
src/main/core/**/*.test.ts. - Renderer unit tests live under
src/renderer/tests/. - Renderer browser tests live under
src/renderer/tests/browser/. - Integration-style tests create temporary projects in
os.tmpdir(). - Run the consistency checks locally before merging:
pnpm run format:check
pnpm run typecheck
pnpm run lint
- Run the tests locally before merging as well.
Security & Compliance
- The project is licensed under Apache-2.0; see
LICENSEat the repo root. - Do not commit secrets, tokens, private keys, app databases, logs, build artifacts, or generated dependency folders.
- Application secrets are stored through encrypted app secret services and Electron safe storage.
- The app sends a small, fixed set of product events to the company's public OTLP relay,
which forwards them to Amplitude and Datadog, and nothing else. The relay holds both
vendor keys, so no credential ships in the app — do not reintroduce one, and do not
call a vendor directly. It also means the vendors see the relay's network address rather
than the user's. Do not turn that into a promise about them: it is a property of the
relay's configuration, which lives in another repository and whose own documentation
describes the change that would undo it. The consent copy therefore promises only what
this app does — it sends no address and no location — which stays true either way.
Logs are local-only and no code path transmits them off the machine. Do not add one.
getDiagnosticLogAttachment()builds a redacted export and is the only function intended to ever feed such a path; anything that ships log content must go through it rather than reading the log itself, and no log content may enter a telemetry payload. - Telemetry consent is a gate, not a preference. Anything that would send usage data
must
await isTelemetryAllowed()(src/main/core/telemetry/consent.ts) at the point of emission and send nothing when it returns false. Do not readtelemetry.enabledfrom settings directly — it does not distinguish "said yes" from "not asked yet" — and do not cache the answer across a send, since the user can revoke it at any time. Consent off means no request is made at all, not a request whose result is discarded. - The answer reaches the managed server too, and never by omission. "Share usage
data" is one decision covering this app and a Switch server it runs, so
startStackreads it and writesTELEMETRY_ENABLEDinto the stack's.envon every start —falseas explicitly astrue, because the compose file forwards the key only when the.envnames it, and a stack started under a yes would otherwise keep reporting. On a shared SSH host a "yes" is written only when the stack already shares or no other Console has been seen on it lately (shareUsageDatainpipeline.ts), so one user's yes never turns sharing on over the others; a "no" is always written. The scope note intelemetry-copy.tsanddocs/TELEMETRY.md§4.1 state this to the user, and change with it. Adding a variable to that contract needs three edits:deploy/local/standalone-docker-compose.ymlpluspnpm run sync:compose,env-file.ts, andnative/core-settings.ts— a native local server (no Docker) gets the same settings as its process environment, and the copy it was started with is what is read back. The server reads the gate once at boot, so a running stack can be out of step; that is surfaced on the server's page with a restart offered, never applied by restarting the user's server for them. Whether it is out of step is read off the running container, not inferred from what we last wrote — and a host that cannot be read is reported as unknown, never as agreeing. - The toggle defaults to on. Usage data is opt-out: a first-run notice says what is shared and carries the off switch, and the same toggle lives in Settings. That default is a product decision, and so is what identifies an install (today, only the random per-install id). Changing either is a product and privacy call, not a code change.
- What a telemetry payload may contain. Add an event only by adding it to the closed
catalogue in
src/main/core/telemetry/events.ts: its property types are literal unions, numbers and booleans, andTELEMETRY_EVENT_PROPERTIESnames the same fields as data, which the emitter uses to drop anything else before it builds a payload. A count goes as a number and a yes/no as a boolean rather than as text, so both stay usable at the far end; anything else — an object, an array,null, a non-finite number — is refused rather than encoded. The types alone are not enough — excess-property checking does not apply through a spread — so the runtime filter is what makes "nothing free-text can reach a payload" true rather than intended. Permitted: which of the catalogued things happened, agent type, local-vs-remote, success-vs-failure, how long an operation took, app version, operating system, the random install id, which kind of launch it was (first, after an update, or neither), and whether a signed-in account is on a company email domain — the yes/no only, read from the domain, never the address. A duration is a number rather than a value from a fixed set, so it is held toTelemetryDurationMs: measured on a monotonic clock, whole milliseconds, and never a span that could encode something else. That is a branded type, not an alias fornumber, andstartTimer()is the only thing that mints one — so a call site cannot reach forDate.now() - startedAt, which is not monotonic and across a clock step yields a negative number nothing at the far end can tell from data. Never: prompts, code, file paths, working directories, error messages or stack traces (use an enumerated code), machine or user names, IP or MAC addresses, email or sign-in, and no agent, room, project, location or server names or ids. Widening this is a consent decision — the summary the user consents to lives insrc/renderer/features/telemetry/telemetry-copy.ts, the field-by-field disclosure it links to isdocs/TELEMETRY.md, and both must be kept in step with it. - The interface may report only through the one gate. Almost everything is
reported from the main process, where a call site is type-checked against the
catalogue. The exceptions are moments that exist only in the UI — a screen
opened, a command run, a checklist abandoned — and they go through
rpc.telemetry.trackintosrc/main/core/telemetry/renderer-events.ts, which checks the event is one of the few permitted and every value against the set the catalogue allows. That check is not ceremony: a type does not survive a process boundary, so it is the only thing standing between a received value and a payload. Do not add a second path, and if a moment can be observed from the main process, observe it there. - Report a moment, not a state — and if you must report a state, claim it after
the gate. A condition that is true from the instant it becomes true is true
again on every later launch, so reporting it directly counts it forever;
ONCE_PER_INSTALLinrenderer-events.tsexists for that case and keeps the record beside the emitter rather than in the user's settings, which would report a setting nobody changed. The record is spent once and never given back, so it must not be claimed until a send is actually possible: the app renders behind the first-run consent prompt, so anything claiming before the consent check spends its one chance while the answer is still unset and retires the event for the life of the install. - Prefer a value the caller declares to one you read back. Several dimensions describe an intent that only the caller has — which button, which source, whether a room was chosen — and the state that would answer is often consumed by the very operation being reported. Pass it through the params; narrow it at the emitter, because it crossed a process boundary.
- A fallback must not assert something.
unknownis the right default for a dimension nobody supplied. Falling back to a real variant —userfor "who started this" — reports a claim the code has no evidence for, and it lands in the bucket a human would read as deliberate. - Telemetry never affects the user. It is fire-and-forget with a short timeout and no
retry: a send that fails is logged with an
errorCodeand dropped. It must never block, delay or fail an operation, and must never surface in the UI. It is off in a dev build, which is logged once so a build that is not reporting says why. - The compile-time guards are load-bearing; keep them in the
[X] extends [never]form. An indexed access by a union distributes and then collapses, soMap[Union]yieldstrue | never— which istrue, and passes while every member but one is wrong. Two assertions in this area were written that way and asserted nothing. Wrapping both sides in a tuple stops the distribution. Note also thatsatisfies { [K in Name]: readonly (keyof T[K])[] }constrains what an array may contain, never what it must — that is why_everyPropertyIsAllowListedis a separate check. - The sidecar sends nothing to the relay. It runs headless on a user's VM with no
consent prompt and no access to this setting, so sessions it starts are not counted in
this app's telemetry. Do not "fix" that by having it report; the gate is not reachable
from there. What a session host does tell is the Switch server it already works for:
that a new session started and how (
host/session-start.ts), as ordinary traffic to that server. Whether that leaves the server as telemetry is the server's own setting. The agent controller this app runs on its own computer still reports nothing itself: once Switch has taken a session's start it tells its parent over the IPC channel (host/session-started.ts), and this app reportsmanaged_session_startedunder its own gate. A controller on any other machine has no parent listening; keep it that way. - Redaction is split by destination, and both halves must be preserved:
- Secrets (tokens, keys, JWTs, PEM blocks, URL credentials) are redacted on the
write path by
redactSecrets()and must never reach disk. - Personal data (home directories, IP and MAC addresses, emails) is deliberately
retained in the local log file — it is what makes a user's own log debuggable —
and is redacted by
redactDiagnosticLog()ingetDiagnosticLogAttachment(), the single point at which content is prepared to leave the machine. Do not "fix" the local file by scrubbing it on write; that reinstates the problem this split exists to solve. - Anything contributed via
registerDiagnosticSection()passes through the same export scrub. Never read the raw log file from outsidefile-logger.ts.
- Secrets (tokens, keys, JWTs, PEM blocks, URL credentials) are redacted on the
write path by
- An agent's Switch API token lives in exactly one file:
<working dir>/.switch/agents/<slug>.json, beside a generated.gitignorecontaining*. For the agents Switch Console manages it also writes.claude/settings.local.jsoncarrying the endpoint and agent id only — Claude Code's own file, read by every session in the directory, which does not need the credential. Do not add a token back to it: two copies is how one goes stale and authenticates as the wrong agent.- It is readable by its owner alone:
0600in a0700.switch/agents/, with owner-only ACLs on Windows. Every write of it is a secret write:PluginFs.writewith{ secret: true }, or what that calls —writeSecretFileinsrc/main/core/providers/plugin-fs.tslocally,SshFileSystem.writeSecretover SFTP. A plain write takes the umask, typically leaving the token readable by every account on the machine. A directory another account owns is left as it is, with a warning, rather than failing the write; the file is private either way. - To tighten a file already there, use
PluginFs.protectSecret, which changes permissions only; rewriting the content to the same end can undo a concurrent write.{ fileOnly: true }leaves the directory alone, for a legacy file in.claude/that still holds a token. - A secret write that is cut off leaves its temporary
<file>.<uuid>copy behind, soPluginFs.deleteremoves those too: delete the file through it, or throughdeleteFileson a host, never with a barerm. - Where Switch Console writes the settings file, Claude Code makes it live.
Its
envblock becomes real process environment for everything a session spawns, so keep the agent id in it in step with.switch/agents/; changing one means changing the other. - Two consumers read this layout: Switch Console and the sidecar. A session
host reads it through
readSharedCredentialsinpackages/agent-providers/src/host/shared-config.tsand refuses a file naming a different agent. Changing the shape means changing both. - The token being in a working tree at all is a known exposure — a
.gitignorestopsgit addand not an archive, a sync orgit add -f. Moving it out is tracked separately; it is deliberately not solved by writing it to a second location as well.
- It is readable by its owner alone:
- The embedded agent controller's credential (
embedded-controller/) lives only in the encrypted app secrets store. It reaches the controller child on stdin (--credential-stdin), never on argv, in the environment or in a file, so the watchers and sessions the controller starts cannot inherit it. Keep it that way. - SDK host environment passthrough must use the allowlist in
packages/agent-providers/src/host/agent-env.ts. - Treat shell escaping and provider process spawning as security-sensitive.
- Do not bypass path-safety, shell escaping, or validation helpers.
- Use
pnpm-lock.yamlfor dependency integrity and review dependency changes.
Shared SDK Host
packages/agent-providers/src/host/ owns persistent execution on both local and
SSH machines. src/main/core/sdk-host/ deploys and connects to it. Changes to
launch configuration, skills, MCP, environment and recovery must work on the
execution machine. Never replace unknown command outcomes with retries.
Versioned Artifacts — Bump Them
The agent runtime package carries its own version, separate from the app's. If you make a non-trivial change to it, bump its version in the same commit. Not at release time, not "later" — in the commit that changes it, or it will be forgotten and someone will debug a build they think is newer than it is.
| Artifact | Version lives in | Bump when |
|---|---|---|
| Agent runtime package | packages/switch-agent-runtime/package.json |
any change to the protocol client or the hosted tool surface. Its version is the client_version Switch records for the connection, and just artifacts-check fails if it disagrees with artifacts.yaml |
"Non-trivial" means anything a user could observe: behaviour, protocol, wiring, dependencies. A comment or a rename that changes nothing does not need one.
SDK host deployment uses the bundle content hash. Preserve wire compatibility and durable command receipts across redeployment.
Agent Guardrails
- Load only the relevant
agents/docs for the area being changed. - Do not hand-edit numbered Drizzle migrations or
drizzle/meta/. - Use
pnpm run db:generatefor new migrations, then update fixtures and migration tests. - Avoid editing
dist/,release/,out/,build/, and generated package artifacts unless the task is explicitly about packaging, signing, or release behavior. - Do not dispatch release workflows, publish packages, or upload artifacts unless the user explicitly asks for release work.
- Treat
src/main/core/sdk-host/,src/main/db/, and updater code as high risk and read the matchingagents/risky-areas/page first. - Do not weaken shell quoting, spawn behavior, env allowlists, or secret redaction casually.
- Prefer existing service, provider, RPC, modal, view, and store patterns over new abstractions.
- New RPC methods belong in the appropriate
src/main/core/*/controller.tsand are registered throughsrc/main/rpc.ts. - Keep renderer-main calls on typed RPC and typed events. The preload bridge in
src/preload/index.tsshould stay small; add directwindow.electronAPIsurface only when a browser/Electron primitive cannot fit the RPC/event path. - Access session and location MobX stores through selectors and session view hooks:
getSessionStore,asProvisioned,sessionViewKind,getSessionManagerStore,getLocationStore,asMounted,useSessionViewKind,useSessionRuntime,useSessionLocationId,useSessionViewModel, anduseSessionAgent. - Never use
asProvisioned(...)!orasMounted(...)!; use explicit null checks. - State guards must check
kind !== 'ready'rather than enumerating non-ready states. - Access session managers through
getSessionManagerStore(locationId), notlocation.sessionManager. - Access mounted locations through
asMounted(getLocationStore(id)), not inline guards. - Session selectors live in
src/renderer/features/sessions/stores/session-selectors.ts. - Location selectors live in
src/renderer/features/locations/stores/location-selectors.ts. - For provider changes, follow Add an agent provider: the plugin, the runtime registration (with its env passthrough), and tests for non-standard behavior. Nothing else should need to name the provider.
- For MCP changes, keep canonical data in shared types and adapt provider formats at edges.
- Run the local merge gate before merging:
pnpm run format
pnpm run lint
pnpm run typecheck
pnpm run test
Extensibility Hooks
- An agent provider registers in two places, each with one line: its plugin in
packages/plugins/src/agents/plugin-registry.ts(display metadata, detection, install, icon) and its runtime inpackages/agent-providers/src/providers/registry.ts(adapter, sign-in check, login command). An ACP CLI's runtime is made from its hooks on the generic ACP adapter.src/shared/core/providers/agent-provider-registry.tsis the catalogue the app builds from both at startup; nothing in the app lists provider ids. See Add an agent provider. - The Switch skill every session receives lives in
packages/plugins/src/switch-skill/SKILL.md, the one copy Console pushes to every host (system context for Claude Code, Cursor and Antigravity; aSKILL.mdfor Codex and OpenCode). A change to how agents interact with Switch — MCP tools, in-room commands, room workflow — updates it. - Provider detection lives in
src/main/core/dependencies/(dependency-managers.ts,registry.ts), with remote detection inremote-dependency-manager.ts. - SDK host deployment and env passthrough live under
src/main/core/sdk-host/. - Per-provider directory-trust helpers live under
src/main/core/agent-hooks/. - Modal definitions are centralized in
src/renderer/app/modal-registry.ts. - View definitions and navigation guards are centralized in
src/renderer/app/view-registry.ts. - MCP types live under
src/shared/core/mcp/. - Skills types and validation live under
src/shared/core/skills/. - Per-location runtime settings can be supplied through
.switchdash.json:preservePatterns,scripts.setup,scripts.run,scripts.teardown, andshellSetup. - Location settings such as
locationProviderare DB-backed, not.switchdash.json. - Optional environment variables:
SWITCHDASH_DB_FILE,SWITCHDASH_DISABLE_NATIVE_DB,SWITCHDASH_REGISTER_DEEPLINK,SWITCHDASH_FAKE_UPDATE,SWITCHDASH_TELEMETRY_DEV, andSWITCHDASH_TELEMETRY_ENDPOINT. - Telemetry in dev: a dev build sends nothing, so the emitter cannot be exercised by
pnpm run devalone.SWITCHDASH_TELEMETRY_DEV=1opts a dev run in, andSWITCHDASH_TELEMETRY_ENDPOINTredirects it at a local listener so what is actually sent can be read off the wire rather than off the code. Both are dev-only and cannot activate in a packaged build. There is no key to configure: events go to the public OTLP relay, which holds the vendor credentials server-side, so every build can report and none carries a secret. Example:SWITCHDASH_TELEMETRY_DEV=1 SWITCHDASH_TELEMETRY_ENDPOINT=http://127.0.0.1:9009 pnpm run dev. - The Codex Windows install list leads with the ChatGPT
install.ps1, and npm's option is stripped of therecommendedflagnpmDependencyadds for every platform — bothpickInstallOptionand the settings UI take the first recommended option, so leaving it on npm steers Windows users there whatever the order. The script ships no uninstaller, so the descriptor removes exactly the two directories it creates (%LOCALAPPDATA%\Programs\OpenAI\Codexand%USERPROFILE%\.codex\packages\standalone) and leaves the rest of~/.codex— config, auth, sessions — alone. It is written without$or%because the install runner's shell may be either PowerShell or cmd.exe, and each would expand one of them beforepowershell -cran. - An auto-approving Codex session launches with
-c approval_policy="never"and nothing else. The sandbox is deliberately not overridden: "Bypass permissions" promises unattended approvals, not unattended filesystem and network access, so the user's ownsandbox_modefrom~/.codex/config.tomlstands. Seepackages/plugins/src/agents/impl/codex/index.ts. - App updates in dev: the update service is inert outside packaged builds, so the
"update available" UI cannot be exercised by
pnpm run devalone. SetSWITCHDASH_FAKE_UPDATEto replay the lifecycle against a simulated release —available,install-error,download-error,check-error, orup-to-date. An unrecognised value fails at startup rather than silently doing nothing.SWITCHDASH_FAKE_UPDATE_VERSIONoverrides the offered version (default: the current minor, bumped) andSWITCHDASH_FAKE_UPDATE_MSthe simulated download duration. Nothing is downloaded or installed, and the harness cannot activate in a packaged build. Example:SWITCHDASH_FAKE_UPDATE=available pnpm run dev. - The managed local Switch server in dev: a dev build launched from a Switch
checkout shows a "Build switch-core from this checkout" toggle on the local
server's page. With it on, every start layers a generated build override on the
bundled compose file and runs
up -d --build, soswitch,gatewayandsetupare built from the working tree and taggeddev-checkoutinstead of pulling the pinned GHCR images. The choice persists inlocal-switch-server/checkout-build.jsonunder user-data and applies from the next start. The compose file stays the bundled pinned one — re-sync it (pnpm run sync:compose) if the checkout's own standalone compose has moved on. Because the tag is not a semver, the downgrade guard cannot run against a checkout build; it is skipped with a warning rather than silently. Seesrc/main/core/managed-switch-server/checkout-build.ts. - Choosing the managed servers' switch-core in dev: a dev build runs the canary
pin (
COMPATIBLE_SWITCH_VERSION).SWITCH_CONSOLE_SERVER_VERSIONoverrides it for the run, read once by the main process at launch:- a release version (
0.30.0,0.31.0-rc.7) — every managed server, local (native or Docker) and SSH-hosted, runs that release: native install, image tags and.envSWITCH_VERSION, the downgrade guard, drift and upgrade prompts all use it, and the setup page shows it. The checkout toggle is held off. The bundled compose file stays the pinned one, and a version older than what a stack already ran is refused by the downgrade guard as usual. checkout— the local server builds (Docker) or installs (native) switch-core from the checkout the app was started in on every start, whatever the persisted toggle says; the server page shows the toggle held on by the variable. Remote managed servers keep the pin, since a remote host builds nothing from this machine. The downgrade guard is skipped with a warning, as for the toggle. A value that is neither, orcheckoutwith no checkout above the app's working directory, stops the launch with an error naming the variable. Set it in the launching environment (.env.localworks too):SWITCH_CONSOLE_SERVER_VERSION=checkout pnpm run dev. Stable and canary builds ignore it. Seesrc/main/core/managed-switch-server/server-version.ts.
- a release version (
- Deeplinks in dev:
pnpm run devdoes not claim theswitchdash://OS URL scheme by default — doing so hijacks the handler from the installed app and the registration outlives the dev process (on macOS it sticks in Launch Services), so later deeplinks open the bare dev Electron's welcome window instead of the installed app. To test deeplinks against the dev build, run withSWITCHDASH_REGISTER_DEEPLINK=1 pnpm run dev; afterwards runpnpm run deeplink:reset(macOS) to hand the scheme back to the installed app. - Path aliases are defined in
tsconfig.jsonand mirrored inelectron.vite.config.ts:@/*,@renderer/*,@main/*,@shared/*, and@root/*. - Versioned JSON column schemas are defined in
src/shared/usingdefineVersionedSchema()fromsrc/shared/lib/versioned-schema/versioned-schema.tsand wired to Drizzle viaversionedJsonColumn()fromsrc/main/db/versioned-column.ts. Seeagents/conventions/versioned-schemas.mdfor the full guide.
Further Reading
- Agent docs map
- Quickstart
- Architecture overview
- Main process architecture
- Renderer architecture
- Shared modules
- Remote execution: hosts, reachability, sidecar
- Switch rooms and sessions
- Data model (Switch Console vs. its upstream origin)
- Testing workflow
- Provider integration
- MCP integration
- IPC conventions
- Main-process patterns
- Renderer patterns
- TypeScript and React conventions
- Config file rules
- Versioned schema conventions
- Database risk notes
- SDK session risk notes
- Updater risk notes
- Contributing guide (repo root)
- Project README