tranquil
Docs

ADR-0001: Fork Pulsar rather than build on VS Code

Status: Active · Date: 2026-07-07

Context

Tranquil needed a desktop foundation that is simultaneously a code-editor-class app and a browser-first workspace. Building the whole thing from scratch was never realistic, so the actual choice was which open-source editor to fork. Two bases were credible: Microsoft’s VS Code (via its open core, Code-OSS) and Pulsar — the actively maintained community continuation of GitHub’s Atom. Both are Electron apps, so either could host embedded browser <webview>s and a native tab/pane UI.

This ADR is recorded retroactively: the entire tranquil-client repo already embodies the decision — it is a Pulsar fork — but the reasoning had never been written down. It is captured here as the foundational platform decision that every later ADR builds on.

Decision

Build Tranquil as a fork of Pulsar — the MIT-licensed, Electron-based continuation of Atom — rather than on VS Code / Code-OSS.

Options considered

  • Option A: Fork Pulsar (chosen) — gives end-to-end control of a fully hackable Electron app. Atom/Pulsar’s package system loads our own owned packages and can restyle and replace core chrome (tabs, panes, title bar, docks), which is exactly what a browser-first product needs. It also leverages existing team familiarity with Atom/Pulsar internals and Tranquil work already built on it, lowering the switching cost to near zero. Con: a smaller ecosystem and community than VS Code, and we own fork maintenance and upstream tracking.
  • Option B: Fork VS Code / Code-OSS — the largest extension ecosystem and strong TypeScript and performance foundations. Rejected: Code-OSS deliberately omits proprietary pieces (the extension marketplace, remote development, branding); its extension API is sandboxed and cannot restyle core chrome the way Tranquil requires; and Microsoft controls the project’s direction while the marketplace Terms of Service restrict use from non-VS Code builds.
  • Option C: Build from scratch on Electron (or Eclipse Theia) — maximum control with no upstream baggage. Rejected: an enormous cost to reach editor parity with no ready package/editor infrastructure, and Theia’s extension model is close to VS Code’s sandboxed approach anyway, so it inherits Option B’s chrome-customization limits without VS Code’s ecosystem.

Consequences

  • Easier: deep customization of the entire UI through owned packages; the MIT license permits rebranding and shipping our own distribution; and the team reuses existing Atom/Pulsar knowledge directly.
  • Harder / new risks: a smaller community and fewer actively maintained packages than VS Code; Tranquil owns fork maintenance and upstream integration (master tracks upstream/master and is folded into tranquil/main only via intentional merges); and some of Atom’s older architecture carries forward.
  • Re-evaluation triggers: Pulsar upstream becoming unmaintained; a hard requirement that only VS Code’s ecosystem or extension API can satisfy; or the upstream-tracking burden growing to outweigh the control benefits that motivated the fork.

See also