Styx keeps two written records of why things are the way they are. Architecture decision records (ADRs) explain the big choices and what was rejected. The deviations log records every smaller, deliberate change to how a screen or flow behaves. Read the relevant ones before you change something that looks odd; it is often odd on purpose.
When the code, an ADR and the deviations log disagree, the code is what ships, and an ADR or a later log row says why.
Architecture decision records
ADRs live in docs/adr/, one Markdown file per decision, named NNNN-short-title.md. Each starts with a heading (# ADR-NNNN Title) and a status line with a date, then gives the context, the decision, and the options that were rejected and why.
Write an ADR when you make a decision that a future contributor would otherwise have to reverse-engineer or might undo by accident:
- a new architectural piece or protocol (a new runner, a new storage rule);
- a new screen, interaction model or flow (these also start as a reviewed HTML mockup in
design/next/); - reversing or narrowing an earlier ADR.
A bug fix or a small change inside an existing design doesn't need one.
ADRs are not rewritten after they are accepted. A later ADR supersedes an earlier one and says so in its status line (for example, ADR-0016 supersedes ADR-0010 for Codex). An ADR can carry a dated amendment at the end when the same decision is revised shortly after.
Finding the latest
List docs/adr/ and take the highest number; the next ADR takes the number after it. Two quirks in the file names: ADR-0024 is filed as 0020-agent-clis-found-like-the-terminal-and-installed-from-styx.md, so two files start with 0020, and there is no 0024-… file.
The deviations log
docs/handoff-discrepancies.md began as a log of every place the app departs from the original design handoff. It is now the running record of how features behave and why they changed. It is one table, with the columns # | Where | Prototype | Spec | Resolution.
Add a row, numbered after the last one, when you change what a screen shows, a flow, a default, or a rule that the handoff states. Name the files you touched and the reason. Don't renumber or rewrite old rows; when behaviour changes again, add a new row that supersedes the old one. The last few dozen rows are the best description of how the app works today.
Every ADR
| ADR | Decision |
|---|---|
| 0001 Grant transport is a local broker (MCP + CLI shims) | Agents ask for access through a local JSON-RPC broker, reached by the styx mcp server and by provider shims put first on the session's PATH. |
| 0002 No LSP in Monaco for v1 | The editor highlights and edits only; "Open in" your IDE is the way to full language features. |
| 0003 Sessions are per project and per worktree | A session belongs to exactly one project and one worktree; sessions across repos are out of scope. |
| 0004 WSL is optional on Windows | Windows sessions default to PowerShell; a project setting switches the terminal shell to WSL. |
0005 .styx/project.json v1 schema | The committed, secret-free, versioned project file, and which settings stay on the machine instead. |
| 0006 Main process is the source of truth; renderer mirrors via snapshot + deltas | SQLite in main, a read-only mirror in the renderer, every change a validated command, no optimistic updates. |
| 0007 Secrets live only in the OS keychain | Secrets are stored with @napi-rs/keyring; SQLite holds only a credentialRef. |
| 0008 Styling: CSS Modules + cascade layers, token custom properties | CSS Modules in fixed cascade layers so selection states win without !important; no Tailwind, CSS-in-JS or icon fonts. |
| 0009 Storybook (Vite builder) for the component library | Storybook over Ladle, for its accessibility addon and test runner. |
0010 Session runners: stream for Claude Code and cursor-agent, pty for the rest | The original split between structured chat and terminal sessions. Superseded for Codex by 0016 and for Gemini and Cursor by 0017. |
| 0011 IDs are ULIDs, timestamps are epoch milliseconds | Branded ULID types everywhere; times are numbers, formatted only in selectors with an injected now. |
| 0012 Fidelity policy | The prototype decided visuals and the spec behaviour, with differences logged. ADR-0027 later moved the screens past the prototype. |
0013 Roadmap and execution state live in .planning/ (gsd format) | Roadmap and phase plans are kept in .planning/; the full design plan is mirrored in docs/plan.md. |
| 0014 Agent connections are app-level and verified through each CLI's own status command | An agent CLI is connected once for the whole app; Styx asks the CLI who is signed in and never holds its credential. |
| 0015 The diff review reverts or marks reviewed; nothing "accepts" | Agents write straight into their worktree, so review offers Revert and Mark reviewed rather than an Accept that applied nothing. |
0016 Codex sessions run through codex app-server, not its TUI | Codex is driven over its JSON-RPC app-server, which gives approvals, questions and steering a running turn. |
| 0017 Gemini CLI and Cursor agent sessions run over the Agent Client Protocol | One generic ACP client drives both CLIs, with permission prompts and live settings. |
| 0018 Run, deploy and tech debt audits use hidden background sessions | These actions run as background sessions behind a progress dialog instead of opening a chat. |
| 0019 Global rail, project rail, project nav; no project dropdown in the titlebar | App-level places, the project switcher and the project's own places get separate columns. |
| 0020 Turn checkpoints: every agent turn as hidden git refs, diffable and revertible | Each turn's workspace is captured as hidden refs, so a whole turn can be viewed or undone without touching your branch. |
| 0021 Publish: commit, push and pull request in one step | One action commits, pushes and opens the pull request, with messages drafted by the agent and editable first. |
| 0022 The design window as a simulator: device runs, live mirror, turn screenshots | Local runs gain a platform (web, iOS, Android) and a live simulator or emulator mirror. |
| 0023 Keep lanes current: fetch on spawn, behind-base on every lane, merge base before publish | Styx owns a lane's relationship with its base branch, so lanes don't drift for days. |
| 0024 Agent CLIs are found the way the terminal finds them, and installed from Styx with the vendor's own installer | Detection uses your login shell's PATH, so a CLI your terminal finds, Styx finds. |
| 0025 Lanes that know about each other | A ledger of what every live lane is changing, so agents hear when they overlap, plus resolving and landing. |
| 0026 A Styx account: sign in with GitHub or Google | Optional sign-in through GitHub or Google, without passwords. The project limit in its amendment was removed when Styx was open-sourced (deviations log row 148). |
| 0027 Organised around the lane | The app is organised around tasks rather than files, and moves past the original handoff's look. |
| 0028 Design before you build: design and build tasks, select to fix, tabs in your order | Tasks are design or build; designs are files in the task's worktree, drawn on the Design tab. |
| 0029 Linux (beta) | Linux ships as an AppImage and a .deb, with Windows-style layout and polkit for production approvals. |
Other background
docs/state-machines.mddescribes the session and grant machines.docs/research/agent-parity.mdcompares the agent CLIs' protocols.design/handoff/is the original design system. Its tokens, square corners and motion timings still apply; its screen layouts are history.