ThinkRail: a JetBrains worktree IDE that hosts the pi coding agent in-process

The problem ThinkRail picks: one checkout, many agent sessions

Running a coding agent against a single working directory creates a queue. Two sessions touching the same files will collide, and a long-running task blocks you from starting the next one. ThinkRail's answer is to make the git worktree the unit of work. The README describes V1 as a worktree IDE: you open a git repository as a project, spin up workspaces that are each their own git worktree with their own branch and working directory, and then work across a tabbed Monaco editor, a git Changes view, terminals, a read-only spec-graph viewer, and multiple concurrent pi chat sessions, all scoped to the active worktree.

The audience is developers who already use the pi coding agent and want a graphical host instead of a terminal. The README is explicit that ThinkRail is a thin host: pi owns models, skills, compaction, cost, and session state, while the app owns the workspace, the editor, and the wire. That division matters when you evaluate it, because it means ThinkRail is not trying to be an agent runtime. If pi does not support something, ThinkRail cannot add it. The project is listed as a JetBrains incubator project, and the repository's only tagged release is v0.1.0, published on 2026-09-10, alongside nightly builds such as v0.1.0-nightly.49.

Three rings: engine host, typed wire, and a UI that ships alone

The architecture document in the repository describes three rings. The engine host is packages/server plus packages/shared, launched by either apps/cli or apps/desktop. createServer() is a Bun.serve HTTP and WebSocket host that holds an AgentSessionManager, and the README states there is one in-process pi AgentSession per tab. The wire is packages/contracts, described as a typed, versioned, types-only protocol. The UI client is apps/web, a mobile-first React 19 application using Zustand and Tailwind v4.

The constraint that follows from this layout is the interesting part. apps/web depends on packages/contracts only, never on the server, which the README says is what makes the UI shippable on its own. In practice that means the browser client dials a host over the wire rather than importing server code, so the same UI can be served by the CLI launcher or wrapped by the desktop app. The engine is pi only, run in process through @earendil-works/pi-coding-agent, pinned in the workspace catalog at version 0.84.3 alongside pi-agent-core and pi-ai at the same version. There is no second agent backend to switch to. That is a deliberate simplification, and it also means the dependency surface is narrow enough to reason about.

Installing ThinkRail and opening a repository as a project

ThinkRail ships in two additive forms: a native desktop installer and a self-contained thinkrail CLI that opens the same app in your browser. Both embed the same in-process agent host. The CLI installer downloads the matching binary, verifies its SHA-256 checksum, and puts thinkrail on your PATH. On macOS and Linux, and on Windows under Git Bash, the README gives this command:

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

Windows has its own installer invocation from cmd or PowerShell. Note that the options on Windows are environment variables rather than flags, which the README lists as THINKRAIL_CHANNEL, THINKRAIL_VERSION, THINKRAIL_PREFIX and THINKRAIL_NO_MODIFY_PATH:

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

Once the binary is on your PATH, run thinkrail with a git repository path to open it as a project. The README gives this example:

thinkrail ~/code/my-repo

What you should see is the workspace UI for that repository, with the worktree model available so you can create additional workspaces. Before any of this works, two runtime prerequisites must be satisfied: git has to be on PATH, and you need an authenticated pi provider, because the agent runs against your real provider credentials. App state lives under ~/.thinkrail. To move to a newer build later, run thinkrail update on any platform; the README states it re-runs the installer for your channel and that on Windows it replaces the running thinkrail.exe in place. thinkrail --version prints the build, and thinkrail --help lists the flags.

Nightly channels, pinned versions, and removing the install cleanly

The installer is not limited to the latest stable build. On macOS and Linux you can pass --channel nightly or --version 0.2.0 to the shell installer, and the README shows both forms. That gives you a way to test a nightly without hand-downloading an artifact, which matters for a project whose release history so far is one tagged version and a stream of nightlies.

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 -- --version 0.2.0

Uninstalling is documented in more detail than most projects bother with. thinkrail uninstall removes the executable, the PATH entry the installer added, and the install metadata, then asks whether to delete your ~/.thinkrail app state. That state is kept by default, and you pass --remove-data to delete it or -y to skip the questions. If you have accumulated worktrees and project entries under ~/.thinkrail, the default behaviour is the safe one, but it also means a reinstall will pick up the old state. If you want a clean slate you have to ask for it explicitly.

Where ThinkRail will not run, and what is not signed

Platform coverage is narrower than the feature list suggests. Prebuilt CLI binaries exist for macOS Apple Silicon, Linux arm64 and x64, and Windows x64. Intel macOS is not prebuilt, and the README points Intel users at Apple Silicon or building from source. On the desktop side the constraint is harder: the README states that Electrobun 2.0.1 does not provide a macOS Intel desktop build at all, so an Intel Mac cannot run the packaged desktop app regardless of what you are willing to compile.

