@exla/rudder 0.0.0-stage → 3.4.0

package/README.md

@@ -1,3 +1,734 @@
-# Temporary Holding Version
+# rudder
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p>
+  <a href="https://rudder.exla.ai">
+    <img src="https://rudder.exla.ai/favicon.svg" width="36" height="36" alt="Rudder logo" />
+  </a>
+</p>
+
+[![TUI e2e](https://github.com/exla-ai/rudder/actions/workflows/tui.yml/badge.svg)](https://github.com/exla-ai/rudder/actions/workflows/tui.yml)
+[![npm version](https://img.shields.io/npm/v/@exla/rudder.svg)](https://www.npmjs.com/package/@exla/rudder)
+[![Node >=22](https://img.shields.io/badge/node-%3E%3D22-43853d.svg)](https://nodejs.org/)
+[![Website](https://img.shields.io/badge/site-rudder.exla.ai-111111.svg)](https://rudder.exla.ai)
+
+Rudder is a TUI for managing coding agents. Run Claude Code, Codex and opencode
+side by side in one native dashboard: every task you type gets its own isolated
+jj workspace, so agents never step on each other. See which agent needs you,
+approve prompts, steer any agent mid-turn, and merge the results back with one
+key. `/main` puts an agent in the main checkout when you want one there, and
+`/plan` turns a bigger goal into a reviewed multi-agent DAG.
+
+> **AI agents and contributors:** this README is for using Rudder. If you are
+> an AI agent (or a human) working on the Rudder codebase itself, read
+> [`AGENTS.md`](./AGENTS.md) first; it is the engineering reference and the
+> source of truth for architecture, conventions, and release rules.
+
+## Install
+
+```bash
+npm install -g @exla/rudder@latest
+rudder
+```
+
+After the global install, every user-facing `rudder` launch checks npm and
+auto-updates itself before running when a newer version is available. Set
+`RUDDER_DISABLE_AUTO_UPDATE=1` to opt out. Run without a global install using
+`npx @exla/rudder@latest`.
+
+Rudder used to be published as `@viraatdas/rudder`. Existing installs move
+themselves to `@exla/rudder` on their next update; nothing to do by hand.
+
+## Requirements
+
+- Node.js 22 or newer
+- Git
+- Claude Code and/or Codex installed and logged in
+- macOS (Apple Silicon or Intel) or Linux x64; the dashboard binary for each
+  ships in the package
+
+Rudder runs agents in isolated [jj (Jujutsu)](https://jj-vcs.github.io)
+workspaces; your repo stays plain git. You do not need to install jj: if it is
+not already on your PATH, Rudder sets up its own copy in `~/.rudder/bin` during
+install (or on first run). A jj you installed yourself is always used instead.
+
+Check your setup at any time:
+
+```bash
+rudder doctor
+```
+
+## Quick start
+
+```bash
+rudder
+```
+
+With no arguments, `rudder` opens the dashboard. Type a task in the bottom input
+and press `Enter`: Rudder starts one worker for it in its own jj workspace. It
+lands in Review when done and merges back with `m`. Use `/main <task>` for an
+agent that works directly in the main checkout (for release, push and deploy
+work), `/gam <task>` to pair a builder with a reviewer from another model, or
+`/plan <task>` when you want a reviewed multi-agent DAG.
+
+If a task needs shared local context like API tokens, private URLs, account ids,
+or environment values, save it with `/share <text>` in the task input. Rudder
+also captures obvious token-looking lines like `APIFY_TOKEN=...` from task-bar
+messages. The text is written to `RUDDER_SHARED.md`, which is gitignored and
+mirrored into worker workspaces; all agents are explicitly told to read it when
+present.
+
+You can also start a task directly from the shell:
+
+```bash
+rudder "fix the failing tests"
+rudder claude "fix the auth redirect bug"
+rudder codex --model gpt-6.1-sol "refactor the parser"
+```
+
+## Onboarding and auth
+
+```bash
+rudder onboard
+```
+
+Onboarding uses the auth you already have, so you usually do not need API keys:
+
+- Claude Code auth from the macOS Keychain or `~/.claude/.credentials.json`
+- Codex auth from `~/.codex/auth.json`
+- `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` if you prefer keys
+
+If auth is missing you can skip it and set up a backend later. Config is written
+to `~/.rudder/config.json`.
+
+## The dashboard
+
+```text
+┌───────────────┬────────────────────────────────────────────┐
+│ agents        │ worker                                       │
+│ task list     │ live Claude Code or Codex terminal           │
+│ status/model  │ DAG-over-orchestrator, scrollback, review    │
+├───────────────┴────────────────────────────────────────────┤
+│ task input: main owner by default, /plan DAG, /run isolated   │
+└──────────────────────────────────────────────────────────────┘
+```
+
+- **agents** (left): one row per task with its backend, model, effort, and status.
+- **worker** (right): the real Claude Code or Codex terminal. When it is focused,
+  your keystrokes go straight to the agent, so its prompts, slash commands,
+  selection, and `Tab` all work normally.
+- **orchestrator** (right, when selected): a Claude Code PTY with the live DAG
+  rendered above it. For planned work, use it to inspect/refine the plan while
+  the bottom task input remains the primary place to type new requests.
+- **task** (bottom): the entry point for fresh requests, slash commands, plan
+  refinements, and approval with empty `Enter`.
+
+Mouse wheel and trackpad scroll the pane under the pointer. Over the worker or
+review pane they scroll Rudder's captured scrollback.
+
+### Usage dashboard
+
+Press `U` in the agents pane (or type `/usage web`) for a machine-wide usage
+page in your browser: subscription quota meters for every signed-in Claude Code
+and Codex account (session and weekly windows with time to reset, read from the
+providers' own usage endpoints using the sign-ins the CLIs already hold), token
+costs estimated at API list rates from the CLIs' local session logs (per day,
+provider, model, and workspace, with the top sessions per workspace and a
+click-to-copy id for `--resume`), and a live view of CPU and memory for Rudder
+and every agent process. Bare `/usage` keeps the one-line summary for the
+current session.
+
+### Diff panel
+
+Press `⌥d` (or type `/diff`) to open a diff panel beside the worker pane, or
+`⌥4` (also `^W 4`) to jump straight to it as the fourth pane: the
+selected agent's change set parsed from `jj diff` (or `git diff` against HEAD
+plus untracked files in a plain checkout), with per-file `+`/`−` counts, line
+numbers, and the run's token usage and estimated API-rate cost in the header.
+It refreshes as the agent edits. `j`/`k` and the wheel scroll, `n`/`p` jump
+between files, `r` refreshes, `Esc` or `⌥d` closes it, and `⌥h` solos it like
+any other pane. On a narrow terminal it takes the worker's place instead of
+squeezing both. `v` opens the same panel.
+
+### God's view
+
+Press `⌥g` (also `^W g`) to see every running agent at once: the screen turns
+into a grid with one tile per agent showing the bottom of its terminal, titled
+with its id, task, model and whether it is working, needs you, or is done.
+Arrows or `h`/`j`/`k`/`l` move the highlight, `Enter` or a click opens that
+agent in the worker pane, and `⌥g` or `Esc` closes the grid. Agents are never
+resized for it, so their scrollback is untouched. With more agents than fit,
+the grid pages.
+
+### Web board
+
+Press `o` in the agents pane (or type `/web`) to open the live project board in
+your browser. The board is a second control surface, not just a monitor: open a
+task to send an update while it runs, or request changes from Review to resume
+the same agent in the same workspace. The task's update thread records your
+directions alongside the latest worker activity. `+ Task` follows the same
+end-to-end main-owner path as typing in the dashboard task pane; use `/plan` in
+the native dashboard for an explicit DAG.
+
+The board also works on its own with `rudder board`: in that mode updates
+redirect or resume the detached worker directly and move revised work back
+through Review before it can merge.
+
+## Keyboard shortcuts
+
+**Direct (work from any pane):**
+
+| Key | Action |
+| --- | --- |
+| `Option-1` / `Option-2` / `Option-3` | Focus the agents, worker, or task pane |
+| `Option-[` / `Option-]` | Step to the previous / next agent, staying in the pane you are in |
+| `Option-h` | Full screen: the focused pane takes the whole terminal; press again to bring the panes back |
+| `Option-g` | God's view: every agent tiled on one screen; press again to close |
+| `Option-d` | Diff panel for the selected agent |
+| `Ctrl-V` | Paste a screenshot or copied files into an agent (works in `rudder cloud` too) |
+| `Option-v` / `Option-b` | Previous question in the selected worker / back to its latest message (Claude Code and Codex) |
+| `Cmd-C` | Copy the active Rudder selection |
+| `Ctrl-C` | Quit (asks to confirm if agents are still running) |
+
+`Option-1/2/3` and `Option-[`/`Option-]` work out of the box on macOS terminals,
+whether or not "Use Option as Meta" is enabled. `Cmd-[` / `Cmd-]` also step agents
+in terminals that forward Cmd to the app (Ghostty and other terminals that speak
+the kitty keyboard protocol, and only if the terminal has not bound those keys
+itself). `Option-[`/`Option-]` are the ones that always work.
+
+## More tabs on the same session
+
+One dashboard owns the session. Run `rudder` again in another tab or split of
+the same checkout and you get a second full view of it: the same agents, plans
+and panes, with its own selection, focused pane and task bar. Start agents,
+`/plan`, merge or type into a worker from either tab; both see the result.
+`Ctrl-C` in a second view closes only that tab.
+
+A pane has one size, so the tab you typed in last sets it; the other tab shows
+that pane at the same size.
+
+To mirror a single agent at full size instead (three agents side by side in
+three splits, say), attach to it:
+
+```bash
+rudder attach            # pick from the live agents
+rudder attach n2         # a plan node
+rudder attach parser     # part of the title
+```
+
+The attached tab mirrors that agent's pane: same output, same scrollback,
+`Option-v` / `Option-b` step through messages, the wheel scrolls, and every
+other key goes to the agent. `Ctrl-W q` detaches; the agent keeps running in
+the dashboard. While a tab is attached, that agent's pane is sized to the tab
+rather than to the dashboard layout, and its row in the dashboard reads
+`attached`.
+
+Stepping agents is the shortcut worth learning: the worker pane hands every
+keystroke to the agent's own TUI, so `j`/`k` only select from the agents list —
+these move between agents without leaving the conversation you are reading.
+
+**Leader: press `Ctrl-W`, then one key.** A reliable way to run a dashboard
+command, even while typing inside the worker pane:
+
+| Then press | Action |
+| --- | --- |
+| `1` / `2` / `3` | Focus agents / worker / task |
+| `v` | Toggle review |
+| `m` | Merge the selected completed workspace |
+| `M` | Merge all completed workspaces |
+| `R` | Review all completed workspaces (Codex review-all agent) |
+| `r` | Rename the selected agent |
+| `b` | Branch the selected agent's chat into a new worker |
+| `u` | Undo the selected row's merge (restores the jj operation it ran as) |
+| `d` | Delete the selected agent and its workspace |
+| `j` / `k` | Move the agent selection |
+| `q` | Quit |
+| `Esc` | Cancel the leader |
+
+`Ctrl-G` toggles the same command set as a sticky "nav mode" (`Esc` exits) if you
+prefer a held mode over the one-shot leader.
+
+**In the task pane:** `Enter` runs the draft. A newline is `Option+Enter`,
+`Shift+Enter`, `Ctrl+Enter`, `Cmd+Enter`, or `Ctrl-J` — they all mean the same
+thing, because only some terminals pass each of them through, and a trailing
+`\` before `Enter` works even in the ones that pass none. Once the draft has
+more than one line, `Up` / `Down` move between its lines and only reach task
+history from the top or bottom line; `Home` / `End`, `Ctrl-A` / `Ctrl-E` and
+`Ctrl-K` act on the current line, and `Ctrl`/`Cmd` with `Home` / `End` jumps to
+the ends of the whole draft.
+
+**In the worker pane:** keystrokes go to the agent. `Tab` / `Shift+Tab` are
+forwarded to it, `Shift+Enter` inserts a newline, and `PageUp` / `PageDown`
+scroll the pane.
+
+**In the agents pane:** `j` / `k` or arrows move the selection, `Enter` focuses
+the worker, `m` / `M` / `R` / `r` / `d` act on the selection, `x` stops a running
+agent (keeping its workspace), `c` clears all merged agents from the list (press
+twice to confirm), `g` toggles the nested DAG view, `o` opens the web board, and
+`U` opens the usage dashboard, and `⌥d` toggles the diff panel.
+
+**Finished work collapses.** A long session ends with dozens of merged and failed
+rows, which bury the two or three still moving, so `done` and `closed` each render
+as a single row with a count and a chevron (`done 27 ›`). `j` / `k` walk onto that
+row and `Enter` opens the drawer: the finished runs list in the worker pane with
+the highlighted one's result below it, and `Esc` backs out. `review` stays inline
+up to five rows — merge-ready work should be one keystroke away — and collapses the
+same way past that, because a 25-row review section is not scannable either.
+
+## Commands and Orchestrator Skills
+
+Type these in the bottom task input. When an interactive Claude orchestrator is
+running, Rudder also exposes matching project skills; the orchestrator can write
+`RUDDER_*` control markers in `RUDDER.md` and Rudder consumes them.
+
+| Command | Action |
+| --- | --- |
+| `/model` | Pick provider, then model, then effort |
+| `/fast` | Fast mode for new agents: flagship model at low effort (Claude opus / Codex gpt-6.1-sol); `/model` switches back |
+| `/plan <text>` | Start the orchestrator / DAG planner |
+| `/gam [main] [<model>] <task>` | Generator + adversarial reviewer pair: split panes, the reviewer questions every round, steers the generator mid-turn, and can stop the run; only the generator edits. `^W t` shows the dialogue between them |
+| `/share <text>` | Save gitignored shared context for all agents in `RUDDER_SHARED.md` |
+| `/main [task]` or `/m` | Start an agent in the main checkout instead of its own workspace |
+| `/review-all` | Combine completed workspaces and start a Codex review-all agent |
+| `/merge-all` | Merge all completed workspaces |
+| `/verify` | Re-run the final repository checks after every DAG node is integrated |
+| `/color terminal\|paper` | Choose the native dashboard color mode; `terminal` uses your terminal foreground/background, `paper` restores the white canvas |
+| `$ <command>` | Open a shell pane in this checkout running the command (`$` alone opens a shell) |
+| `/login` | Browser login for Rudder Cloud |
+| `/cloud` | Toggle cloud mode: tasks you type start in Rudder Cloud and keep running when you disconnect (`/cloud off` goes local) |
+| `/cloud list` | List cloud workers |
+| `/help` | Show the keybinding + command cheat sheet |
+
+Finding a DAG task's worker: every plan node id (`n0`, `n1`, …) appears on the
+orchestrator DAG row, on the matching worker's row in the agents pane (`run n1`),
+and in the worker pane title, so the three panes cross-reference by id. A finished
+Planned DAG workers integrate automatically after completion; manually started
+workers remain ready for `m`/`M`. Only locally merged nodes unblock dependents.
+Merged rows show the target branch, jj/Git revision, and whether the remote contains it.
+
+## Models
+
+Use `/model [provider] [model] [effort]` in the task input. Claude offers the
+same current aliases as Claude Code (`opus`, `fable`, `sonnet`, and `haiku`);
+the picker labels context windows such as Opus's 1M context without inventing a
+different model name. Codex offers `gpt-6.1-sol`, `gpt-5.6-sol`, and other
+discovered models. `auto` effort means Rudder passes no override.
+
+`opencode` is available as a third backend: `/model opencode <provider/model>`
+(its ids are provider-qualified, e.g. `anthropic/claude-sonnet-4-5`), and the
+picker lists whatever `opencode models` reports for your authenticated providers.
+opencode has no reasoning-effort flag, so Rudder offers no effort choice for it
+rather than a dead control, and `/fast` says so instead of pretending. Turn-end is
+reported by a small plugin Rudder generates per run (loaded through
+`OPENCODE_CONFIG`, never written into your workspace), so opencode rows reach
+Review deterministically like the other two. Token/cost accounting for opencode
+rows is not wired up yet and reports zero.
+
+Your last provider, model, and effort are saved in `~/.rudder/config.json` and
+reused next time. Rudder refreshes model metadata from
+`https://models.dev/api.json` and falls back to local caches when offline.
+The native Codex picker also reads `~/.codex/models_cache.json`, so account-specific
+models such as the GPT-5.6 Sol/Terra/Luna family appear as soon as Codex exposes them.
+Implementation, review, resume, and shipping Codex sessions keep Codex plugins and
+Computer Use enabled, matching a direct Codex session. Read-only planner sessions
+disable both capabilities so planning cannot cause external side effects.
+
+## One-Off and Planning
+
+Type a task in the bottom input and Rudder starts one worker for it in its own
+jj workspace. The same thing happens no matter what else is on screen: a
+standalone worker that touches nothing but its workspace, lands in Review when
+done, and merges back with `m` or `/merge-all`. A slash command Rudder does not
+know is reported as unknown instead of being sent to an agent as a task.
+
+Use `/main <task>` for an agent in the main checkout itself, for work that has to
+happen there (release, push, deploy). Several may run there at once; they edit
+the same tree, so they can overwrite each other, and Rudder says so in the
+activity log rather than stopping you. Use `/plan <text>` when you want the
+orchestrator / DAG path: the read-only planner decomposes the task, then separate
+isolated workers implement its nodes. To change a running plan, talk to that
+orchestrator's own pane.
+
+For planned work, Rudder runs a dedicated Claude Code orchestrator PTY with a DAG
+pane above it. The flow stays inside Rudder: the orchestrator researches
+read-only, writes the DAG to `RUDDER.md`, and separate workers do the
+implementation.
+
+1. **It asks when it needs to.** The planner inspects the repo first. If something
+   material is missing (scope, approach, a key decision), it asks before the first
+   DAG, shown as a numbered prompt; a clear request goes straight to a DAG with the
+   planner's assumptions listed under it:
+
+   ```
+   ❓ The planner needs your input
+     1. Which time range: last 4 weeks, 6 months, or all time?
+     2. Reuse the existing module contract, or rebuild from scratch?
+
+   ↳ answer in the task input (e.g. "1: ..., 2: ...")
+   ```
+
+   Type your answer in the task input; Rudder resumes the same planning
+   conversation with your answer. The focused orchestrator pane can also accept
+   a follow-up when it is showing the planner chat.
+2. **It lays out a DAG.** When it is ready it shows the task DAG (a tree of worker tasks
+   with their dependencies) above the orchestrator terminal. Type feedback in the
+   task input to refine it, or press empty `Enter` to approve/launch.
+3. **The fleet runs.** The scheduler drains the DAG (todo → in-progress → review → done) as
+   dependencies merge, each task in its own isolated jj workspace.
+
+After launch, typing a new task folds it into the running DAG as a new node. When a worker
+finishes, Rudder reads back what it did and what work it found remaining (reconstructing it
+from the diff if the agent did not say), so the plan keeps growing on its own. Type a
+sweeping change ("rewrite this in Rust instead") and the plan re-plans around the work
+already done. The queued plan and workspaces survive a restart. Closing the dashboard
+marks owned live PTYs `paused` and removes their dead process ids; select a paused row
+and press `Enter` to resume it (reusing its backend session when available).
+
+The orchestrator also handles worker operations in natural language. For example, tell it
+"pause the current tasks and resume them on Codex gpt-5.6 at max effort." It resolves the
+live node ids from `RUDDER.md`, pauses each matching worker without deleting its jj
+workspace, and resumes it on the requested provider/model. A same-provider switch keeps
+the agent conversation; a provider switch keeps the workspace and starts a fresh session
+with a handoff to inspect and continue the existing diff.
+
+## Continuing a conversation you already started
+
+The chat you are already having in a terminal — a plain `claude`, `codex`, or
+`opencode` session — holds the context you would otherwise retype: the files you
+looked at, the decisions you made, the plan you agreed on. Rudder can pick that
+conversation up and keep it going as an agent.
+
+Two directions, same result:
+
+- **From the dashboard:** type `/resume`. The palette lists this repository's
+  recent conversations — Claude, Codex, and opencode in one list, newest first —
+  showing what each was about, which model it was running, how long ago, and its
+  session id. Pick one, optionally type the next step after it, and press Enter. It
+  opens as an isolated worker that merges with `m` like any other.
+- **From inside the chat:** run `rudder handoff "<next step>"`. That queues the
+  conversation you are in; the dashboard picks it up within a second (start it with
+  `rudder` if it is not open). `--here` continues in the main checkout instead of an
+  isolated workspace, `--list` shows the conversations Rudder can see, and
+  `--codex` / `--opencode` pick a different source CLI.
+
+Handoffs always FORK the conversation. The chat in your terminal is untouched and
+keeps working; the Rudder agent continues from a copy. The fork is told it is now
+running in a different workspace, so it re-reads files instead of trusting its
+memory of the checkout it came from.
+
+`/handoff` still works as an alias for `/resume` (it is what the CLI half is
+called). `b` on a worker row does the same thing for a conversation already inside
+Rudder, and `/restore <claude|codex> <id>` continues a session IN PLACE (same
+session, main checkout) instead of forking it into a worker.
+
+## Worktrees and merging
+
+**Who merges what:** planned `/plan` DAG nodes integrate into your checkout
+**automatically** as soon as they finish — no per-node confirmation — so
+dependent nodes unblock and the chain keeps flowing (their row shows
+`done · auto-merging`, then `merged locally`; the final gate runs the repo's
+checks after the last node lands). Workers started from the task bar never
+auto-merge: they wait in Review (`done · press m to merge`) until you merge
+them yourself. There is no `/automerge` command or config flag — this split is
+the behavior.
+
+Planned and task-bar workers run in their own jj workspaces under a sibling
+`.rudder-workspaces` area, so parallel agents never edit the same checkout.
+`/main` agents intentionally run in the main checkout. Run records
+live under `.rudder/runs/`. If you quit Rudder, live workers become `paused`, keep
+their workspace/session metadata, and stay listed when you reopen the repo.
+
+- Press `m` to merge the selected completed agent back into its branch.
+- Press `M` (or `/merge-all`) to merge all completed agents.
+- Both ask for a `y`/`n` confirmation first, and the prompt warns when your own
+  uncommitted changes in the main checkout would ride along in the merge.
+
+Clean merges become merge commits. If git reports conflicts, Rudder leaves the
+conflicted state in place and can open an agent in the main checkout to help
+resolve it.
+
+Choose the merge behavior in `~/.rudder/config.json`:
+
+```json
+{ "mergeStrategy": "rebase" }
+```
+
+- `"merge"` (default): `git merge --no-ff`.
+- `"rebase"`: rebase the workspace onto the latest base, then `git merge --ff-only`.
+
+Command-line equivalents:
+
+```bash
+rudder merge <runId>
+rudder sync <runId>
+rudder cleanup
+```
+
+`rudder stop` records a durable cancellation request and terminates the native PTY process
+group. Cancellation is terminal: a resulting signal exit cannot be relabeled as a failure.
+
+## Shipping and delivery evidence
+
+Rudder treats these as different facts: an agent finished, changes merged locally,
+a revision was pushed, and a product was deployed. A task that explicitly asks to
+deploy, publish, release, install, or launch remains `delivery proof needed` until
+its completion report records the target, delivery kind, verification time, and at
+least one real smoke check. Verified web URLs, installed macOS app paths, provider
+deployment ids, revisions, and versions are persisted in `.rudder/runs/<id>/run.json`
+and shown in the native dashboard, web board, and generated `RUDDER.md`.
+
+Pushing a commit is never presented as proof that a host deployed it. Likewise,
+building a macOS app is not the same as replacing and launching the installed app.
+If delivery fails or needs credentials/user input, the row says `delivery blocked`
+instead of incorrectly moving to deployed.
+
+## Review
+
+Press `v` on an agent to toggle a review of its workspace, showing the run's diff.
+Press `v` or `Esc` to return to the worker.
+
+Press `R` to review all completed workspaces as one bundle: Rudder builds an
+aggregate branch and starts a Codex review-all agent over the combined diff. When
+that row is done, press `m` on it to merge the reviewed bundle into your checkout.
+
+## Rudder Cloud
+
+Rudder Cloud is an optional hosted worker mode. The local dashboard stays your
+control surface; you decide whether a task runs locally or is handed to the cloud.
+
+```bash
+rudder login                 # sign in with Google (opens straight to the account picker)
+rudder cloud                 # open this repo on your home machine and attach to it
+rudder cloud home            # home machine status: projects, agents, previews
+rudder cloud move            # move this repo's running agents to the home machine
+rudder cloud sync [repo]     # bring this checkout and the cloud's clone level (/sync)
+rudder cloud app             # the phone app link
+rudder cloud list            # list cloud workers
+rudder cloud logs <id>       # worker status
+rudder cloud onload [runId]  # hand one agent off to the cloud (or upload the workspace)
+rudder cloud workspace attach # migrate all live isolated agents into one cloud workspace
+rudder sail <name>           # short alias for starting a cloud worker
+```
+
+**Your home machine.** `rudder cloud` in a repo with a GitHub origin opens it on
+your one cloud machine (4 CPU / 16 GB, persistent disk), cloning it into
+`~/code/<repo>` the first time. Every repo you open lives on that same machine,
+each with its own Rudder dashboard, so agents can read your other repos at the
+paths you are used to. GitHub is the source of truth: the cloud clones from it,
+and finished work comes back as a pushed branch and a draft PR (`m` in a cloud
+dashboard publishes instead of merging locally). Before attaching, Rudder warns
+about uncommitted or unpushed work it can't see, and offers to copy the repo's
+`.env` files into the encrypted vault. The machine stops after two quiet hours
+and starts again on the next `rudder cloud` or phone visit; conversations and
+agent state live on its disk, so agents resume where they were.
+`rudder cloud --snapshot` keeps the old behavior: upload this folder to a
+machine of its own.
+
+**Same repo on the laptop and the cloud (`/sync`).** `/sync` in the dashboard
+(or `rudder cloud sync`) brings this checkout and the cloud machine's clone of
+it up to the newest default branch, and carries the work GitHub does not have
+yet, uncommitted edits included, from one side to the other directly. Nothing is
+pushed to your repo, and gitignored files such as `.env` never travel. The side
+receiving work only takes it when nothing of its own would be lost; when both
+sides changed, both versions are kept and the other one waits as the jj bookmark
+`rudder-sync/cloud` (or `rudder-sync/laptop`). `rudder cloud sync <repo>` with a
+name clones a repo that so far exists only on the cloud into `~/code/<repo>`.
+`/sync all` covers every repo, and `/sync move` hands this laptop's running
+agents to the cloud.
+
+**Screenshots and files.** In `rudder cloud`, `Ctrl-V` with a screenshot or
+files copied in Finder, or dragging a file into the terminal, uploads it to the
+cloud machine and gives the agent its path there: Claude Code attaches an image
+as `[Image #1]` exactly as it does locally. Up to 25 MB per file.
+
+**Updates.** After a release the cloud machine updates itself once its agents
+have been idle for five minutes, so you never restart it by hand.
+
+**Phone.** Open `rudder cloud app` on your phone and sign in with the same
+Google account. You see every project and agent, read conversations as they
+happen, text any agent, start tasks (`/model` picks Claude or Codex for new ones),
+stop, merge or delete agents (swipe left), and open previews. A message that can't
+reach an agent (a menu is open in its pane) says so instead of vanishing. Claude
+panes in the cloud also run with Remote Control, so they appear in the Claude
+app too.
+
+**Previews.** Put a Tailscale auth key in the vault
+(`rudder cloud secrets set TS_AUTHKEY`) and the home machine joins your tailnet
+as `rudder-home`. Any dev server an agent starts there shows up as an HTTPS link
+(`https://rudder-home.<tailnet>.ts.net:<port>`) in `rudder cloud home` and the
+phone app.
+
+Inside the dashboard, `/login` starts browser auth and `/cloud` toggles cloud
+mode: while it is on, tasks you type start as workers in Rudder Cloud and keep
+running when this laptop disconnects (`/cloud off` returns to local workers).
+`rudder cloud` from a shell onloads the current workspace (repo snapshot plus
+selected auth/config) so the whole dashboard runs on a cloud machine. Completed
+cloud work returns through the same review and merge path as local work.
+
+**Taking agents with you.** About to close the laptop? Press `H` in the
+dashboard and every running agent moves to your home machine: its work so far
+(the jj change, including unpushed local changes it builds on) and its
+conversation go along, nothing is pushed to GitHub, and the conversation resumes
+there, so it keeps going with the laptop closed. Quitting with agents running
+offers the same thing ("3 agents are running here. Move them to the home
+machine?"), and `rudder cloud` in a repo with agents asks too. Bare `/handoff`
+moves just the selected agent. (`/handoff <session-id>` still adopts an outside
+CLI chat, like `/resume`.) Delete an agent anywhere (`dd` here, swipe left on the
+phone) and it is gone everywhere.
+
+Cloud comes in two shapes: a **sail** is an ephemeral, task-scoped worker (it goes away
+when the task is done; idle sails pause and can resume), while a **workspace** is a
+persistent, volume-backed dev environment you can come back to. Both restore the same
+workspace snapshot.
+
+An active workspace agent keeps running when you close the terminal or lose the
+connection; the idle sweeper only stops a workspace after its reported active-agent
+count reaches zero. Re-running `rudder cloud` reconnects to the same volume and saved
+sessions. If several terminals attach, the first remains the input and resize
+controller; additional terminals are read-only observers until the controller leaves.
+This prevents another terminal's dimensions or disconnect keys from disrupting the
+shared remote dashboard.
+
+You can also tell the live orchestrator: "take the current agents and run them on
+Rudder Cloud." Rudder freezes the local worker PTYs first, then migrates every live
+isolated workspace. Claude sessions resume from their transcript when available;
+Codex and missing-session workers restart from a context-rich handoff over the existing
+diff. The explicit fleet-migration snapshot includes all inherited environment variables
+(except OS/Rudder control variables),
+agent auth/config, shell and cloud CLI configuration, and project `.env*` files (including
+nested package dotenv files) in each restored worker workspace.
+
+Cloud workers use Fly Machines by default. To use your own server over SSH (Docker over
+SSH; bring-your-own-compute can be stopped but not paused/resumed):
+
+```bash
+rudder cloud byoc <ssh-host>   # an entry from ~/.ssh/config, key auth + Docker
+rudder cloud vm "task"         # run on that host
+rudder cloud runtime [fly|byoc]
+```
+
+The CLI points at the hosted control plane `https://rudder-cloud-control.fly.dev`.
+Set `RUDDER_CLOUD_URL` to use your own deployment. Rudder Cloud login is separate
+from Claude Code and Codex login; provider auth stays in the official CLIs.
+
+## Run management
+
+```bash
+rudder status
+rudder runs
+rudder watch <runId>
+rudder logs <runId> --follow
+rudder stop <runId>
+rudder delete <runId>
+rudder merge <runId>
+rudder sync <runId>
+rudder cleanup
+```
+
+## Troubleshooting
+
+- Stale behavior after an upgrade: restart any already-running Rudder dashboards
+  so no old `rudder-native` process lingers. New `rudder` launches auto-update
+  unless `RUDDER_DISABLE_AUTO_UPDATE=1` is set.
+- Sustained CPU/redraw load: version 2.12.9 and newer cache Codex plan-output scans,
+  avoid reparsing unchanged planner JSON, throttle background PTY drains, and redraw
+  only dirty frames. Upgrade and restart any dashboard launched by 2.12.8 or older.
+- Trackpad scrolling: confirm your terminal sends scroll events with
+  `rudder mouse-test parsed`. Set `RUDDER_WHEEL_SCROLL_ROWS=<n>` to change the
+  scroll step, or `RUDDER_MOUSE_DEBUG=1` to inspect routing.
+
+## Continual improvement loop
+
+Rudder improves itself from its own telemetry. Every run already leaves a
+record on disk (`.rudder/runs/`, event logs, verifier results, steer history,
+token usage). The improvement loop, `rudder improve`, is a scheduled local
+batch job (launchd on macOS, not a resident daemon) that:
+
+1. **Collects** recent session telemetry across your registered projects,
+   redacting secrets at the source.
+2. **Mines** it into ranked friction findings (failed runs, user redirects,
+   merge conflicts, verifier misses) using the advisor pattern: a Sonnet
+   executor consults a Fable 5 advisor mid-generation, so most tokens bill at
+   the executor rate.
+3. **Proposes** fixes with headless agents in isolated git worktrees of the
+   rudder repo, each briefed with a rich context pack (finding, evidence,
+   surface map, prior failed attempts, repo conventions).
+4. **Judges** each candidate with the repo's full test gates plus a
+   three-lens adversarial LLM panel that fails closed.
+5. **Prepares** survivors as pushed review branches by default. If you
+   explicitly opt into `ship` autonomy, Rudder instead rebases onto
+   `origin/main`, runs `npm version patch`, and pushes main + tag for the normal
+   tag-driven npm release. Later cycles verify whether the targeted metric
+   improved and record regressions for review.
+
+```bash
+rudder improve run --dry-run     # see what it would do, propose nothing
+rudder improve schedule install  # nightly cycle at 03:30 via launchd
+rudder improve status            # shipped versions, metrics trend, ledger
+```
+
+Everything stays on your machine. Estimated model/agent spend is bounded per
+cycle (`improve.budgetUsd`, default $5), and autonomy is configurable:
+`observe` only reports, `propose` (the default) pushes a review branch, and
+`ship` is an explicit opt-in to unattended releases. `RUDDER_IMPROVE=0`
+disables the loop. The full harness spec is in
+[`docs/continual-improvement.md`](./docs/continual-improvement.md);
+implementation details live in [`AGENTS.md`](./AGENTS.md) section 15.
+
+## What Rudder derives rather than remembers
+
+A status that can be checked is checked, on a slow tick, against whatever actually
+knows: jj for "is this work in main", the process handle for "is this agent
+alive", the filesystem for "does this workspace exist", each backend's own session
+store for "which conversation is this". Anything that changed is written to
+`.rudder/activity.jsonl` with the ids it touched — change id, bookmark, commit,
+jj operation — so it can be lined up against `jj op log` afterwards.
+
+This is why a merged row can say **`merged · NOT in main`**: the merge landed, and
+then something rewrote history under it. Rudder used to keep claiming success.
+
+## Telemetry and feedback
+
+Rudder sends a small set of **anonymous usage events** so the parts people get
+stuck on are visible: how many installs ever start an agent, how many ever merge,
+which backend and model get picked, which errors fire most. It is on by default,
+disclosed the first time you run anything, and off in one command:
+
+```bash
+rudder telemetry status
+rudder telemetry off          # or RUDDER_TELEMETRY=0 in your shell
+```
+
+What is sent: the event name, rudder version, platform, backend/model, agent and
+merge counts, slash-command *names*, and a hashed project id (a digest of the
+repo path — it counts projects without naming them). What is never sent: your
+prompts, code, diffs, file contents, paths, repo names, branch names, or session
+ids. Events are anonymous (no person profile), keyed to a random id minted per
+install. Implementation and the rules it enforces: `src/analytics.ts`.
+
+**`/feedback <what broke>`** in the task pane (or `rudder feedback "..."`) sends a
+report with the message plus what was on screen in structure: version, platform,
+backend/model, how many agents were running, the last few notices and the last
+error — with paths stripped. It lands in three places, in order of durability: a
+local JSON copy under `.rudder/feedback/` (always, so nothing is lost offline), a
+usage event, and a GitHub issue when `gh` is installed and authenticated. Add
+`--no-issue` to keep it out of the public tracker.
+
+## Building from source
+
+```bash
+git clone https://github.com/exla-ai/rudder.git
+cd rudder
+./setup.sh
+```
+
+`setup.sh` checks prerequisites (Node >=20, git, npm, Rust/`cargo`), installs
+dependencies, builds (`tsc` + `cargo build --release`), typechecks, and smoke
+tests the CLI. It is safe to re-run after pulling. For architecture and
+implementation details, see [`AGENTS.md`](./AGENTS.md).
+
+## License
+
+[Elastic License 2.0](LICENSE) (ELv2). Source-available: you can use, modify and
+redistribute Rudder, but you may not offer it to others as a hosted or managed
+service. Versions published before 2.16.6 were released under MIT and remain
+available under those terms.