Getting started

runcastle is a programming system built on Claude Code: the IDE to Claude Code's text editor. One global command installs it, and it runs entirely on your machine as a Bun server plus a browser UI at http://localhost:4512. No account, no hosted backend.

Install

Three lines: install it, see what is missing, boot it.

$ 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 lands, 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 must already be there. Run runcastle doctor any time: it probes each one and prints a copy-pasteable fix for whatever is missing. runcastle doctor --gate is the stricter pre-boot check that stops only on the must-haves.

Platform baselines: macOS 13+, Windows 10 1809+ (64-bit), or a modern Linux. runcastle is source-available under the FSL (FSL-1.1-ALv2) and published to npm as runcastle.

Only for unattended builds

Skip these two if you only 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 wizard appears. It asks for a git identity, the one hard step: runcastle commits docs and merges for you, so it writes your name and email to git config --global. It is skipped if you already have one. Then it offers to enable unattended burns (optional, and you can do it later), and asks you to open your first project by pointing runcastle at a git repo.
3. Prepare the project. One conversation, once, that records how your repo installs, verifies, and runs, so no agent has to guess. How preparation works.
4. Start something. If you know what you want, use New Feature. If you have a complaint rather than a plan, talk it through with the project session and let it cut the work into features.

The loop

Every feature gets its own conversation, which walks six phases: ideation, spec, tickets, build, review, shipped. You get grilled on an idea until a spec and tickets fall out. Sandboxed agents burn the tickets on the feature's branch while you are elsewhere. You test drive the result and merge.

You are needed at the two ends and nowhere in between. Each feature has its own branch and its own memory, so several run at once, and the app always names the next step. Read the pipeline for each phase and gates for the checks between them.

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, and everything preparation established about the repo.
• Your code lives where it always did. One branch per feature. Planning sessions get docs-only worktrees so several features can be planned at once, and your checkout stays yours.

When something will not start

Start with runcastle doctor. It names the 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, so re-run bun install. On Windows it 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.