ThinkRail

A ThinkRail-branded desktop-and-mobile client for the pi coding agent. ThinkRail is a thin host that runs pi in-process and bridges it to a rich, mobile-first UI — pi owns models, skills, compaction, cost, and session state; the app owns the workspace, the editor, and the wire.

Website: thinkrail.ai — a landing page that is the IDE, its blog, and the vibecoder-focused experience (see apps/website).

ThinkRail is a Worktree IDE: open a git repo as a project, spin up workspaces as git worktrees (each its own branch and cwd), and work across a tabbed Monaco editor, git Changes view, terminals, a read-only spec-graph viewer, and multiple concurrent pi chat sessions — all scoped to the active worktree.

Install

ThinkRail ships in two additive forms: a native desktop installer and the self-contained thinkrail CLI, which opens the same app in your browser. Both embed the same in-process agent host and are published with SHA256SUMS on the releases page.

JetBrains signs the Windows CLI and desktop setup executable. The macOS CLI is signed but not yet notarized. Signed/notarized desktop DMGs require the coordinated JetBrains service pipeline; older published DMGs and local Electrobun packages may still be unsigned and blocked by Gatekeeper. Linux artifacts are unsigned. Local installer smoke is not notarization verification.

Desktop

Download the matching thinkrail-desktop-* asset: a DMG for macOS Apple Silicon, a setup ZIP for Windows x64, or a setup tarball for Linux x64/ARM64. Extract the complete Windows ZIP before running its setup executable, keeping its adjacent payload; extract the Linux tarball and run installer. Electrobun 2.0.1 does not provide a macOS Intel desktop build. The coordinated macOS release pipeline uses Electrobun's expanded app archive for JetBrains signing and SRE DMG finalization; that intermediate archive is not a public download. The signing limitation above remains until that private pipeline update is deployed.

Linux desktop builds require Ubuntu 24.04 or another glibc 2.38+ distribution with GTK 3, WebKitGTK 4.1, Ayatana AppIndicator 3, and librsvg 2. On Ubuntu 24.04:

sudo apt install libgtk-3-0 libwebkit2gtk-4.1-0 libayatana-appindicator3-1 librsvg2-2

Eligible packaged stable and nightly desktop builds check for updates in the background. An update follows the classic consent-driven flow in Settings → Updates: Download → Downloading → Preparing update → Install & Restart. Closing Settings or quitting normally defers it; only Install & Restart applies the prepared release. The updater appears only when the package carries a valid HTTPS feed identity. Existing installations that predate that identity need one manual installation before in-app updates are available.

CLI / browser

The CLI installer downloads the right binary, verifies its SHA-256 checksum, and puts thinkrail on your PATH.

macOS / Linux (also Windows under Git Bash):

curl -fsSL https://raw.githubusercontent.com/JetBrains/thinkrail/main/install.sh | bash

Windows — the same command works from cmd and PowerShell:

powershell -c "irm https://raw.githubusercontent.com/JetBrains/thinkrail/main/install.ps1 | iex"

Nightly builds and pinned versions:

# macOS / Linux — a pinned version must belong to the selected channel
curl -fsSL https://raw.githubusercontent.com/JetBrains/thinkrail/main/install.sh | bash -s -- --channel nightly
curl -fsSL https://raw.githubusercontent.com/JetBrains/thinkrail/main/install.sh | bash -s -- --channel stable --version 0.1.2
curl -fsSL https://raw.githubusercontent.com/JetBrains/thinkrail/main/install.sh | bash -s -- --channel nightly --version 0.2.0-nightly.10

# Windows — options are env vars (THINKRAIL_CHANNEL, THINKRAIL_VERSION, THINKRAIL_PREFIX, THINKRAIL_NO_MODIFY_PATH)
$env:THINKRAIL_CHANNEL='nightly'; irm https://raw.githubusercontent.com/JetBrains/thinkrail/main/install.ps1 | iex   # PowerShell
set "THINKRAIL_CHANNEL=stable" && set "THINKRAIL_VERSION=0.1.2" && powershell -c "irm https://raw.githubusercontent.com/JetBrains/thinkrail/main/install.ps1 | iex"   # cmd

Then run thinkrail (add a git repo path to open it as a project: thinkrail ~/code/my-repo). Installed stable/nightly CLI hosts periodically offer Run Update in Settings → Updates. That action runs the host machine's parameterless thinkrail update in the background; the current host stays alive, and a successful update asks you to restart it manually. This is also true when the UI is open in a browser on another machine.

You can run thinkrail update directly on any platform. It re-runs the installer for the installed channel and replaces the current <prefix>/bin/thinkrail[.exe]; use --channel or --version only for an explicit terminal override. To remove it, run thinkrail uninstall: it takes out the executable, the PATH entry the installer added, and the install metadata, and asks whether to delete your ~/.thinkrail app state (kept by default — pass --remove-data to delete it, -y to skip the questions). thinkrail --help lists the flags; thinkrail --version prints the build.

Prebuilt platforms: macOS (Apple Silicon), Linux arm64 + x64, Windows x64 (.exe). Intel macOS isn't prebuilt — use Apple Silicon or build from source.

Prefer a manual CLI install? Download a binary + SHA256SUMS from the releases page and verify the checksum. For safe self-update, rename it to thinkrail (thinkrail.exe on Windows) and place it at <prefix>/bin/thinkrail[.exe]. A binary kept under its release filename or another arbitrary location must be replaced manually or reinstalled with the script; it will not update a different hidden copy.