Code signing is the second boundary. JetBrains signs the Windows CLI and desktop setup executable. The macOS CLI is signed but not yet notarized. Signed and notarized desktop DMGs require a coordinated JetBrains service pipeline, and the README warns that older published DMGs and local Electrobun packages may still be unsigned and blocked by Gatekeeper. Linux artifacts are unsigned. The README also notes that local installer smoke is not notarization verification, which is a fair warning: a successful local install does not tell you anything about whether the artifact will pass Gatekeeper on someone else's machine. The coordinated macOS release pipeline uses Electrobun's expanded app archive for signing and DMG finalization, and that intermediate archive is not a public download. The README states the signing limitation remains until that private pipeline update is deployed.

Linux desktop builds carry their own dependency list: Ubuntu 24.04 or another glibc 2.38+ distribution, with GTK 3, WebKitGTK 4.1, Ayatana AppIndicator 3 and librsvg 2. The README gives the apt line for Ubuntu 24.04:

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

If your distribution ships an older glibc, the desktop build is not the right target and the CLI plus a browser is the practical fallback.

Building from source, and why the toolchain is pinned

Developing ThinkRail requires Bun 1.4.0, which the repository pins as its package manager and runtime, plus Node.js 22.19 or newer because the in-process pi engine needs it. You also need an authenticated pi provider. The README gives this sequence:

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

bun run dev boots the host and the web client together, and Ctrl+C stops both. From there the launchers are separate: bun run --filter @thinkrail/cli dev starts the browser launcher, bun run build:binary produces a standalone CLI artifact, and bun run desktop:dev packages and opens the Electrobun app while bun run desktop:build packages without opening it. Host-native installers come from bun run desktop:package:stable or bun run desktop:package:canary. The README places native and installer smoke tests plus shared CLI and desktop probes in packages/artifact-tests, deliberately outside the application packages, and notes that installer smoke takes an artifact path and a channel.

The pinned toolchain is a trade-off worth naming. Bun 1.4.0 and Node 22.19 or newer are both hard requirements, and the workspace catalog pins React to a canary build, 19.3.0-canary-a1124489-20260826, with overrides forcing the same version for react-dom. That is consistent with a project that expects to move fast, but it means contributing to ThinkRail is not a matter of cloning and running whatever Node happens to be installed. The upside of the catalog approach is that every package in the monorepo resolves the same versions of pi, React, Tailwind and TypeScript, so version skew between apps/web and packages/server is unlikely to be the source of a bug.

What you give up compared with a terminal-first agent setup

The obvious alternative is running pi directly from a terminal, which is what ThinkRail is a client for. The difference in approach is not cosmetic: a terminal session has no worktree abstraction, no tabbed editor, no git Changes view and no spec-graph viewer, but it also has no install artifact, no signing story and no ~/.thinkrail state directory. If you already work comfortably in a terminal and your agent tasks are short and serial, ThinkRail adds a packaging layer between you and the same agent engine without changing what the agent can do, because the engine is pi only and runs in process either way.

A second alternative is a general-purpose editor with an agent extension. The README's own framing is that ThinkRail is a thin host, which means the value it adds is the workspace model and the UI, not agent capability. An editor extension inherits a mature editing environment and a large extension ecosystem; ThinkRail inherits a mobile-first React client and a worktree-centric workspace model. Which one fits depends on whether your bottleneck is editing or parallel agent sessions. If it is parallel sessions in one repository, the worktree model is the reason to look at ThinkRail. If it is editing, ThinkRail is competing on ground where it has fewer features to offer.

The spec-graph viewer is described in the README as read-only, which is a limitation rather than an oversight. The repository topics include spec-driven and spec-driven-development, so specs are clearly part of the intended workflow, but the V1 viewer does not let you edit them. Anyone expecting a full spec authoring environment should treat that as out of scope for this version.

Editorial conclusion

Adopt ThinkRail if you already have an authenticated pi provider, work in git repositories, and want several agent sessions isolated by worktree rather than one chat window pointed at a single checkout. Do not adopt it if you need Intel macOS, a notarized macOS build, or a stable release line: the only tagged release is v0.1.0 from 2026-09-10 and the README states the macOS CLI is signed but not notarized. Before installing, confirm that git is on PATH, that Node.js is at least 22.19 if you build from source, and that your pi provider credentials are already configured, because the agent runs against your real provider account. Then run thinkrail --version against the binary the installer placed on your PATH and check that it matches the release you intended.

Frequently asked questions

Official sources

1. JetBrains/thinkrail on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases