Getting started

SpecRider is a workspace for spec-driven development. Open a folder of Markdown plans, and the app gives you a documents browser, a reader, a persistent outline, change-aware editing, an embedded agent terminal, and search. This guide gets you from zero to writing in about five minutes.

Install

Download SpecRider for macOS on Apple Silicon or Linux from the Download page . Linux ships as AppImage, .deb, and .rpm.

After install, launch SpecRider. The first run shows an empty-state Choose-folder CTA — that’s expected.

Pick a folder

SpecRider operates on a directory of Markdown files. Anything in there with a .md extension shows up in the documents browser; subdirectories become folder buckets.

If you don’t have a plans folder yet, create one:

mkdir ~/specs
cd ~/specs
echo '# Hello, SpecRider' > intro.md

Then in SpecRider:

• macOS: press ⌘O to open a folder picker. Linux: press Ctrl+O. Pick ~/specs. The window switches to it.
• Or drag the folder onto the SpecRider app icon.

The chosen folder becomes the window’s plans-root. It’s persisted per-window — close the app and reopen, and you land back where you were.

Write a plan

Click intro.md in the left rail. The reader opens it in Read mode — rendered Markdown, served via SpecRider’s typography stack (Source Serif 4 body, IBM Plex UI, opt-in ligatures, GFM tables and callouts).

Press ⌘E to flip to Markdown mode. CodeMirror takes over with syntax highlighting and the standard keymap. Edit the file, save with ⌘S, and the Read view picks up your changes when you toggle back.

SpecRider does not have its own save-on-blur magic — it relies on filesystem events, so the same file edited from another editor (Vim, VS Code, an agent in a terminal) shows up here within ~50ms.

The outline

The right rail shows the active plan’s outline — every H1/H2/H3, plus GFM task list items if you’ve turned that on in Settings → Editor & Outline. The outline tracks your scroll position; the matching heading highlights as you read. Click any row to jump.

If your plan has - [ ] task items, the outline rolls them up: each parent heading shows a progress bar and an n/m counter. Check off - [x] and the bar fills.

Change awareness

Open SpecRider on a folder that’s a Git repo and the app starts paying attention to HEAD. Unstaged edits show as colored gutter bars in the editor and dots on outline rows. Plan rows in the browser get an M chip. Press ⌘⇧J / ⌘⇧K to jump between hunks.

This is opt-out, not opt-in — there’s nothing to configure. If the folder isn’t a Git repo, all the diff UI silently disappears.

Agent terminal

Press ⌃` (or open the View menu) and a real PTY-backed terminal opens inside the same window. Run claude, codex, aider, an SSH session, anything that lives in a terminal. SpecRider tracks OSC 7 cwd changes from the agent, so the title bar always reflects the directory the agent thinks it’s in.

The terminal session is scoped to the window — opening a second window gives you a second, independent session. Sessions survive pane resizes and reload.

Where to go next

• Keyboard shortcuts — every keymap SpecRider responds to.
• Theming — author a custom theme (or just tweak the accent).
• Frontmatter contract — what the app parses out of your plans’ YAML headers.

Hit a bug? Help → Copy diagnostics produces a fenced markdown snippet with version + OS + settings — paste it into a GitHub issue.