Runtime prerequisites: git on PATH, and an authenticated pi provider (the agent runs against your real provider credentials). App state lives under ~/.thinkrail.

Quick start

Prerequisites (developing ThinkRail)

• Bun 1.4.0 (the repository's pinned package manager and runtime)
• Node.js ≥ 22.19 (required by the in-process pi engine)
• An authenticated pi provider (the agent runs against your real provider credentials)

For developers

git clone <repo-url>
cd thinkrail
bun install
bun run dev

bun run dev boots the host and the web client together. Press Ctrl+C to stop. Source/dev and locally unstamped builds expose no Updates UI. Running thinkrail update from source installs a published binary; it does not pull, install dependencies, or rebuild the checkout.

To run the launchers:

bun run --filter @thinkrail/cli dev  # browser launcher
bun run build:binary                 # standalone CLI artifact
bun run desktop:dev                  # package and open the Electrobun app
bun run desktop:build                # package without opening it

Desktop commands use the standard Electrobun CLI/configuration. Its pre-build hook builds the shared UI and stages ThinkRail's PI/native resources; Electrobun owns preload bundling and installer creation. Create host-native installers with bun run desktop:package:stable or bun run desktop:package:canary; canary is Electrobun's internal name for the public nightly channel. Native/installer smoke and shared CLI/desktop probes live in packages/artifact-tests, outside the application packages. Run bun run smoke:desktop after a dev build; installer smoke takes an artifact path and channel via bun run smoke:desktop:installer <path> <stable|canary>.

On-disk app state (projects, workspaces, worktrees) lives under ~/.thinkrail.

Architecture (three rings)

• Engine host — packages/server (+ packages/shared), launched by apps/cli or apps/desktop. createServer() is a Bun.serve HTTP+WS host with an AgentSessionManager (one in-process pi AgentSession per tab).
• The wire — packages/contracts: the typed, versioned protocol (types-only).
• UI client — apps/web: mobile-first React 19 + Zustand + Tailwind v4, ships independently and dials a host over the wire.

The engine is pi only, run in-process via @earendil-works/pi-coding-agent. apps/web depends on packages/contracts only — never on the server — which is what makes the UI shippable on its own.

See goal-and-requirements.md and architecture.md for the canonical product and design specs.

Repo layout

apps/
  cli/        browser launcher: boot host + open browser
  web/        mobile-first UI client
  desktop/    Electrobun local-host launcher + native packaging
  website/    public landing + blog + vibecoding site (Cloudflare Pages)
packages/
  artifact-tests/ source-only CLI/desktop artifact and installer tests
  server/     createServer(): Bun.serve + AgentSessionManager
  contracts/  the wire (types-only)
  shared/     server-side helpers (shellEnv, freePort)
  spec-graph/ portable pi extension: spec_* tools + skill

Development

Fast gates (also the husky pre-commit hook):

bun run lint        # biome
bun run typecheck   # tsc across all packages
bun run test        # unit tests (root tooling + each package)

End-to-end tests drive the real web UI against isolated hosts. The no-agent gate builds once and uses a machine-adaptive number of independent shards (half the available CPUs, capped at eight):

bunx playwright install chromium                    # one-time
bun run e2e                                         # complete no-agent gate
bun run e2e -- e2e/changes.spec.ts                  # focused iteration
bun run e2e -- --last-failed                        # repair loop
bun run e2e:serial                                  # one-host debugging fallback
bun run e2e -- --shards=12                          # explicit 1–16 override
bun run e2e:binary                                  # packaged CLI host (build first)
bun run e2e:desktop                                 # packaged desktop host (build first)
bun run e2e:full                                    # everything; needs pi auth
bun run e2e:agent                                   # only @agent; remains serial

On macOS, every public browser E2E command prevents idle system sleep while its runner is alive; the display may still sleep normally.

Specification-driven development

ThinkRail is developed spec-first: hierarchical, interconnected specs live in the repo alongside the code — top-level specs at the root (goal-and-requirements.md, architecture.md) and a co-located SPEC.md for every module. When you change a boundary, contract, or decision, update the corresponding spec in the same change. See AGENTS.md for the spec workflow.

Analytics & Privacy

ThinkRail sends basic usage events to PostHog EU: launches, chat creation, accepted message sends, and provider connections. These are always on in desktop, CLI, and source runs; CI and automated tests are silent. Events include a random installation ID, version/channel, build kind, OS/architecture, send mode, catalog-bucketed provider/model names, and the observed authentication category (API key, subscription sign-in, OAuth, Central, or other/unknown)—never credential values or account/plan details. First observed launch measures first use, not a completed OS installation.

Additional setup, run-outcome, task, review, and PR statistics require explicit consent in the first-launch window. Its switch starts from your saved analytics preference; confirming records your choice. Change it later in Settings → Privacy. --no-analytics or THINKRAIL_NO_ANALYTICS=1 suppresses additional events for that run only; basic reporting remains on.

Neither tier collects prompts, code, transcripts, file/repository names or paths, credentials, or token/cost counts. The installation ID links usage over time, but no person profiles are created and GeoIP enrichment is disabled. The analytics spec defines the event boundaries.

Contributing

Contributions are welcome — see CONTRIBUTING.md. This project and community are governed by the Code of Conduct.

License

Licensed under the Apache License 2.0.