siding

01Overview

siding is a workspace manager for coding agents. Each task gets its own track: a folder with one git worktree per repo it touches, a shared branch name, and a generated AGENTS.md that tells the agent the rules, the repos and which skills to load at each stage. The name comes from a railway siding: a side track where a train works without blocking the main line.

02The Problem

Coding agents work best on one task at a time, in a clean checkout. Real work rarely looks like that. A feature touches the backend and the web app, a hotfix lands in the middle of it, and the agent edits whatever clone it was pointed at. Switching tasks means git stash and git checkout across several repos, and nothing stops an agent from shipping code nobody has read.

03What Was Built

A CLI that any agent able to run shell commands can use, plus adapters that add guard rails per harness:

• One track per task: one worktree per repo, the same branch name in each, and the base commit recorded in .track.json. Main clones in repos/ are never edited, and a hook blocks edits there
• Two human gates: the agent stops after the PRD (Gate 1) and again with the uncommitted diff (Gate 2). In Claude Code, Codex, Cursor and OpenCode a hook blocks the agent from running siding approve itself
• Generated AGENTS.md: rules, worktree paths, branches, repo facts and the skills for the current stage, regenerated when the stage changes
• Board: siding ui serves tracks by stage, per-file diffs, docs, gate buttons and the agent terminal live over xterm.js, bound to 127.0.0.1 and protected by a per-server token
• Learning loop: the retro writes lesson proposals to knowledge/inbox/. Accepted ones become repo facts that every later track touching that repo gets in its AGENTS.md

04A Task, Start to Finish

• siding new add-promo backend,web creates the track, then siding open starts the agent in it
• The agent writes prd.md, runs siding submit and stops at Gate 1
• You read the PRD and run siding approve, or send it back with --back
• The agent plans, writes tests and code, leaves the changes uncommitted and stops at Gate 2
• siding pr commits, pushes and opens one PR per repo; siding done removes the worktrees once log.md exists

05Technical Notes

• Stack: Go, a single binary. Git is the only hard dependency. Config is TOML, task docs and knowledge are Markdown
• Install: brew install rans0/tap/siding, Scoop on Windows, or go install
• Parallel tracks: each track gets the lowest free port slot and its own COMPOSE_PROJECT_NAME, so several tracks run at once without port clashes
• Safe by default: existing branches are reused, and done checks everything first and refuses while any repo has uncommitted changes or unpushed commits
• Terminal: siding open runs the agent in a pseudo-terminal owned by siding, so it works in any terminal app with no tmux

Port

port + slot × port_stride

Example

With port_stride = 100, three tracks of web run on 3000, 3100 and 3200.