SpecRider App Icon SpecRider
Download
Guides

Agent integration

Running Claude Code, Codex, Aider, or any agent inside SpecRider's terminal.

SpecRider runs a real PTY-backed terminal inside every window, so the loop of “ask the agent to revise the plan, watch the file refresh, read it” doesn’t make you alt-tab. This guide covers what works today and the gotchas worth knowing.

This page is a stub. Detailed agent recipes for launching agents, granting workspace access, and keeping plan edits in sync will land here. Until then, see the high-level pitch on the home page and the agent terminal section of the lander.

What works today

  • PTY-backed terminal via xterm.js with the WebGL renderer, ligatures, ANSI 256-color palette, and a 256 KB reattach buffer. Anything that lives in a terminal works — claude, codex, aider, an SSH session, htop, vim.
  • OSC 7 cwd tracking. When the agent cd’s into a subdirectory, SpecRider knows. The title bar reflects it, and the cwd is available to other surfaces that want it.
  • Per-window session scoping. Each window owns its terminal session; opening a second window doesn’t share PTY state. Sessions survive pane resizes and reload.
  • Reader stays live. When the agent edits a plan on disk, the reader picks up the change within ~50ms via filesystem events. No “reload to see changes” step.
  • Launch your agent the same way you would in a regular terminal — there’s no SpecRider-specific wrapper to install.
  • For Claude Code / Codex / Aider, give the agent the SpecRider plans-root as its working directory so it sees the same file tree the reader is showing.
  • Most agents respect $EDITOR. If you want the agent to drop you into SpecRider’s editor when it wants confirmation, set EDITOR="open -W -n -a SpecRider" (macOS, blocking). Caveat: SpecRider isn’t yet wired to handle protocol callbacks back to the agent, so for v0.1 this is one-way only.

Gotchas

  • Long-running commands inside Claude Code. The agent’s own shell management can occasionally lose track of background processes. Workaround: prefix with & and disown if you need a job to outlive the agent session.
  • TTY size on rapid resize. Aggressive pane resizing in SpecRider can briefly leave the PTY’s reported size out of sync. Most agents recover on the next prompt; if not, send SIGWINCH manually (kill -WINCH <pid> from another shell).