Getting started

runcastle is an opinionated programming system layered on Claude Code — the IDE to Claude Code's text editor. It installs as one global command and runs entirely on your machine: a Bun server plus a browser UI at http://localhost:4512. There is no runcastle account and no hosted backend.

Install

Three lines. The first installs the command, the second tells you what is missing, the third boots the server and opens the app.

$ bun add -g runcastle       # install
$ runcastle doctor           # check prerequisites
$ runcastle                  # boot the server and open http://localhost:4512

runcastle --version prints the installed version. When a newer release is published, an in-app banner names the exact bun add -g runcastle@latest command. runcastle never installs anything for you — every fix is a line you run yourself.

What you need first

runcastle drives real tools on your machine, so a few things must already be present. Run runcastle doctor at any time: it probes each one and prints a copy-pasteable fix for whatever is missing. runcastle doctor --gate is the stricter pre-boot gate that stops only on the must-haves.

Platform baselines: macOS 13+, Windows 10 1809+ (64-bit), or a modern Linux. runcastle is MIT-licensed and published to npm as runcastle.

Only for unattended builds

Skip these two if you just want interactive sessions. Builds you walk away from need a container runtime — Docker or Podman — and an auth token: run claude setup-token on this machine and put CLAUDE_CODE_OAUTH_TOKEN=… in ~/.runcastle/.env. Each user authenticates against their own subscription; nothing routes through runcastle.

First run

1. Run runcastle and open http://localhost:4512.
2. On a fresh machine a short first-run wizard appears. It asks for a git identity — the one hard step, because runcastle commits docs and merges for you, so it writes your name and email to git config --global; it is skipped automatically if you already have one. Then it offers to enable unattended burns (optional — set up the sandbox and auth token now, or later), and finally asks you to open your first project by pointing runcastle at a git repo.
3. Inside a project, drive the loop.

The loop

Every feature you build gets a persistent session that walks a pipeline: ideation, spec, tickets, build, review, shipped. You get grilled on an idea until a spec and a set of tickets fall out. Sandboxed AFK agents burn those tickets on a branch. You test drive the result and merge. Human in the loop at only the two ends — and because each feature has its own branch and its own memory, several run the loop at once.

The app always names the one next step. Read the pipeline for what happens in each of the six phases, and gates for the checks between them and the two moments they hand the decision back to you.

Where things get written

• Knowledge lives in your repo, at docs/features/<slug>/: spec, decisions, research, notes. Plain markdown, versioned and agent-readable, and it outlives the tool.
• Machinery lives in the app's SQLite at ~/.runcastle/: phase state, session links, workflow runs, transcript index.
• Your code lives where it always did. One branch per feature; planning sessions get docs-only worktrees so several features can be planned in parallel; the main checkout stays reserved for you.

When something will not start

Start with runcastle doctor. It names the exact failing prerequisite and the fix. Beyond that, the three that come up most:

• bun or runcastle not found on Windows after install. Add %USERPROFILE%\.bun\bin to your PATH.
• The embedded terminal will not start, or instantly exits. node-pty's native binary is missing — re-run bun install. On Windows this is almost always a missing system node.
• Unattended burns fail with an auth error. Make sure CLAUDE_CODE_OAUTH_TOKEN is in ~/.runcastle/.env, generated by claude setup-token.

The full troubleshooting list in the README covers the rest, including musl/Alpine and Podman on Windows.