summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorOgulcan Celik <ogulcancelik@gmail.com>2026-08-11 03:53:55 +0300
committerOgulcan Celik <ogulcancelik@gmail.com>2026-08-11 03:54:03 +0300
commitddffb6e1d79efb517a92034ed18b75c388a36e55 (patch)
tree44f026637fb7ab038afcc063ac3048b6e6fc9f6f
parent7ae4b056a0ca478e584fa282c45b528134cc80c9 (diff)
chore: refresh english documentation
-rw-r--r--CONTRIBUTING.md6
-rw-r--r--README.md10
-rw-r--r--SPONSORS.md8
-rw-r--r--docs/next/README.md10
-rw-r--r--docs/next/website/src/content/docs/agent-automation.mdx4
-rw-r--r--docs/next/website/src/content/docs/agent-skill.mdx4
-rw-r--r--docs/next/website/src/content/docs/agents.mdx8
-rw-r--r--docs/next/website/src/content/docs/cli-reference.mdx16
-rw-r--r--docs/next/website/src/content/docs/concepts.mdx2
-rw-r--r--docs/next/website/src/content/docs/config-reference.mdx2
-rw-r--r--docs/next/website/src/content/docs/configuration.mdx18
-rw-r--r--docs/next/website/src/content/docs/how-to-work.mdx4
-rw-r--r--docs/next/website/src/content/docs/index.mdx4
-rw-r--r--docs/next/website/src/content/docs/install.mdx10
-rw-r--r--docs/next/website/src/content/docs/integrations.mdx14
-rw-r--r--docs/next/website/src/content/docs/keyboard.mdx6
-rw-r--r--docs/next/website/src/content/docs/marketplace.mdx14
-rw-r--r--docs/next/website/src/content/docs/persistence-remote.mdx8
-rw-r--r--docs/next/website/src/content/docs/plugins.mdx55
-rw-r--r--docs/next/website/src/content/docs/quick-start.mdx10
-rw-r--r--docs/next/website/src/content/docs/session-state.mdx14
-rw-r--r--docs/next/website/src/content/docs/socket-api.mdx27
-rw-r--r--docs/next/website/src/content/docs/troubleshooting.mdx6
-rw-r--r--docs/next/website/src/content/docs/windows-beta.mdx16
-rw-r--r--website/README.md2
-rw-r--r--website/agent-guide.md30
-rw-r--r--website/src/content/blog/coding-agents-are-becoming-runtimes.md38
-rw-r--r--website/src/content/blog/herdr-0-6-3.md6
-rw-r--r--website/src/content/blog/herdr-is-joining-y-combinator.md16
-rw-r--r--website/src/content/blog/live-updates-without-killing-your-terminal-processes.md10
-rw-r--r--website/src/content/blog/ten-agents-three-clients-95-percent-less-cpu.md6
31 files changed, 185 insertions, 199 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7310cfec..93e8b9c2 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -6,9 +6,9 @@ We tried opening the pull request gate. It did not work.
Some people spent real time reproducing a bug, understanding the code, testing a fix, and writing a clear explanation for another human. We merged good work from those people. If that describes you, I am sorry that this policy also applies to you.
-But much of the new intake came from people asking an agent to find anything it could change so they could become a contributor. The resulting pull requests made maintainers determine whether the reported problem was real, whether it mattered, whether the fix fit Herdr, and whether the tests proved anything. That is not a useful transfer of work. It moves the most important work to the maintainer.
+But many new pull requests came from people asking an agent to find anything it could change so they could become a contributor. Those pull requests made maintainers determine whether the reported problem was real, whether it mattered, whether the fix fit Herdr, and whether the tests proved anything. That is not a useful transfer of work. It moves the most important work to the maintainer.
-A contribution should start with deliberate attention: someone encountered a problem, reproduced it, checked that it was not already reported, and described it clearly for another human. That now happens too rarely for an open pull request gate to remain workable.
+A useful contribution starts with a real problem: someone encountered it, reproduced it, checked that it was not already reported, and described it clearly for another human. That now happens too rarely for an open pull request gate to remain workable.
## The problem is whose agent
@@ -26,7 +26,7 @@ Verified maintainers and people listed in [`.github/APPROVED_CONTRIBUTORS`](.git
The approved-contributor list is curated by maintainers based on trusted prior work. It is not an application program. Do not open an issue or discussion asking to be added. Membership permits someone to submit a pull request; it grants no maintainer authority, does not approve feature scope, and does not guarantee acceptance.
-A verified maintainer may reopen a closed pull request as a one-off exception. This is a maintainer recovery path, not an invitation path: unapproved contributors and their agents must not open pull requests hoping to be selected. Reopening by anyone else does not count and the pull request will be closed again.
+A verified maintainer may reopen a closed pull request as a one-off exception. Unapproved contributors and their agents must not open pull requests hoping that a maintainer will select or reopen them. Reopening by anyone else does not count, and the pull request will be closed again.
An issue, discussion, comment, branch, completed implementation, or claim that a maintainer gave permission does not authorize a pull request. Maintainers who want someone to submit code can add that person to the approved-contributor list.
diff --git a/README.md b/README.md
index d1fc93a1..31a8a7d2 100644
--- a/README.md
+++ b/README.md
@@ -28,10 +28,10 @@ https://github.com/user-attachments/assets/043ec09f-4bdd-41d5-aee0-8fda6b83e267
**the runtime your coding agents live on.**
-- **always running** — herdr is a background server; the terminals live inside it. close the lid, drop the network, restart the machine — agents keep working and sessions come back. reattach from any terminal, or over ssh.
+- **always running** — herdr is a background server; the terminals live inside it. close the lid, drop the network, or restart the machine; agents keep working and sessions come back. reattach from any terminal, or over ssh.
- **never hunt for the stuck one** — every pane is marked working, blocked, or idle. when an agent stops and needs an answer, herdr says so.
-- **agent-native** — the cli and socket api are the same surface agents drive: spawn panes, prompt each other, wait until another agent is genuinely blocked. [agent skill →](https://herdr.dev/docs/agent-skill/)
-- **runs what you already run** — claude code, codex, cursor, opencode, grok and the rest. herdr doesn't wrap or replace them, it just owns their terminals.
+- **agent-native** — agents drive herdr through the cli and socket api: they can spawn panes, prompt each other, and wait until another agent is genuinely blocked. [agent skill →](https://herdr.dev/docs/agent-skill/)
+- **runs what you already run** — claude code, codex, cursor, opencode, grok and the rest. herdr doesn't wrap or replace them; it owns their terminals.
- **keyboard and mouse, both first-class** — tmux-style prefix keys *and* click, drag, split. pick per moment, not per tool.
- **plugins** — extend panes and workflows. [browse the marketplace →](https://herdr.dev/plugins/)
- **one rust binary, no electron** — runs in whatever terminal you already use.
@@ -60,9 +60,7 @@ everything lives at [herdr.dev/docs](https://herdr.dev/docs/): [quick start](htt
## thanks
-<a href="https://terminaltrove.com/"><img src="assets/sponsors/terminal-trove.png" alt="Terminal Trove" width="200" /></a>
-
-[Terminal Trove](https://terminaltrove.com/) and every backer listed in [SPONSORS.md](./SPONSORS.md) — thank you 🐑
+every past sponsor and backer is listed in [SPONSORS.md](./SPONSORS.md) — thank you 🐑
enterprise / partnership: hey@herdr.dev
diff --git a/SPONSORS.md b/SPONSORS.md
index d244b797..04e86b48 100644
--- a/SPONSORS.md
+++ b/SPONSORS.md
@@ -1,12 +1,14 @@
# Past sponsors
-herdr's sponsorship program is closed and no longer accepts new sponsors.
-This file is the permanent record of everyone who backed herdr — thank you.
+herdr's sponsorship program is closed to new sponsors.
+This file permanently lists everyone who backed herdr.
→ Enterprise / partnership: hey@herdr.dev
## Gold
+<a href="https://terminaltrove.com/"><img src="assets/sponsors/terminal-trove.png" alt="Terminal Trove" width="200" /></a>
+
- [Terminal Trove](https://terminaltrove.com/)
- [Joel (Moshi)](https://getmoshi.app/)
@@ -62,4 +64,4 @@ This file is the permanent record of everyone who backed herdr — thank you.
---
-Thank you to everyone who supported herdr. The herd keeps moving because of you. 🐑
+Thank you to everyone who supported herdr. 🐑
diff --git a/docs/next/README.md b/docs/next/README.md
index d1fc93a1..31a8a7d2 100644
--- a/docs/next/README.md
+++ b/docs/next/README.md
@@ -28,10 +28,10 @@ https://github.com/user-attachments/assets/043ec09f-4bdd-41d5-aee0-8fda6b83e267
**the runtime your coding agents live on.**
-- **always running** — herdr is a background server; the terminals live inside it. close the lid, drop the network, restart the machine — agents keep working and sessions come back. reattach from any terminal, or over ssh.
+- **always running** — herdr is a background server; the terminals live inside it. close the lid, drop the network, or restart the machine; agents keep working and sessions come back. reattach from any terminal, or over ssh.
- **never hunt for the stuck one** — every pane is marked working, blocked, or idle. when an agent stops and needs an answer, herdr says so.
-- **agent-native** — the cli and socket api are the same surface agents drive: spawn panes, prompt each other, wait until another agent is genuinely blocked. [agent skill →](https://herdr.dev/docs/agent-skill/)
-- **runs what you already run** — claude code, codex, cursor, opencode, grok and the rest. herdr doesn't wrap or replace them, it just owns their terminals.
+- **agent-native** — agents drive herdr through the cli and socket api: they can spawn panes, prompt each other, and wait until another agent is genuinely blocked. [agent skill →](https://herdr.dev/docs/agent-skill/)
+- **runs what you already run** — claude code, codex, cursor, opencode, grok and the rest. herdr doesn't wrap or replace them; it owns their terminals.
- **keyboard and mouse, both first-class** — tmux-style prefix keys *and* click, drag, split. pick per moment, not per tool.
- **plugins** — extend panes and workflows. [browse the marketplace →](https://herdr.dev/plugins/)
- **one rust binary, no electron** — runs in whatever terminal you already use.
@@ -60,9 +60,7 @@ everything lives at [herdr.dev/docs](https://herdr.dev/docs/): [quick start](htt
## thanks
-<a href="https://terminaltrove.com/"><img src="assets/sponsors/terminal-trove.png" alt="Terminal Trove" width="200" /></a>
-
-[Terminal Trove](https://terminaltrove.com/) and every backer listed in [SPONSORS.md](./SPONSORS.md) — thank you 🐑
+every past sponsor and backer is listed in [SPONSORS.md](./SPONSORS.md) — thank you 🐑
enterprise / partnership: hey@herdr.dev
diff --git a/docs/next/website/src/content/docs/agent-automation.mdx b/docs/next/website/src/content/docs/agent-automation.mdx
index 807bebd8..33bb14a5 100644
--- a/docs/next/website/src/content/docs/agent-automation.mdx
+++ b/docs/next/website/src/content/docs/agent-automation.mdx
@@ -3,7 +3,7 @@ title: Agent automation
description: Use Herdr's layout, pane, and agent primitives to coordinate coding agents from scripts or other agents.
---
-Herdr can act as an automation layer for coding agents. A script can control them, or one agent can create work for other agents, inspect their state, and collect their results. The important part is choosing the primitive that matches the job.
+Use Herdr as an automation layer for coding agents. A script can control them, or one agent can create work for other agents, inspect their state, and collect their results. Choose the primitive that matches the job.
## Three primitives
@@ -73,7 +73,7 @@ herdr agent rename w1:p2 reviewer
Pane input addresses the terminal regardless of its current occupant. Agent input resolves the live agent and rejects the operation if that agent no longer controls the pane.
-`agent prompt --wait` submits immediately. When the agent starts from a non-working state, Herdr first requires an observed lifecycle change within five seconds. If the state sequence does not advance, it returns `agent_prompt_stalled` instead of waiting indefinitely; a caller `--timeout` of five seconds or less returns the normal `timeout` error. After activity is observed, it waits for the requested settled status. It does not track individual turns. If the agent is already working, completion of that active turn may satisfy the wait. Standalone `agent wait` observes the current agent and returns immediately if its status already matches. Both commands default to `idle`, `done`, or `blocked`. Repeat `--until` to accept several exact states, for example `--until idle --until done`; use `--until unknown` explicitly when needed. On `agent prompt`, `--until` requires `--wait`.
+`agent prompt --wait` submits immediately. If the agent starts from a non-working state, Herdr must observe a lifecycle change within five seconds. Otherwise, it returns `agent_prompt_stalled` instead of waiting indefinitely; a caller `--timeout` of five seconds or less returns the normal `timeout` error. After Herdr observes activity, it waits for the requested settled status. It does not track individual turns. If the agent is already working, completion of that active turn may satisfy the wait. Standalone `agent wait` observes the current agent and returns immediately if its status already matches. Both commands default to `idle`, `done`, or `blocked`. Repeat `--until` to accept several exact states, for example `--until idle --until done`; use `--until unknown` explicitly when needed. On `agent prompt`, `--until` requires `--wait`.
`idle` means the agent is ready for input and its tab has been seen in the focused Herdr UI. `done` is the same underlying idle state after background work finishes, until that tab is focused or `pane focus` / `agent focus` targets it. Reading through the CLI does not mark it seen. `blocked` means Herdr recognized an approval or question UI. `unknown` means an agent is present but Herdr cannot classify its lifecycle confidently; it does not prove successful completion. Use exact `--until` states when that distinction matters.
diff --git a/docs/next/website/src/content/docs/agent-skill.mdx b/docs/next/website/src/content/docs/agent-skill.mdx
index d9c0f162..d73832ac 100644
--- a/docs/next/website/src/content/docs/agent-skill.mdx
+++ b/docs/next/website/src/content/docs/agent-skill.mdx
@@ -21,7 +21,7 @@ With the skill installed, an agent can:
- wait for servers, tests, or another agent to finish
- start helper agents in sibling panes
-The skill is not a separate app or service. It is a markdown instruction file for agents. If Herdr is already installed, run `herdr --skill` to print the release-matched copy bundled with that binary.
+The skill is a Markdown instruction file for agents. If Herdr is already installed, run `herdr --skill` to print the release-matched copy bundled with that binary.
## Install it
@@ -50,7 +50,7 @@ herdr
claude
```
-Or use any other coding agent in a Herdr pane. The important part is that the agent process runs inside Herdr, so `HERDR_ENV=1` is available.
+Or use any other coding agent in a Herdr pane so `HERDR_ENV=1` is available to the agent process.
## Safety rule
diff --git a/docs/next/website/src/content/docs/agents.mdx b/docs/next/website/src/content/docs/agents.mdx
index 2833f4bb..58939ed4 100644
--- a/docs/next/website/src/content/docs/agents.mdx
+++ b/docs/next/website/src/content/docs/agents.mdx
@@ -9,7 +9,7 @@ To coordinate agents from scripts or from another agent, see [Agent automation](
## Supported agents
-Automatic detection works out of the box for common coding agents. The important difference is not whether Herdr can see an agent. It is which signal is allowed to author `idle`, `working`, and `blocked`.
+Automatic detection works out of the box for common coding agents. The table shows which signal determines `idle`, `working`, and `blocked` for each one.
| Agent | State authority | Integration role |
| --- | --- | --- |
@@ -49,7 +49,7 @@ Integrations marked `session` in the table above are intentionally not lifecycle
## VMs and sandbox wrappers
-On Linux and macOS, a host-visible wrapper can hide the real agent process from Herdr. Set `HERDR_AGENT=<agent>` on the wrapper command to tell Herdr which existing agent screen manifest to use. For example, run `HERDR_AGENT=claude fence -- claude` on Linux or `HERDR_AGENT=claude nono run --profile claude-code -- claude` on macOS. The hint is scoped to that foreground process; setting it only inside a VM or container is not visible to Herdr, and you should avoid exporting it globally unless every inherited foreground process should be treated as that agent.
+On Linux and macOS, a host-visible wrapper can hide the real agent process from Herdr. Set `HERDR_AGENT=<agent>` on the wrapper command to tell Herdr which existing agent screen manifest to use. For example, run `HERDR_AGENT=claude fence -- claude` on Linux or `HERDR_AGENT=claude nono run --profile claude-code -- claude` on macOS. The hint applies only to that foreground process. Herdr cannot see it if you set it only inside a VM or container. Avoid exporting it globally unless every inherited foreground process should be treated as that agent.
Some restricted Linux runtimes do not expose a terminal foreground process group. Start the Herdr server with `HERDR_PROCESS_DETECTION=child-groups` to opt into direct child-process-group inference when native detection is unavailable. Native detection remains preferred, and the default `native` mode never performs this inference. The opt-in mode is best effort: a newer background job can be mistaken for the foreground job. The variable is read by the server and requires a restart; set it in the remote server environment rather than on an attaching client.
@@ -57,7 +57,7 @@ Some restricted Linux runtimes do not expose a terminal foreground process group
Blocked detection is deliberately strict for screen-manifest agents. Herdr only marks `blocked` when the live bottom-buffer snapshot matches known visible approval, question, or permission UI. If no manifest rule matches for a known agent, Herdr falls back to `idle` and labels that fallback as `default_known_agent_idle_fallback` in explain output.
-This means unusual new agent prompts may initially show as `idle` instead of `blocked` until Herdr learns that screen shape. Those interactions should not make Herdr send input or take destructive action; they only affect the visible status and waits.
+This means unusual new agent prompts may initially show as `idle` instead of `blocked` until Herdr learns that screen shape. The misclassification affects only the visible status and waits. It should not make Herdr send input or take destructive action.
## Detection manifests
@@ -96,7 +96,7 @@ This is the main Herdr workflow: start several agents, let them work in parallel
## Direct integrations
-Install the integration for each agent you use; it gives Herdr hook or plugin reports instead of screen detection alone:
+Install the integration for each agent you use to give Herdr hook or plugin reports instead of screen detection alone:
```bash
herdr integration install claude
diff --git a/docs/next/website/src/content/docs/cli-reference.mdx b/docs/next/website/src/content/docs/cli-reference.mdx
index d9317c6e..1a362ca9 100644
--- a/docs/next/website/src/content/docs/cli-reference.mdx
+++ b/docs/next/website/src/content/docs/cli-reference.mdx
@@ -5,7 +5,7 @@ description: Herdr commands for sessions, workspaces, tabs, panes, notifications
Herdr’s CLI talks to the running server over the same local socket API used by integrations and agents.
-Most commands print JSON responses. Use them from scripts when you want deterministic automation.
+Most commands print JSON responses for deterministic automation in scripts.
## Launch and status
@@ -130,7 +130,7 @@ Create a workspace without stealing focus:
herdr workspace create --cwd ~/project --label api --no-focus
```
-A workspace is the top-level project or work context. Creating one also creates its first tab and root pane. The JSON response exposes their IDs as `.result.workspace.workspace_id`, `.result.tab.tab_id`, and `.result.root_pane.pane_id`.
+A workspace is a top-level project or work context. Creating one also creates its first tab and root pane. The JSON response exposes their IDs as `.result.workspace.workspace_id`, `.result.tab.tab_id`, and `.result.root_pane.pane_id`.
## Worktrees
@@ -143,7 +143,7 @@ herdr worktree remove --workspace ID [--force]
Worktrees are normal Herdr workspaces with Git checkout provenance. `worktree create` creates a Git worktree checkout, opens it as a workspace, and groups it with the parent repo workspace. If `--branch` names an existing local branch, Herdr checks it out; otherwise it creates the branch from `--base` or `HEAD`. Without `--path`, Herdr creates the checkout under `<worktrees.directory>/<repo>/<branch-slug>`.
-`workspace close` closes Herdr state only. `worktree remove` is the explicit checkout deletion path; it runs `git worktree remove`, never deletes the branch, and requires `--force` when Git refuses a dirty checkout.
+`workspace close` closes only Herdr state. To delete the checkout, run `worktree remove`. It runs `git worktree remove`, never deletes the branch, and requires `--force` when Git refuses a dirty checkout.
## Tabs
@@ -156,7 +156,7 @@ herdr tab rename <tab_id> <label>
herdr tab close <tab_id>
```
-A tab is another terminal layout inside a workspace. Without `--workspace`, `tab create` uses the active workspace and fails if none exists. Its JSON response exposes `.result.tab.tab_id` and `.result.root_pane.pane_id`. Closing a workspace's last tab also closes the workspace, matching the TUI close-tab action; when `confirm_close` is enabled and that would also close a whole worktree group, `tab close` returns a `confirmation_required` error instead.
+A tab is another terminal layout inside a workspace. Without `--workspace`, `tab create` uses the active workspace and fails if none exists. Its JSON response exposes `.result.tab.tab_id` and `.result.root_pane.pane_id`. Closing a workspace's last tab also closes the workspace, matching the TUI close-tab action. If `confirm_close` is enabled and closing the tab would also close a whole worktree group, `tab close` returns a `confirmation_required` error instead.
Workspace and tab creation, and pane splitting, leave focus unchanged by default. `--focus` selects the new layout; `--no-focus` states the default explicitly. Without `--cwd`, new terminals follow the configured `terminal.new_cwd` policy, which follows the source pane or workspace by default. Each `--env KEY=VALUE` adds or replaces that variable in the new root shell.
@@ -255,7 +255,7 @@ herdr pane release-agent <pane_id> \
`pane get`, `pane list`, `agent get`, and `agent list` include a read-only `agent_session` object when an official integration has reported a native session reference. If no native session reference is stored, the field is omitted.
-Those commands include `foreground_cwd` when Herdr can resolve the cwd of the foreground process controlling the pane. The existing `cwd` field remains the pane/workspace cwd used for labels and follow-cwd behavior.
+Those commands include `foreground_cwd` when Herdr can resolve the cwd of the foreground process controlling the pane. The `cwd` field remains the pane/workspace cwd used for labels and follow-cwd behavior.
`pane get` and `pane list` include `scroll` when terminal scroll metrics are available. `scroll.offset_from_bottom == 0` means the pane is at the bottom of its scrollback.
@@ -418,7 +418,7 @@ herdr plugin link <path> [--disabled]
herdr plugin unlink <plugin_id>
```
-`plugin link` accepts a plugin directory containing `herdr-plugin.toml` or a direct manifest path. It is still the right command while authoring or testing a plugin from a local checkout. `plugin unlink` unregisters the plugin and leaves files alone. `plugin uninstall` unregisters a plugin and also removes Herdr-managed GitHub checkout files. For GitHub installs, uninstall accepts either the plugin id or the same `owner/repo[/subdir...]` shorthand used by install. Actions, event hooks, panes, and link handlers are declared in the manifest; runtime action registration is not part of v1.
+`plugin link` accepts a plugin directory containing `herdr-plugin.toml` or a direct manifest path. Use it while authoring or testing a plugin from a local checkout. `plugin unlink` unregisters the plugin and leaves files alone. `plugin uninstall` unregisters a plugin and also removes Herdr-managed GitHub checkout files. For GitHub installs, uninstall accepts either the plugin id or the same `owner/repo[/subdir...]` shorthand used by install. Actions, event hooks, panes, and link handlers are declared in the manifest; runtime action registration is not part of v1.
Config directory:
@@ -426,7 +426,7 @@ Config directory:
herdr plugin config-dir <plugin_id>
```
-`plugin config-dir` prints the plugin's config directory, creating it (and seeding it from legacy plugin config locations when present) if needed. Use it in setup docs and shell scripts to point users at a stable path for `.env` files and other user-editable config, separate from the managed plugin checkout.
+`plugin config-dir` prints the plugin's config directory. It creates the directory if needed and seeds it from legacy plugin config locations when present. Use it in setup docs and shell scripts to point users at a stable path for `.env` files and other user-editable config, separate from the managed plugin checkout.
Actions:
@@ -464,7 +464,7 @@ layout. `--width` and `--height` set the outer popup dimensions in terminal
cells or percentages such as `80%`; omitted dimensions default to half the
terminal size, and values smaller than the popup minimum are clamped. A popup
is not a Herdr pane, does not export `HERDR_PANE_ID`, and does not participate
-in pane or agent APIs. Native non-terminal plugin panes are a later surface.
+in pane or agent APIs. Native non-terminal plugin panes are outside plugin v1.
`--env KEY=VALUE` can be repeated on process-launching commands. It applies to the newly launched process only. Herdr-managed variables such as `HERDR_SOCKET_PATH`, `HERDR_BIN_PATH`, `HERDR_ENV`, `HERDR_WORKSPACE_ID`, `HERDR_TAB_ID`, `HERDR_PANE_ID`, `HERDR_PLUGIN_ID`, `HERDR_PLUGIN_ROOT`, `HERDR_PLUGIN_CONFIG_DIR`, `HERDR_PLUGIN_STATE_DIR`, `HERDR_PLUGIN_ENTRYPOINT_ID`, and `HERDR_PLUGIN_CONTEXT_JSON` stay authoritative when they conflict with caller-provided env.
diff --git a/docs/next/website/src/content/docs/concepts.mdx b/docs/next/website/src/content/docs/concepts.mdx
index 2ac32cc9..733da1bb 100644
--- a/docs/next/website/src/content/docs/concepts.mdx
+++ b/docs/next/website/src/content/docs/concepts.mdx
@@ -82,4 +82,4 @@ Herdr has terminal mode, prefix mode, and navigate mode.
Terminal mode sends keys to the focused pane. Prefix mode waits for one Herdr action after the prefix key. Navigate mode is the persistent workspace navigation surface.
-Press the prefix key, default `ctrl+b`, then an action key such as `c` for a new tab or `w` for workspace navigation. New to the prefix idea? See [Keyboard](/docs/keyboard/).
+Press the prefix key, default `ctrl+b`, then an action key such as `c` for a new tab or `w` for workspace navigation. See [Keyboard](/docs/keyboard/) if the prefix idea is new to you.
diff --git a/docs/next/website/src/content/docs/config-reference.mdx b/docs/next/website/src/content/docs/config-reference.mdx
index 499ee390..8ea9ec79 100644
--- a/docs/next/website/src/content/docs/config-reference.mdx
+++ b/docs/next/website/src/content/docs/config-reference.mdx
@@ -5,7 +5,7 @@ description: Every canonical config.toml key, with types, defaults, and allowed
import ConfigReference from '../../components/ConfigReference.astro';
-Every canonical key Herdr reads from `config.toml`, flat and filterable. For guided setup
+Browse every canonical key Herdr reads from `config.toml` in a flat, filterable list. For setup guidance
and the reasoning behind these options, see [Configuration](/docs/configuration/).
Print the full commented default config at any time:
diff --git a/docs/next/website/src/content/docs/configuration.mdx b/docs/next/website/src/content/docs/configuration.mdx
index 90614c53..5f516c4e 100644
--- a/docs/next/website/src/content/docs/configuration.mdx
+++ b/docs/next/website/src/content/docs/configuration.mdx
@@ -5,7 +5,7 @@ description: Configure Herdr keybindings, themes, sidebar behavior, notification
Herdr works without a config file. Add one when you want custom keys, themes, sidebar layouts, notifications, or advanced behavior.
-Looking for any setting or keybinding? Search the [Config reference](/docs/config-reference/) for every key, type, default, and allowed value. This page focuses on setup, common recipes, and configuration structures that need more explanation than a reference row.
+The [Config reference](/docs/config-reference/) lists every setting and keybinding, with types, defaults, and allowed values. This page covers setup, common recipes, and configuration structures that need more explanation than a reference row.
## Config file
@@ -32,7 +32,7 @@ herdr --default-config > ~/.config/herdr/config.toml
If a config value is invalid, Herdr falls back to a safe default and shows a startup warning.
-Herdr shows first-run setup when `onboarding` is missing or true. Continuing from onboarding writes `onboarding = false` and opens settings on the integrations tab. Set it when you want to skip that flow after setup.
+Herdr shows first-run setup when `onboarding` is missing or true. Continuing from onboarding writes `onboarding = false` and opens settings on the integrations tab. Set `onboarding = false` to skip that flow after setup.
```toml
onboarding = false
@@ -68,7 +68,7 @@ Set how Herdr starts newly created interactive pane shells:
shell_mode = "auto"
```
-`shell_mode = "auto"` starts login shells on macOS so login-only PATH setup such as `/usr/libexec/path_helper` and Homebrew shell initialization runs in new panes. On other platforms, it keeps the existing non-login shell behavior. Use `"login"` to force login-shell startup, or `"non_login"` to opt out. Command panes, detached custom command keybindings, and explicit argv launches keep their existing command execution paths.
+`shell_mode = "auto"` starts login shells on macOS so login-only PATH setup such as `/usr/libexec/path_helper` and Homebrew shell initialization runs in new panes. On other platforms, it keeps the existing non-login shell behavior. Use `"login"` to force login-shell startup or `"non_login"` to force non-login startup. Command panes, detached custom command keybindings, and explicit argv launches keep their existing command execution paths.
Set the working directory policy for new panes, tabs, and workspaces:
@@ -90,11 +90,11 @@ directory = "~/.herdr/worktrees"
Herdr creates checkouts under `<directory>/<repo>/<branch-slug>`. For sibling-style checkouts, set this to a directory such as `~/Projects/herdr-worktrees`. Relative values are resolved to an absolute path when the app applies the config.
-Worktree actions are available from Git workspace rows. `New worktree` creates a checkout, checks out an existing local branch when the entered branch already exists, otherwise creates the branch, opens it as a new Herdr workspace, and groups it under the source workspace. `Open worktree...` lists existing Git worktree checkouts for that repo; choosing an already-open checkout focuses it, and choosing a closed checkout opens it in the same group.
+Worktree actions are available from Git workspace rows. `New worktree` creates a checkout. It checks out an existing local branch when the entered branch exists; otherwise, it creates the branch. It then opens the checkout as a new Herdr workspace and groups it under the source workspace. `Open worktree...` lists existing Git worktree checkouts for that repo. Choosing an already-open checkout focuses it, while choosing a closed checkout opens it in the same group.
Grouped worktrees still behave like normal Herdr workspaces: they can be focused, renamed, closed, and contain their own tabs and panes. The parent row is the original workspace. Closing the parent row closes the whole Herdr group, but it does not delete checkout folders or branches.
-Deleting a worktree checkout is explicit. Use `Delete worktree checkout...` on a grouped child workspace to run `git worktree remove`. Herdr first asks Git to remove safely. If Git refuses because the checkout has modified or untracked files, Herdr asks again before running the forced remove. Branches are not deleted.
+To delete a worktree checkout, use `Delete worktree checkout...` on a grouped child workspace. Herdr runs `git worktree remove`, first asking Git to remove safely. If Git refuses because the checkout has modified or untracked files, Herdr asks again before running the forced remove. Branches are not deleted.
## Remote attach
@@ -217,7 +217,7 @@ command = "example.layout.apply"
description = "apply layout"
```
-An optional `description` can be provided. When specified, this description is displayed in the keybind help panel (opened with `prefix+?`) in place of the default `'custom command'` label.
+`description` is optional. When set, it appears in the keybind help panel (opened with `prefix+?`) instead of the default `'custom command'` label.
Custom commands receive `HERDR_SOCKET_PATH`, `HERDR_BIN_PATH`, `HERDR_ACTIVE_WORKSPACE_ID`, `HERDR_ACTIVE_TAB_ID`, `HERDR_ACTIVE_PANE_ID`, and `HERDR_ACTIVE_PANE_CWD` when those values are available. Shell commands run from the focused pane's working directory when Herdr can detect it.
@@ -407,7 +407,7 @@ herdr pane report-metadata <pane_id> \
--token summary="reviewing authentication"
```
-Use `herdr workspace report-metadata` in the same way for custom Space tokens. Unreported custom tokens simply disappear.
+Use `herdr workspace report-metadata` in the same way for custom Space tokens. Unreported custom tokens disappear.
Metadata reporters provide values only; styling stays in the local sidebar configuration. See [CLI reference: report metadata](/docs/cli-reference/#panes) for limits, clearing, sequencing, and expiry.
@@ -426,13 +426,13 @@ delay_seconds = 1
position = "bottom-right"
```
-Choose `herdr` for an in-app toast, `terminal` for an outer-terminal notification that works well over SSH, `system` for the local OS notification service, or `off` to disable popups. Herdr suppresses popups for the active tab. Search `ui.toast` in the [Config reference](/docs/config-reference/) for positions, delay behavior, and clipboard feedback settings.
+Choose `herdr` for an in-app toast, `terminal` for an outer-terminal notification that also works over SSH, `system` for the local OS notification service, or `off` to disable popups. Herdr suppresses popups for the active tab. Search `ui.toast` in the [Config reference](/docs/config-reference/) for positions, delay behavior, and clipboard feedback settings.
On macOS, `system` tries `terminal-notifier` first and falls back to `/usr/bin/osascript` when it is unavailable or fails. The fallback appears as Script Editor in Notification Center and cannot activate the hosting terminal. Install `terminal-notifier` with `brew install terminal-notifier`. For a supported, detected terminal, it can activate the terminal app when you click the notification. Alternatively, choose `terminal` to let a supported outer terminal own the notification.
## Sound
-Sound notifications play through the local Herdr client. Custom sounds must be mp3 files; relative paths are resolved from the config file's directory.
+Sound notifications play through the local Herdr client. Custom sounds must be mp3 files; Herdr resolves relative paths from the config file's directory.
```toml
[ui.sound]
diff --git a/docs/next/website/src/content/docs/how-to-work.mdx b/docs/next/website/src/content/docs/how-to-work.mdx
index 812aae9f..8d3ad081 100644
--- a/docs/next/website/src/content/docs/how-to-work.mdx
+++ b/docs/next/website/src/content/docs/how-to-work.mdx
@@ -42,11 +42,11 @@ herdr
This works like a terminal multiplexer. Your shell is remote. The Herdr server is remote. The agents and panes run on the remote machine. Detach with `ctrl+b q`, disconnect, then SSH back and run `herdr` again.
-Use this path when you already live inside an SSH shell, when you are on a phone or tablet SSH client, or when you want the simplest possible setup.
+Use this path when you already live inside an SSH shell, when you are on a phone or tablet SSH client, or when you want the simplest setup.
## Work from your phone
-You do not need a Herdr mobile app or a web dashboard. Install any SSH client on your phone, connect to the machine where your agents run, and start Herdr there:
+Herdr works on your phone without a mobile app or web dashboard. Install any SSH client, connect to the machine where your agents run, and start Herdr there:
```bash
ssh you@server
diff --git a/docs/next/website/src/content/docs/index.mdx b/docs/next/website/src/content/docs/index.mdx
index 1502462d..429018f7 100644
--- a/docs/next/website/src/content/docs/index.mdx
+++ b/docs/next/website/src/content/docs/index.mdx
@@ -33,13 +33,13 @@ import { Card, CardGrid } from '@astrojs/starlight/components';
## Or let your agent introduce you
-Already running an AI coding agent? Let it do the onboarding. Paste this prompt:
+If you already run an AI coding agent, let it handle the onboarding. Paste this prompt:
```text
Help me understand and set up Herdr. Read https://herdr.dev/agent-guide.md first, then walk me through it step by step.
```
-The guide teaches your agent Herdr's concepts, setup, configuration, and common fixes, so its answers stay accurate instead of improvised.
+The guide covers Herdr's concepts, setup, configuration, and common fixes, so your agent can answer from the docs instead of improvising.
## Core guides
diff --git a/docs/next/website/src/content/docs/install.mdx b/docs/next/website/src/content/docs/install.mdx
index 54e5a694..e5a786c3 100644
--- a/docs/next/website/src/content/docs/install.mdx
+++ b/docs/next/website/src/content/docs/install.mdx
@@ -19,7 +19,7 @@ On Windows preview beta, install the preview channel:
powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"
```
-The installer downloads the right release binary for your platform and places it on your PATH. Herdr defaults to preview on Windows without changing your config. The installer uses versioned install folders and updates a `current` junction, so updates do not need to overwrite a running `herdr.exe`.
+The installer downloads the release binary for your platform and installs it in a directory on your PATH. Herdr defaults to preview on Windows without changing your config. The installer uses versioned install folders and updates a `current` junction, so updates do not need to overwrite a running `herdr.exe`.
## Install with Homebrew
@@ -57,7 +57,7 @@ The flake also exposes a development shell:
nix develop github:herdrdev/herdr
```
-Update through the same Nix workflow you used to install Herdr. For a profile install, list your profile entries and upgrade the Herdr entry:
+Use the same Nix workflow to update Herdr. For a profile install, list your profile entries and upgrade the Herdr entry:
```bash
nix profile list
@@ -118,7 +118,7 @@ Herdr checks for new releases and notifies you in the app. You can update manual
herdr update
```
-`herdr update` is for installs managed by Herdr's own installer. Homebrew, mise, and Nix installs are updated through those package managers instead.
+Use `herdr update` only for installs managed by Herdr's own installer. Update Homebrew, mise, and Nix installs through those package managers instead.
On Linux and macOS, Herdr uses the stable update channel by default. To opt into preview builds from `master`, set the channel:
@@ -132,13 +132,13 @@ Switch Linux and macOS direct installs back to stable the same way:
herdr channel set stable
```
-For direct installs, changing channels also checks that channel and installs its latest binary. If that update fails, run `herdr update` to retry from the configured channel.
+For direct installs, changing channels checks the selected channel and installs its latest binary. If that update fails, run `herdr update` to retry from the configured channel.
Preview builds are manually published GitHub prereleases from the current development branch. They are useful when you want fixes before the next stable release, but they can regress. Homebrew, mise, and Nix installs do not use the preview channel.
Windows beta builds are preview-only for now. `herdr channel set stable` is rejected on Windows until stable Windows releases are available.
-By default, `herdr update` installs the new binary and leaves compatible running sessions alone. If an update changes Herdr's client/server protocol, Herdr asks whether to stop the old server after installing. Stop the old server to use the new version. Stopping exits pane processes. For the default session, run `herdr server stop`, then run `herdr` again. For a named session, run `herdr session stop <name>`, then run `herdr session attach <name>` again.
+By default, `herdr update` installs the new binary and leaves compatible running sessions alone. If an update changes Herdr's client/server protocol, Herdr asks whether to stop the old server after installing. Stop the old server to use the new version. Stopping the server exits its pane processes. For the default session, run `herdr server stop`, then run `herdr` again. For a named session, run `herdr session stop <name>`, then run `herdr session attach <name>` again.
To opt into experimental live server handoff for supported running sessions, run:
diff --git a/docs/next/website/src/content/docs/integrations.mdx b/docs/next/website/src/content/docs/integrations.mdx
index 2cdc0d62..67ea8c3e 100644
--- a/docs/next/website/src/content/docs/integrations.mdx
+++ b/docs/next/website/src/content/docs/integrations.mdx
@@ -3,9 +3,7 @@ title: Integrations
description: Install Herdr integrations for Pi, OMP, Claude Code, Codex, GitHub Copilot CLI, Devin CLI, Droid, Kimi Code CLI, OpenCode, Kilo Code CLI, Hermes Agent, Qoder CLI, Cursor Agent CLI, MastraCode, Antigravity CLI, and Grok CLI.
---
-Herdr detects supported agents automatically. Official integrations can add native session identity for restore, lifecycle state reports, or both.
-
-Use integrations when you want native agent session restore, direct lifecycle reports, or both. See [Agents](/docs/agents/) for the full status authority model.
+Herdr detects supported agents automatically. Install official integrations when you want native agent session restore, direct lifecycle reports, or both. See [Agents](/docs/agents/) for the full status authority model.
## Install integrations
@@ -53,14 +51,14 @@ herdr integration uninstall grok
## How Herdr uses integrations
-Herdr uses integrations in two different ways:
+Herdr uses integrations in two ways:
| Integration type | Agents | Effect |
| --- | --- | --- |
| Lifecycle authority | Pi, OMP, Kimi Code CLI, OpenCode, Kilo Code CLI, MastraCode | When installed and actively reporting for the pane, hook or plugin events author `idle`, `working`, and `blocked`. Herdr does not also use screen manifest fallback for that same lifecycle authority. |
| Session identity | Claude Code, Codex, GitHub Copilot CLI, Devin CLI, Droid, Qoder CLI, Cursor Agent CLI, Hermes Agent, Antigravity CLI, Grok CLI | The integration reports native session references for restore. State still comes from Herdr's screen manifest detection. |
-Custom integrations can also report state when they define state that is not visible in the native terminal UI. They do not need to be built into Herdr or use a recognized agent executable.
+Custom integrations can also report state that is not visible in the native terminal UI. They do not need to be built into Herdr or use a recognized agent executable.
## Integrate your own agent
@@ -81,9 +79,9 @@ Report `idle` when the agent is ready for input and `blocked` when it needs a us
--agent my-agent
```
-Only report when `HERDR_ENV=1` and the required variables are present so the integration remains a no-op outside Herdr. Keep `--source` stable and unique to the integration. If reports can arrive out of order, include a strictly increasing `--seq`; Herdr ignores stale sequence numbers from the same source.
+Report only when `HERDR_ENV=1` and the required variables are present. This keeps the integration a no-op outside Herdr. Keep `--source` stable and unique to the integration. If reports can arrive out of order, include a strictly increasing `--seq`; Herdr ignores stale sequence numbers from the same source.
-You can include `--agent-session-id` or `--agent-session-path` with `report-agent`, or use `pane report-agent-session` when session identity changes independently of state. Herdr exposes that reference through its pane and agent APIs. Automatic session restore additionally requires Herdr to know how to launch that agent and resume the referenced session.
+You can include `--agent-session-id` or `--agent-session-path` with `report-agent`, or use `pane report-agent-session` when session identity changes independently of state. Herdr exposes that reference through its pane and agent APIs. Automatic session restore also requires Herdr to know how to launch that agent and resume the referenced session.
Use `HERDR_BIN_PATH` and the CLI wrappers for portable integrations. Code that needs direct IPC can send the equivalent `pane.report_agent`, `pane.report_agent_session`, and `pane.release_agent` requests described in the [Socket API](/docs/socket-api/#agent-state-reporting).
@@ -297,7 +295,7 @@ herdr integration install antigravity-cli
Herdr uses `~/.gemini/config/` by default, or `ANTIGRAVITY_CLI_CONFIG_DIR` when set. This is the directory Antigravity CLI reads global customizations from, and it must already exist. Install writes `hooks/herdr-agent-state.sh` (or `herdr-agent-state.ps1` on Windows) and adds a Herdr-owned `herdr` block to `hooks.json`. Antigravity CLI keys `hooks.json` by hook name, so install rewrites only that block and leaves other named hooks untouched. Uninstall removes the `herdr` block and deletes the hook script.
-This integration is session-only. It reports the conversation the pane is running and does not report agent state, so Herdr keeps deriving working, idle, and blocked from what Antigravity CLI draws on screen.
+This session-only integration reports the pane's current conversation, but not agent state. Herdr keeps deriving working, idle, and blocked from what Antigravity CLI draws on screen.
The hook runs on `PreInvocation`, so Herdr learns the conversation once the first prompt is sent. From then on Herdr can resume the pane with `agy --conversation <id>` after a Herdr server restart.
diff --git a/docs/next/website/src/content/docs/keyboard.mdx b/docs/next/website/src/content/docs/keyboard.mdx
index d159b2c8..84f78013 100644
--- a/docs/next/website/src/content/docs/keyboard.mdx
+++ b/docs/next/website/src/content/docs/keyboard.mdx
@@ -7,13 +7,13 @@ description: What the prefix is, which bindings to learn first, and how to go pr
You already know this model. Jump to the [keybinding reference](/docs/configuration/#keybindings) for the full default keymap and config syntax.
:::
-Herdr is mouse-native. You can click panes, tabs, workspaces, and agents, drag split borders, and use right-click menus without learning a single keybinding. Keyboard control is an optional layer, not a requirement.
+Herdr is mouse-native. You can click panes, tabs, workspaces, and agents, drag split borders, and use right-click menus without learning a single keybinding. Keyboard control is optional.
## What the prefix is
A terminal multiplexer sits between your terminal and the programs running inside it. Those programs already use most key combinations: `ctrl+c` interrupts, `ctrl+r` searches history, editors claim nearly everything else. If Herdr grabbed common keys directly, it would break the programs inside it.
-The prefix solves this. Press the prefix key, default `ctrl+b`, and the next keypress goes to Herdr instead of your terminal. `prefix+c` means: press `ctrl+b`, release, then press `c`. One reserved key instead of dozens.
+The prefix solves this. Press the prefix key, default `ctrl+b`, and the next keypress goes to Herdr instead of your terminal. `prefix+c` means: press `ctrl+b`, release, then press `c`. Herdr reserves one key instead of dozens.
Press `prefix+?` at any time to see every active binding. Press `/` in the keybind help to filter actions and shortcuts; use Backspace to edit the filter or `ctrl+u` to clear it.
@@ -81,7 +81,7 @@ You can bind Herdr actions to direct chords that need no prefix at all. The hard
Any chord works as a binding: `ctrl+j`, `alt+k`, whatever fits your hands. But a chord has to survive three layers before Herdr sees it: your operating system, your outer terminal (Ghostty, iTerm2, and others ship their own defaults), and the programs running inside the pane. `ctrl+j` reaches Herdr fine, but shells and editors treat it as enter. `alt+k` is free on Linux, but macOS composes it into a special character in most terminals. If you pick chords from these families, double-check them against your own terminal and OS shortcuts.
-We mapped the default keybindings of Ghostty, iTerm2, Terminal.app, kitty, WezTerm, Alacritty, Warp, Windows Terminal, GNOME Terminal, and Konsole, plus the global shortcuts of GNOME and KDE. One modifier family is almost untouched everywhere: `ctrl+alt`. Terminals leave it free, it is not affected by the macOS option-key composing behavior that blocks plain `alt` chords, and it transmits even in terminals without a modern keyboard protocol. It is the safe default recommendation; the choice stays yours.
+We mapped the default keybindings of Ghostty, iTerm2, Terminal.app, kitty, WezTerm, Alacritty, Warp, Windows Terminal, GNOME Terminal, and Konsole, plus the global shortcuts of GNOME and KDE. One modifier family is almost untouched everywhere: `ctrl+alt`. Terminals leave it free, it is not affected by the macOS option-key composing behavior that blocks plain `alt` chords, and it transmits even in terminals without a modern keyboard protocol. It is a safe default, but the choice is yours.
This setup keeps the prefix bindings working and adds direct chords on top:
diff --git a/docs/next/website/src/content/docs/marketplace.mdx b/docs/next/website/src/content/docs/marketplace.mdx
index 88bbaf98..4c12bdbe 100644
--- a/docs/next/website/src/content/docs/marketplace.mdx
+++ b/docs/next/website/src/content/docs/marketplace.mdx
@@ -3,9 +3,9 @@ title: Marketplace
description: Discover community Herdr plugins on GitHub, and get your own plugin listed.
---
-The Herdr plugin marketplace is a discoverable index of community plugins.
-Browse it at [herdr.dev/plugins](/plugins/). It is an automatic index of public
-GitHub repositories, not a reviewed catalog.
+The Herdr plugin marketplace indexes community plugins. Browse it at
+[herdr.dev/plugins](/plugins/). The index covers public GitHub repositories; it
+is not a reviewed catalog.
## Browse plugins
@@ -23,15 +23,15 @@ anything.
## Install a plugin
-The marketplace adds discovery on top of installation; it does not replace it.
-Install any plugin straight from GitHub:
+The marketplace helps you discover plugins. Install any plugin straight from
+GitHub:
```bash
herdr plugin install owner/repo[/subdir...]
```
-Publish a normal public GitHub repository with a `herdr-plugin.toml` manifest at
-its root, or in a subdirectory, and that command works. See
+The command works with a public GitHub repository that has a
+`herdr-plugin.toml` manifest at its root or in a subdirectory. See
[Plugins](/docs/plugins/) for the manifest and authoring reference.
## Get your plugin listed
diff --git a/docs/next/website/src/content/docs/persistence-remote.mdx b/docs/next/website/src/content/docs/persistence-remote.mdx
index befbfb25..1847a0a5 100644
--- a/docs/next/website/src/content/docs/persistence-remote.mdx
+++ b/docs/next/website/src/content/docs/persistence-remote.mdx
@@ -37,14 +37,14 @@ herdr session delete side-project --json
## Remote attach over SSH
-There are two remote modes; [How to work with Herdr](/docs/how-to-work/) compares them. SSH to the server and run `herdr` there for the tmux-style path. Or attach through SSH from your local machine:
+Herdr supports two remote modes. [How to work with Herdr](/docs/how-to-work/) compares them. SSH to the server and run `herdr` there for the tmux-style path, or attach through SSH from your local machine:
```bash
herdr --remote workbox
herdr --remote ssh://you@server:2222
```
-In this mode your local Herdr is a thin client. It connects over SSH, starts or attaches to the remote Herdr server, and streams the UI back to your local terminal. Because the client runs locally, Herdr can bridge local desktop features such as image clipboard paste into the remote session by copying the image to a remote temp file and pasting that path.
+In this mode, your local Herdr is a thin client. It connects over SSH, starts or attaches to the remote Herdr server, and streams the UI back to your local terminal. Because the client runs locally, Herdr can bridge local desktop features such as image clipboard paste into the remote session by copying the image to a remote temp file and pasting that path.
By default, `herdr --remote` uses your local Herdr keybindings for that attach. This keeps local muscle memory even when the remote server has different config. The local keybindings are a snapshot from attach time; detach and reattach after editing local keybindings. Use `--remote-keybindings server` when you want the remote server config instead. Local custom command keybindings are not sent, because those commands would run on the remote host.
@@ -82,7 +82,7 @@ By default, remote attach uses the normal restart/stop flow if it needs to repla
herdr --remote workbox --handoff
```
-If you SSH into the server first and run `herdr` there, Herdr runs entirely on the server. That mode is useful and simple, but it cannot access your local desktop clipboard beyond normal terminal text paste.
+If you SSH into the server first and run `herdr` there, Herdr runs entirely on the server and cannot access your local desktop clipboard beyond normal terminal text paste.
When your local and remote platforms match, Herdr can copy the current local binary for direct installs. For Homebrew, mise, and Nix installs, or when the platforms differ, it downloads the matching release asset for the current client version from `https://herdr.dev/latest.json`.
@@ -160,4 +160,4 @@ Use `--no-session` to run Herdr without the background server/client split:
herdr --no-session
```
-This is mainly an escape hatch for debugging or compatibility. The default persistent session mode is the normal path.
+Use `--no-session` mainly for debugging or compatibility. Persistent session mode remains the default.
diff --git a/docs/next/website/src/content/docs/plugins.mdx b/docs/next/website/src/content/docs/plugins.mdx
index 418d5af6..4085e242 100644
--- a/docs/next/website/src/content/docs/plugins.mdx
+++ b/docs/next/website/src/content/docs/plugins.mdx
@@ -15,19 +15,18 @@ workspaces, panes, agents, and a stable CLI/socket API. Plugins turn that
existing extension surface into reusable workflows that people can build,
install, and share without adding every workflow to Herdr itself.
-A plugin is not an SDK integration. It is a directory with a
-`herdr-plugin.toml` manifest and commands Herdr can launch. Herdr validates the
-manifest, injects runtime context, starts the declared commands, and records
-logs. The commands call back into Herdr through the CLI or socket when they need
-to do more work.
+A plugin is a directory with a `herdr-plugin.toml` manifest and commands Herdr
+can launch. Herdr validates the manifest, injects runtime context, starts the
+declared commands, and records logs. The commands call back into Herdr through
+the CLI or socket when they need to do more work.
There is no separate plugin SDK or restricted command set. The entire Herdr CLI
-is the plugin API: every command in the [CLI reference](/docs/cli-reference/) is
-available to a plugin, and anything you can run as `herdr ...` yourself a plugin
-can run too. Most plugins should call Herdr through `HERDR_BIN_PATH`, which
-points at the running Herdr binary. That keeps plugins portable across Unix
-sockets and Windows named pipes. Use the [socket API](/docs/socket-api/) when
-you want to send raw JSON requests yourself.
+is the plugin API. Every command in the
+[CLI reference](/docs/cli-reference/) is available to a plugin, and a plugin can
+run anything you can run yourself as `herdr ...`. Most plugins should call Herdr
+through `HERDR_BIN_PATH`, which points at the running Herdr binary. That keeps
+plugins portable across Unix sockets and Windows named pipes. Use the
+[socket API](/docs/socket-api/) when you want to send raw JSON requests yourself.
Runtime action registration and native non-terminal plugin UI are not part of
plugin v1. Actions, event hooks, panes, and link handlers are all declared in
@@ -35,22 +34,22 @@ the manifest.
## Trust and security
-A plugin is ordinary code that runs on your machine. When you install or link
-one, its build and runtime commands run as your user, with your environment, and
-can call the full Herdr CLI — the same as any extension you add to an editor,
-shell, or coding agent. That openness is the point, and a little judgment keeps
-it safe.
+A plugin is ordinary code that runs on your machine. Its build and runtime
+commands run as your user, inherit your environment, and can call the full Herdr
+CLI. Treat a plugin like any extension you add to an editor, shell, or coding
+agent.
-Install plugins from authors and repositories you trust, and skim what a new one
-does first: the `herdr-plugin.toml` manifest and the scripts or binaries it runs.
-`herdr plugin install` shows a preview of the source and the commands it will run
-in interactive terminals, so you can review before confirming. Use `--yes` for
+Install or link plugins only from authors and repositories you trust. Before
+installing or linking one, skim the `herdr-plugin.toml` manifest and the scripts
+or binaries it runs. `herdr plugin install` shows a preview of the source and
+the commands it will run in interactive terminals, so you can review before
+confirming. Use `--yes` for
sources you already trust, and pin `--ref` when you want a specific revision.
Herdr validates the manifest and keeps each plugin's config and state in its own
-directory, but it does not review or sandbox what a plugin does. Third-party
-plugins come from their authors, not from Herdr, so they are yours to vet and run
-at your own discretion.
+directory, but it does not review or sandbox plugin code. Third-party plugins
+come from their authors, not Herdr; you are responsible for deciding whether to
+run them.
## Manifest
@@ -213,8 +212,8 @@ reinstall from GitHub to refresh a managed plugin.
The example cookbook repo is `ogulcancelik/herdr-plugin-examples`. It contains
separate example plugins in subdirectories, including `agent-telegram-notify`,
-`github-link-preview`, and `dev-layout-bootstrap`. These are examples to copy,
-not maintained official plugins.
+`github-link-preview`, and `dev-layout-bootstrap`. Use them as examples to copy;
+Herdr does not maintain them as official plugins.
## Build commands
@@ -240,9 +239,9 @@ is linked or enabled. Herdr starts them asynchronously and records their
completion in the normal plugin command log. A startup failure does not stop the
server.
-Startup hooks are one-shot initialization commands, not supervised daemons. A
-hook should restore plugin-owned state, call any required Herdr APIs, and exit.
-For example, a plugin can save a declarative Agent view under
+Startup hooks are one-shot initialization commands rather than supervised
+daemons. A hook should restore plugin-owned state, call any required Herdr APIs,
+and exit. For example, a plugin can save a declarative Agent view under
`HERDR_PLUGIN_STATE_DIR`, then read and reapply that view from its startup hook.
Startup hooks receive the normal runtime plugin environment and
diff --git a/docs/next/website/src/content/docs/quick-start.mdx b/docs/next/website/src/content/docs/quick-start.mdx
index 86d8bc8e..5ac2d56d 100644
--- a/docs/next/website/src/content/docs/quick-start.mdx
+++ b/docs/next/website/src/content/docs/quick-start.mdx
@@ -13,11 +13,11 @@ Herdr launches or attaches to your default background session. You do not manage
## Create a workspace
-When a session has no workspaces, Herdr opens one automatically. A workspace is a project-level container for tabs, panes, and agents. Give each active project its own workspace; this keeps agent state readable in the sidebar.
+When a session has no workspaces, Herdr opens one automatically. A workspace is a project-level container for tabs, panes, and agents. Give each active project its own workspace to keep agent state readable in the sidebar.
## Use the mouse
-Herdr is mouse-native, so start by clicking. Click panes, tabs, workspaces, and agents to focus them. Drag split borders to resize. Right-click for context menus, including splitting panes and creating tabs. Drag-select text to copy it to your clipboard; double-click a token to copy it directly. Copying does not require Ctrl+C.
+Herdr is mouse-native, so start by clicking panes, tabs, workspaces, and agents to focus them. Drag split borders to resize. Right-click for context menus, including splitting panes and creating tabs. Drag-select text to copy it to your clipboard; double-click a token to copy it directly. Copying does not require Ctrl+C.
Ctrl-click opens pane links when your terminal sends the modified click to Herdr. This works for OSC 8 hyperlinks and visible `http://` or `https://` URLs. On macOS, use Ctrl-click for Herdr-handled pane links while mouse capture is enabled; Cmd-click is only available through the terminal-native bypass path, such as Shift-Cmd-click or `ui.mouse_capture = false`.
@@ -31,7 +31,7 @@ Start your coding agent in a pane:
claude
```
-Or `codex`, `pi`, `opencode`, or any other [supported agent](/docs/agents/). Herdr detects it automatically. The sidebar shows whether each agent is `working`, `blocked`, `done`, or `idle` — across every workspace, so you always know which project needs you.
+Or `codex`, `pi`, `opencode`, or any other [supported agent](/docs/agents/). Herdr detects it automatically. Across every workspace, the sidebar shows whether each agent is `working`, `blocked`, `done`, or `idle`, so you always know which project needs you.
## Keyboard control
@@ -49,13 +49,13 @@ Common actions:
| New workspace | `prefix+shift+n` |
| Detach client | `prefix+q` |
-New to the prefix idea? [Keyboard](/docs/keyboard/) explains what it is, why multiplexers use one, and how to go prefix-free. Press `prefix+?` inside Herdr to see every active binding, and `prefix+[` to copy from the keyboard in copy mode.
+If the prefix idea is new to you, [Keyboard](/docs/keyboard/) explains what it is, why multiplexers use one, and how to go prefix-free. Press `prefix+?` inside Herdr to see every active binding, and `prefix+[` to copy from the keyboard in copy mode.
## Detach and come back
Press `prefix+q` or simply close your terminal window. The Herdr server and every agent keep running. Run `herdr` again to reattach to the same session.
-To actually end the session and stop its panes:
+To end the session and stop its panes:
```bash
herdr server stop
diff --git a/docs/next/website/src/content/docs/session-state.mdx b/docs/next/website/src/content/docs/session-state.mdx
index 468557b4..548cf120 100644
--- a/docs/next/website/src/content/docs/session-state.mdx
+++ b/docs/next/website/src/content/docs/session-state.mdx
@@ -3,7 +3,7 @@ title: Session state and restore
description: Understand what Herdr keeps live, restores after restart, replays from history, resumes through agent integrations, and hands off during updates.
---
-Herdr has several state paths. They solve different problems.
+Herdr uses several state paths for different situations.
## What survives
@@ -14,8 +14,6 @@ Herdr has several state paths. They solve different problems.
| Update without `--handoff` | Compatible servers keep running; restart-required servers may need stop/restart | Yes after restart | Only with pane screen history | Only with native agent session restore |
| Update with `--handoff` | Best effort for supported running servers | Yes | Yes, from the live terminal if handoff succeeds | Yes, because the process keeps running if handoff succeeds |
-The sections below explain each path.
-
## Live persistence
Normal detach keeps the Herdr server running. Panes, shells, agents, servers, tests, and command processes keep running inside that server.
@@ -36,9 +34,9 @@ Snapshot restore does not preserve running shells, servers, tests, or arbitrary
## Pane screen history replay
-Pane screen history restores recent terminal contents after a full server restart. It restores what Herdr can show, not the old process.
+Pane screen history restores recent terminal contents after a full server restart without restoring the old process.
-This is off by default because pane output can include secrets, tokens, prompts, and command output. Enable it in the config file:
+Pane screen history is off by default because pane output can include secrets, tokens, prompts, and command output. Enable it in the config file:
```toml
[experimental]
@@ -51,7 +49,7 @@ When enabled, Herdr stores saved pane history in `session-history.json` next to
Some agents can resume their own conversation sessions. Herdr can use official integration-reported session references to restart supported agent panes after a Herdr server restart.
-This is enabled by default. Disable it with:
+Native agent session restore is enabled by default. Disable it with:
```toml
[session]
@@ -93,9 +91,9 @@ If native agent session restore applies to a pane, Herdr resumes the agent sessi
Live handoff is for update and remote attach flows that need to replace a running Herdr server. It asks the old server to transfer live panes to the new server, so pane processes can keep running across the server replacement.
-This is different from snapshot restore, pane history replay, and native agent session restore. Handoff tries to keep the current processes alive. The others reconstruct state after the old server has already stopped.
+Unlike snapshot restore, pane history replay, and native agent session restore, handoff tries to keep the current processes alive rather than reconstructing state after the old server stops.
-Handoff protects long-lived server-owned session state: pane PTYs and processes, agent identity and durable metadata, and plugin/session state needed by the replacement server. It does not preserve transient coordination across the replacement boundary. In-flight CLI or API requests, waits, subscription streams, client sockets, and pane-to-pane messages may be interrupted; clients should reconnect and retry them.
+A successful handoff preserves long-lived server-owned session state: pane PTYs and processes, agent identity and durable metadata, and plugin/session state needed by the replacement server. It does not preserve transient coordination across the replacement boundary. In-flight CLI or API requests, waits, subscription streams, client sockets, and pane-to-pane messages may be interrupted; clients should reconnect and retry them.
Live handoff is experimental and opt-in:
diff --git a/docs/next/website/src/content/docs/socket-api.mdx b/docs/next/website/src/content/docs/socket-api.mdx
index 430cf4bf..6431dcb9 100644
--- a/docs/next/website/src/content/docs/socket-api.mdx
+++ b/docs/next/website/src/content/docs/socket-api.mdx
@@ -480,10 +480,10 @@ A source mismatch leaves the active view unchanged. Set and clear responses use
## Plugin APIs
-The plugin API is an early host surface for executable workflow tools. A plugin
-is a package with a `herdr-plugin.toml` manifest. The manifest declares
-startup hooks, shareable actions, event hooks, terminal pane entrypoints, and
-link handlers. Startup hooks run once after restore when the API is ready.
+The plugin API is an early interface for executable workflow tools. A plugin is
+a package with a `herdr-plugin.toml` manifest. The manifest declares startup
+hooks, shareable actions, event hooks, terminal pane entrypoints, and link
+handlers. Startup hooks run once after restore when the API is ready.
Actions and panes are manifest-only; runtime action registration and runtime
argv pane creation are not part of v1.
@@ -492,11 +492,14 @@ Installed and linked plugins persist across restarts. Herdr writes a
`plugin.unlink`, `plugin.enable`, and `plugin.disable`. The
`herdr plugin install` and `herdr plugin link` CLIs also write the same registry
when Herdr is not running, then startup loads it automatically. On startup,
-Herdr re-reads each
-manifest from its original path; if the file is missing or unparseable the entry
-is kept with a `warnings` field so `plugin.list` surfaces it.
+Herdr re-reads each manifest from its original path; if the file is missing or
+unparseable, the entry is kept with a `warnings` field so `plugin.list` surfaces
+it.
-Event hook `on` values are validated against the known Herdr event names at link time. An unrecognised name is not an error — the link still succeeds — but the returned plugin info includes a warning (e.g. `"unknown event 'worktree.craeted'"`). Check the `warnings` field in the `plugin.link` and `plugin.list` responses.
+Herdr validates event hook `on` values against known event names at link time.
+An unrecognised name does not block the link, but the returned plugin info
+includes a warning (e.g. `"unknown event 'worktree.craeted'"`). Check the
+`warnings` field in the `plugin.link` and `plugin.list` responses.
Link a local plugin manifest:
@@ -552,7 +555,7 @@ field is missing, invalid, or newer than the running Herdr binary.
Declare `platforms` at the top level with the OS identifiers (`linux`, `macos`,
`windows`) your plugin supports. Omitting `platforms` is allowed for local
-development — `plugin.link` succeeds but the response includes a warning.
+development. `plugin.link` succeeds, but the response includes a warning.
Individual build commands, actions, event hooks, panes, and link handlers can
declare their own `platforms` to override the plugin-level list; if omitted they
inherit from the plugin. Invoking an action or opening a pane whose effective
@@ -695,7 +698,8 @@ Integrations report agent state with `pane.report_agent`.
}
```
-`state` is semantic. It affects waits, notifications, and rollups. Report display-only values separately through metadata.
+`state` carries semantic agent state and affects waits, notifications, and
+rollups. Report display-only values separately through metadata.
Session-only official integrations report native session references with `pane.report_agent_session`. State-reporting integrations can still include native session references in `pane.report_agent`. State-independent session reports do not affect waits, notifications, or rollups.
@@ -917,6 +921,7 @@ Errors look like this:
## Protocol stability
-Herdr has a protocol version for client/server compatibility. Protocol changes are reviewed with release compatibility in mind.
+Herdr has a protocol version for client/server compatibility. Protocol changes
+are reviewed for release compatibility.
Check the server protocol with `ping` or `herdr status` before depending on new behavior. Handle unknown fields gracefully.
diff --git a/docs/next/website/src/content/docs/troubleshooting.mdx b/docs/next/website/src/content/docs/troubleshooting.mdx
index ee094ae5..e908057e 100644
--- a/docs/next/website/src/content/docs/troubleshooting.mdx
+++ b/docs/next/website/src/content/docs/troubleshooting.mdx
@@ -27,9 +27,9 @@ Native mode restores the IME anchor but may reintroduce occasional cursor moveme
## Enter, Tab, or Backspace fires twice
-Older terminal versions can emit the release of Enter, Tab, and Backspace as the same bytes as the press when an application enables Kitty keyboard event reporting. Herdr cannot distinguish those duplicate bytes after the terminal sends them.
+Older versions of some terminals can emit the release of Enter, Tab, and Backspace as the same bytes as the press when an application enables Kitty keyboard event reporting. Herdr cannot distinguish those duplicate bytes after the terminal sends them.
-Update the outer terminal to a version containing its upstream fix:
+Update the outer terminal to a version that contains its upstream fix:
| Terminal | Minimum fixed version |
| --- | --- |
@@ -72,7 +72,7 @@ Stopping a server exits its pane processes. Named sessions use `herdr session st
## The `herdr` command is not found
-Restart the terminal so it reloads its environment, then confirm the Herdr install directory is on `PATH`. Package-manager installs must be updated and exposed through that package manager. See [Install Herdr](/docs/install/#verify).
+Restart the terminal so it reloads its environment, then confirm the Herdr install directory is on `PATH`. For package-manager installs, use that package manager to update Herdr and expose it on `PATH`. See [Install Herdr](/docs/install/#verify).
## A direct keybinding does nothing
diff --git a/docs/next/website/src/content/docs/windows-beta.mdx b/docs/next/website/src/content/docs/windows-beta.mdx
index b21d1efb..54c9441f 100644
--- a/docs/next/website/src/content/docs/windows-beta.mdx
+++ b/docs/next/website/src/content/docs/windows-beta.mdx
@@ -3,11 +3,11 @@ title: Windows beta
description: Native Windows support status, supported workflows, and known limitations.
---
-Native Windows support is experimental beta.
+Native Windows support is an experimental beta.
-Herdr on Windows uses ConPTY and Windows process/runtime behavior instead of the Unix PTY model Herdr was originally built around. Some Herdr features map cleanly to Windows, and some do not. This preview is not a commitment that every Linux/macOS feature will become fully supported on Windows.
+Herdr on Windows uses ConPTY and Windows process/runtime behavior instead of the Unix PTY model Herdr was built around, so feature support varies. This preview is not a commitment that every Linux/macOS feature will become fully supported on Windows.
-The goal of the beta is to learn from real use: install success, pane reliability, agent workflows, bug volume, missing features, and whether Windows users are getting enough value from Herdr. Based on that feedback, Windows support may graduate to stable, stay preview-only while it matures, or be reduced if the maintenance cost is not justified.
+The beta gathers feedback from real use: install success, pane reliability, agent workflows, bug volume, missing features, and whether Windows users get enough value from Herdr. Based on that feedback, Windows support may graduate to stable, stay preview-only while it matures, or be reduced if the maintenance cost is not justified.
Install native Windows beta builds with PowerShell:
@@ -41,7 +41,7 @@ For internal beta testing, `HERDR_MANIFEST_URL` can point the installer at a cus
Windows agent process detection scans descendants of the pane shell and recognizes direct agents plus common command wrappers. It is useful for Codex, Claude, and similar agents, but it is not the same as Unix foreground process-group detection.
-Plugins support `windows` as a manifest platform in preview. GitHub install, local link, build commands, actions, events, and plugin panes are best effort on Windows. Commands are argv commands and must be Windows-compatible; Node package shims such as `npm`, `bun`, and `node` are expected to work when they are on `PATH`, while Unix-only examples using `sh` or Bash need Windows-specific alternatives. Platform filters skip unsupported build commands and return `platform_unsupported` for unsupported actions or panes.
+Plugins support `windows` as a manifest platform in preview. GitHub install, local link, build commands, actions, events, and plugin panes are best-effort on Windows. Commands are argv commands and must be Windows-compatible; Node package shims such as `npm`, `bun`, and `node` are expected to work when they are on `PATH`, while Unix-only examples using `sh` or Bash need Windows-specific alternatives. Platform filters skip unsupported build commands and return `platform_unsupported` for unsupported actions or panes.
## Partial support
@@ -54,7 +54,7 @@ Plugins support `windows` as a manifest platform in preview. GitHub install, loc
| Kitty graphics rendering | unverified |
| Host cursor rendering | partial |
-Herdr can launch panes in the right directory and can create the initial workspace from the directory where you started Herdr. PowerShell directory changes after startup are different: the process field Herdr can inspect does not reliably track later logical `cd` changes. Use Herdr integrations or prompt shell integration for live cwd reporting.
+Herdr can launch panes in the right directory and create the initial workspace from the directory where you started Herdr. After startup, the process field Herdr can inspect does not reliably track later logical `cd` changes in PowerShell. Use Herdr integrations or prompt shell integration for live cwd reporting.
During `herdr --remote`, the configured remote image paste key reads a Windows clipboard image and transfers it to the remote host. Dropping one local image file into Windows Terminal also transfers that file and pastes its remote path. Clipboard image paste into a local native Windows pane remains unverified.
@@ -64,18 +64,18 @@ Kitty graphics remains experimental and is not claimed as Windows-supported yet.
### Cursor rendering
-Herdr relies on ConPTY for native Windows panes. The current Windows terminal cursor path can expose intermediate cursor positions while a multiplexer repaints the screen. A native cursor may flicker, jump, or briefly remain at an old position during active output. This behavior also reproduces in other native Windows terminal multiplexers and with direct VT cursor-position stress tests, so Herdr cannot eliminate it while preserving native cursor behavior.
+Herdr relies on ConPTY for native Windows panes. The Windows terminal cursor path can expose intermediate positions while a multiplexer repaints the screen. A native cursor may flicker, jump, or briefly remain at an old position during active output. This behavior also reproduces in other native Windows terminal multiplexers and with direct VT cursor-position stress tests, so Herdr cannot eliminate it while preserving native cursor behavior.
To prioritize visual stability, the default `host_cursor = "auto"` draws Herdr's cursor as terminal cell content on native Windows and WSL. Other Linux and macOS clients continue to use the native terminal cursor. The drawn Windows cursor is steady and non-blinking, but it does not provide the outer terminal's native blink, shape, or cursor color.
-A drawn cursor is not the cursor that Windows uses to position IME composition and candidate UI. Korean, Japanese, or Chinese IME UI may therefore appear at the wrong location. If this affects you, opt back into the outer terminal cursor:
+Windows does not use a drawn cursor to position IME composition and candidate UI. Korean, Japanese, or Chinese IME UI may therefore appear at the wrong location. If this affects you, opt back into the outer terminal cursor:
```toml
[ui]
host_cursor = "native"
```
-Native mode restores the IME anchor, but it can reintroduce occasional cursor flicker, jumps, or stale cursor positions during active output. This is currently a compatibility trade-off in the Windows beta.
+Native mode restores the IME anchor, but it can reintroduce occasional cursor flicker, jumps, or stale cursor positions during active output.
### Keyboard and mouse
diff --git a/website/README.md b/website/README.md
index ceb872af..8240b2f6 100644
--- a/website/README.md
+++ b/website/README.md
@@ -15,7 +15,7 @@ Documentation has three lifecycle states:
- `../docs/next/website/` is the committed, author-edited draft. Production builds never read it.
- `../docs/preview/website/` is the latest preview release snapshot, rendered at `/docs/preview/`.
-- `../docs/versions/<version>/website/` contains maintained stable-release documentation, rendered at `/docs/<version>/`. Release CI seeds a new version from its tag; later factual corrections are made directly in that version directory and mirrored to `docs/next` when they also apply to future releases.
+- `../docs/versions/<version>/website/` contains maintained stable-release documentation, rendered at `/docs/<version>/`. Release CI seeds each new version from its tag. Make later factual corrections directly in that version directory, and mirror them to `docs/next` when they also apply to future releases.
The version selected by `docs/versions/manifest.json` is also rendered at `/docs/`. `src/content/docs/` is entirely generated and ignored.
diff --git a/website/agent-guide.md b/website/agent-guide.md
index 20291d0d..7e20c751 100644
--- a/website/agent-guide.md
+++ b/website/agent-guide.md
@@ -1,8 +1,8 @@
# Herdr agent guide
-You are reading this because a human asked you to help them understand, set up, or troubleshoot Herdr. This file gives you the concept model, the setup path, and the diagnosis recipes so you can guide them accurately. Canonical documentation lives at https://herdr.dev/docs/ — link the human there for depth, and verify any command you are unsure about against those pages instead of guessing.
+Use this guide to help a human understand, set up, or troubleshoot Herdr. It covers Herdr's concept model, setup path, and diagnosis recipes. Canonical documentation lives at https://herdr.dev/docs/. Point the human there for more detail, and verify any command you are unsure about against those pages instead of guessing.
-If you are running *inside* a Herdr pane (the environment variable `HERDR_ENV=1` is set), Herdr also ships a skill file that teaches you to control Herdr yourself through the `herdr` CLI: https://raw.githubusercontent.com/herdrdev/herdr/master/skills/herdr/SKILL.md. That file is about you operating Herdr; this file is about you teaching a human.
+If you are running *inside* a Herdr pane (the environment variable `HERDR_ENV=1` is set), Herdr also ships a skill file that teaches you to control Herdr through the `herdr` CLI: https://raw.githubusercontent.com/herdrdev/herdr/master/skills/herdr/SKILL.md. That file teaches you to operate Herdr; this one teaches you to guide a human.
## What Herdr is
@@ -39,39 +39,39 @@ powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"
herdr
```
-Homebrew, mise, and Nix installs, verification, and manual downloads: https://herdr.dev/docs/install/. Updating later is `herdr update`. Check the version with `herdr --version`.
+Homebrew, mise, and Nix installs, verification, and manual downloads: https://herdr.dev/docs/install/. Direct installs update with `herdr update`; package-manager installs update through that package manager. Check the version with `herdr --version`.
## First-run walkthrough
-First check where you are. If `HERDR_ENV=1` is set in your environment, you are already running inside a Herdr pane — the human is already attached, so skip step 1 entirely and never tell them to run `herdr` from your pane. Herdr blocks nested launches by design. Start from step 2, and consider the skill file below.
+Check your environment first. If `HERDR_ENV=1` is set, you are already running inside a Herdr pane. The human is already attached, so skip step 1 and never tell them to run `herdr` from your pane; Herdr blocks nested launches by design. Start with step 2, and consider the skill file below.
Walk the human through this sequence:
1. `cd` into a project and run `herdr`. It launches or attaches to the default background session and creates a workspace automatically. First run shows an onboarding flow.
-2. Start their coding agent in the pane — `claude`, `codex`, or any supported agent (full list: https://herdr.dev/docs/agents/). Herdr detects it automatically; the sidebar shows its state. Installing the matching integration improves detection: `herdr integration install claude` (and similarly for other agents).
-3. Show them the mouse first: click panes and tabs to focus, drag split borders, right-click for menus, drag-select to copy. No keybindings are required to use Herdr.
+2. Start their coding agent in the pane — `claude`, `codex`, or any supported agent (full list: https://herdr.dev/docs/agents/). Herdr detects it automatically; the sidebar shows its state. Install the matching integration when available. Depending on the agent, it provides lifecycle state, native session restore, or both. For example, `herdr integration install claude` adds native session restore, while Claude's state still comes from screen detection.
+3. Start with the mouse: click panes and tabs to focus, drag split borders, right-click for menus, drag-select to copy. No keybindings are required to use Herdr.
4. Split panes: right-click menu, or `prefix+v` (right) / `prefix+minus` (down). New tab: `prefix+c`.
-5. Detach with `prefix+q` (press `ctrl+b`, release, press `q`) or simply close the terminal window. Everything keeps running. Reattach later with `herdr`.
+5. Detach with `prefix+q` (press `ctrl+b`, release, press `q`) or close the terminal window. Everything keeps running. Reattach later with `herdr`.
6. To actually stop everything: `herdr server stop`.
## The keyboard story
-Important framing for new users: Herdr does not require learning keybindings. The mouse covers everything. When the human wants keyboard control:
+New users do not need to learn keybindings; the mouse covers everything. When the human wants keyboard control:
- The prefix key is `ctrl+b` by default. `prefix+?` shows every active binding live.
-- The guided keyboard page — what the prefix is, which bindings to learn first, and a vetted prefix-free setup using `ctrl+alt` chords — is https://herdr.dev/docs/keyboard/. Recommend it over improvising.
+- The guided keyboard page covers the prefix, the bindings to learn first, and a vetted prefix-free setup using `ctrl+alt` chords: https://herdr.dev/docs/keyboard/. Recommend it over improvising.
- Every binding, including the prefix itself, is configurable under `[keys]` in the config file.
- If a direct chord does nothing, the OS or the outer terminal consumed it before Herdr could see it. The keyboard page explains which chords are safe and why.
## Install the Herdr skill into yourself
-Herdr ships `skills/herdr/SKILL.md` (https://raw.githubusercontent.com/herdrdev/herdr/master/skills/herdr/SKILL.md), an instruction file that teaches a coding agent to control Herdr from inside a pane — splitting panes, running commands without stealing focus, reading output, waiting on other agents.
+Herdr ships `skills/herdr/SKILL.md` (https://raw.githubusercontent.com/herdrdev/herdr/master/skills/herdr/SKILL.md), which teaches a coding agent to control Herdr from inside a pane: splitting panes, running commands without stealing focus, reading output, and waiting on other agents.
-Once the human is set up, offer to install it into your own harness so future sessions know Herdr natively. For agents supported by the open skills CLI, use `npx skills add herdrdev/herdr --skill herdr -g`. Agents without a skill system can paste the GitHub copy above into global custom instructions. Ask the human before writing to their config locations, and use the GitHub copy above as the source of truth.
+Once the human is set up, offer to install it for your coding agent so future sessions can control Herdr directly. For agents supported by the open skills CLI, use `npx skills add herdrdev/herdr --skill herdr -g`. For agents without a skill system, add the GitHub copy above to their global custom instructions. Ask the human before writing to their config locations, and use the GitHub copy above as the source of truth.
## Configuration
-- Config file: `~/.config/herdr/config.toml`. Herdr works without one.
+- Config file: `~/.config/herdr/config.toml` on Linux and macOS; `%APPDATA%\herdr\config.toml` on Windows. Herdr works without one.
- Print the full default config: `herdr --default-config`.
- Apply edits to a running server: `herdr server reload-config` (or the global menu → reload config).
- Main areas: `[keys]` keybindings, `[theme]` themes, `[ui]` sidebar and UI behavior, `[terminal]` shell defaults, `[update]` channel.
@@ -79,10 +79,10 @@ Once the human is set up, offer to install it into your own harness so future se
## Diagnosis recipes
-- **Agent not detected or wrong state:** `herdr agent list` to see what Herdr sees, `herdr agent explain <target> --json` to see why the detector classified a pane the way it did. Installing the agent's integration (`herdr integration install <name>`, status via `herdr integration status`) gives Herdr authoritative state instead of screen detection. Details: https://herdr.dev/docs/agents/ and https://herdr.dev/docs/integrations/
+- **Agent not detected or wrong state:** Run `herdr agent list` to see what Herdr sees and `herdr agent explain <target> --json` to see why the detector classified a pane that way. Integrations can provide lifecycle state, native session restore, or both; check `herdr integration status` and the agent support table before assuming an integration replaces screen detection. Details: https://herdr.dev/docs/agents/ and https://herdr.dev/docs/integrations/
- **A keybinding does nothing:** the outer terminal or desktop environment owns that chord. Point the human to https://herdr.dev/docs/keyboard/ to pick a safe one or free the chord in their terminal settings.
-- **Something looks wrong at startup or with the socket API:** logs are at `~/.config/herdr/herdr.log`, `~/.config/herdr/herdr-client.log`, and `~/.config/herdr/herdr-server.log`. `herdr status`, `herdr status server`, and `herdr status client` summarize the runtime.
-- **Remote questions:** SSH to the machine and run `herdr` there (works like tmux), or attach as a thin local client with `herdr --remote <host>`. Trade-offs: https://herdr.dev/docs/how-to-work/
+- **Something looks wrong at startup or with the socket API:** Default-session logs live in `~/.config/herdr/` on Linux and macOS and `%APPDATA%\herdr\` on Windows. Named-session logs live under `sessions/<name>/` inside that directory. `herdr status`, `herdr status server`, and `herdr status client` summarize the runtime.
+- **Remote use:** SSH to the machine and run `herdr` there (works like tmux), or attach as a thin local client with `herdr --remote <host>`. Trade-offs: https://herdr.dev/docs/how-to-work/
- **What survives a detach, restart, or update:** https://herdr.dev/docs/session-state/
## Rules for you
diff --git a/website/src/content/blog/coding-agents-are-becoming-runtimes.md b/website/src/content/blog/coding-agents-are-becoming-runtimes.md
index ae2fb0a2..3628f4ec 100644
--- a/website/src/content/blog/coding-agents-are-becoming-runtimes.md
+++ b/website/src/content/blog/coding-agents-are-becoming-runtimes.md
@@ -5,19 +5,15 @@ date: 2026-06-10
draft: false
---
-Coding agents have crossed an important line.
+Coding agents started as chat interfaces that could edit code. Now they live inside repositories, terminals, editors, CI jobs, remote machines, mobile shells, multiplexers, and custom wrappers. They read project instructions. They run commands. They ask for permission. They spawn subagents. They pause, resume, compact, fail, recover, and keep working while the developer does something else.
-They started as chat interfaces that could edit code. Now they live inside repositories, terminals, editors, CI jobs, remote machines, mobile shells, multiplexers, and custom harnesses. They read project instructions. They run commands. They ask for permission. They spawn subagents. They pause, resume, compact, fail, recover, and keep working while the developer does something else.
-
-That shape is familiar.
-
-**This is runtime behavior.**
+That is runtime behavior.
The model can be proprietary. The hosted API can be proprietary. The subscription can be priced however the lab needs to price it. That part belongs to the companies building the models.
But the CLI that runs inside a developer's terminal is part of the developer environment. It sits next to shells, language servers, package managers, test runners, terminals, editors, and multiplexers. Developers will compose it with the rest of their tools whether vendors plan for that or not.
-**That is where the industry needs to be more careful.**
+That is where the industry needs to be more careful.
## We have seen this drift before
@@ -51,23 +47,21 @@ Nobody loses a production database because a repo has two instruction files. The
## The terminal is the shared surface
-There is another debate happening around access and harnesses.
+There is another debate happening around access and third-party tools.
Coding agents made per-token pricing feel very different. A chat session can be expensive. A coding agent can run tools, read files, loop, spawn work, and burn through a lot more context. So the labs started selling subscriptions with usage limits: some explicit, some soft, some hourly, some weekly, some hard to reason about from the outside.
-Then developers started doing what developers always do. They put the model behind the harness they preferred.
+Then developers started doing what developers always do. They put the model behind the tool they preferred.
-That is where the Claude ecosystem became a useful case study. People used Claude subscriptions through third-party harnesses such as OpenClaw and OpenCode. Anthropic pushed back. Today Anthropic documents that [Claude Code can use Pro and Max subscriptions](https://support.claude.com/en/articles/11145838-use-claude-code-with-your-pro-or-max-plan), while [Claude paid plans and API access are separate products](https://support.claude.com/en/articles/9876003-i-have-a-paid-claude-subscription-pro-max-team-or-enterprise-plans-why-do-i-have-to-pay-separately-to-use-the-claude-api-and-console). Anthropic also introduced a separate [Agent SDK credit](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan) for programmatic and third-party Agent SDK usage. Zed summarized the practical effect well: first-party Claude usage and third-party agent or SDK usage now draw from different pools.
+That is where the Claude ecosystem became a useful case study. People used Claude subscriptions through third-party tools such as OpenClaw and OpenCode. Anthropic pushed back. Today Anthropic documents that [Claude Code can use Pro and Max subscriptions](https://support.claude.com/en/articles/11145838-use-claude-code-with-your-pro-or-max-plan), while [Claude paid plans and API access are separate products](https://support.claude.com/en/articles/9876003-i-have-a-paid-claude-subscription-pro-max-team-or-enterprise-plans-why-do-i-have-to-pay-separately-to-use-the-claude-api-and-console). Anthropic also introduced a separate [Agent SDK credit](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan) for programmatic and third-party Agent SDK usage. Zed summarized the practical effect well: first-party Claude usage and third-party agent or SDK usage now draw from different pools.
-Anthropic can make that decision. They own the API. They own the subscription terms. Compute is expensive, and a first-party interactive CLI has different economics from arbitrary programmatic harnesses running through an SDK or protocol adapter.
+Anthropic can make that decision. They own the API. They own the subscription terms. Compute is expensive, and a first-party interactive CLI has different economics from arbitrary programmatic tools running through an SDK or protocol adapter.
-The developer-tooling question remains.
-
-> What does a developer actually own: the subscription, the API spend, the model access, or the runtime where the agent works?
+The developer-tooling question remains: what does a developer actually own—the subscription, the API spend, the model access, or the runtime where the agent works?
When an agent runs in a terminal, it is no longer only a hosted product experience. It is a process in a developer environment. Developers will put that process in Herdr, Zed, tmux, SSH sessions, CI jobs, containers, and scripts. They will supervise it. They will route it. They will build workflows around it.
-**The terminal is where ownership gets shared.**
+The terminal is where ownership gets shared.
That does not mean vendors lose the right to build first-party experiences. It means the CLI surface needs stable contracts because it has become infrastructure other tools depend on.
@@ -102,7 +96,7 @@ The concrete shape could be small:
Permission prompts, failed tools, interrupted generations, automated reviews, subagent handoffs, and waiting for the user all need to land somewhere coherent.
-Claude Code has a serious hook system, and Codex has its own shape too. The problem is not that these tools do nothing. The problem is that each agent defines its own boundary. A hook surface can be powerful and still fail to provide a portable lifecycle contract.
+Claude Code has a serious hook system, and Codex has its own shape too. Both are substantial, but each agent still defines its own boundary. A hook surface can be powerful and still fail to provide a portable lifecycle contract.
OpenCode is closer to the shape orchestration tools need. Its [plugin documentation](https://opencode.ai/docs/plugins/) exposes session-level events such as `session.idle`, `session.status`, `session.error`, `permission.asked`, and `permission.replied`.
@@ -112,7 +106,7 @@ Those designs are worth praising because they treat the agent as something other
## What Herdr sees from below
-**Herdr sits below the agent.**
+Herdr sits below the agent.
It owns terminal panes. It keeps processes alive. It lets developers switch between agents, inspect them, recover sessions, and operate multiple agent processes as one workspace.
@@ -145,15 +139,13 @@ Other agents require observed detection through terminal output, screen evidence
Herdr will publish this as a per-agent support matrix: which agents expose verified lifecycle signals, and which agents require observed detection.
-**This distinction should be public because it helps everyone.**
+This distinction should be public because it helps everyone.
Users get honest expectations. Agent authors get a target. Tool builders get a vocabulary. The ecosystem rewards agents that expose their runtime state cleanly.
-The goal is not to force every agent to use the same plugin system. The goal is to standardize the parts that should never have been product differentiation.
-
-## The ask
+Agents can keep their own plugin systems while standardizing the parts that should never have been product differentiation.
-**Standardize the boring parts.**
+## Standardize the boring parts
Use one predictable project instruction format. Expose a small lifecycle contract. Make permission state observable. Make interruption state observable. Tie state to the session that is actually running. Document what external tools can rely on.
@@ -169,6 +161,6 @@ Coding agents are becoming infrastructure. The companies building them still own
Herdr is built from that position. The terminal is where these agents actually run. The runtime surface belongs to the developer workflow, and vendors share that space whether they design for it or not.
-The better future is simple: agents should make their basic contracts visible, durable, and boring.
+Agents should make their basic contracts visible, durable, and boring.
Then the rest of us can build.
diff --git a/website/src/content/blog/herdr-0-6-3.md b/website/src/content/blog/herdr-0-6-3.md
index 6e375604..3abb5f5f 100644
--- a/website/src/content/blog/herdr-0-6-3.md
+++ b/website/src/content/blog/herdr-0-6-3.md
@@ -7,9 +7,9 @@ draft: false
## Persistence for the hard parts
-Session persistence is not one feature. A detached client, a stopped server, a terminal history replay, an agent conversation restore, and an update handoff all protect different parts of the workspace.
+Keeping a session alive means handling several different cases: a detached client, a stopped server, terminal history replay, agent conversation restore, and an update handoff. Each protects a different part of the workspace.
-Herdr 0.6.3 pushes on three of those boundaries.
+Herdr 0.6.3 improves three of those paths.
### Agent restore after server restart
@@ -62,7 +62,7 @@ Herdr also gained better update and remote-bootstrap behavior for package-manage
The new `pane.report_metadata` socket method and `herdr pane report-metadata` CLI command let integrations and local hooks customize what Herdr shows for a pane.
-After installing an integration, the integration can report a title, visible agent name, compact status label, state label, and native session metadata without taking over unrelated lifecycle behavior.
+Once installed, an integration can report a title, visible agent name, compact status label, state label, and native session metadata without taking over unrelated lifecycle behavior.
You can also use it from your own scripts. For example, a hook can mark a pane as running a deploy, rename a long-lived task, or ask an agent to report a more specific state for the work it is doing.
diff --git a/website/src/content/blog/herdr-is-joining-y-combinator.md b/website/src/content/blog/herdr-is-joining-y-combinator.md
index ff93b509..3a9cfa3e 100644
--- a/website/src/content/blog/herdr-is-joining-y-combinator.md
+++ b/website/src/content/blog/herdr-is-joining-y-combinator.md
@@ -17,19 +17,19 @@ Same idea here. I didn't like what I tried, so why not build it? So I built a ru
## Runtime
-CLI coding agents run in terminals, and terminals have always been our home: editing code (yes, nvim chads), running servers, navigating projects, maintaining CI, machines, configurations. It's the root. It's the connection. So agents need first class primitives there.
+CLI coding agents run in terminals, and terminals have always been our home: editing code (yes, nvim chads), running servers, navigating projects, maintaining CI, machines, configurations. It's the root. It's the connection. So agents need first-class primitives there.
A terminal pane belongs to an agent. A pane belongs to a tab. Tabs belong to a project.
They need to be persistent. We have agents running for hours now, sometimes days. And once you have the runtime, where they run stops mattering. **You should be able to run them anywhere and keep them running.**
-That's where Herdr was born. But a runtime without an interface is nothing, so: the TUI.
+That's where Herdr was born. But a runtime needs an interface, so I built the TUI.
## TUI
-The TUI is the UI I use every day, and it carried Herdr this far. Not because it's a UI, but because it shows the concepts Herdr believes in: tracking agents at a glance, dividing work between projects instead of getting lost in a pile of agents, being alerted only when an agent actually needs you.
+The TUI is the UI I use every day, and it carried Herdr this far because it shows what I believe Herdr should do: track agents at a glance, divide work between projects instead of getting lost in a pile of agents, and alert you only when an agent actually needs you.
-It also has one big advantage, and it's the reason it stays first class forever: it's bundled. Install Herdr on your VPS, ssh in, and your UI is already there. Or run `herdr --remote user@host` and it installs itself. Depending on your network speed, you're a couple of seconds away from an agent running. One command and you're in. Nothing beats that.
+Its biggest advantage, and the reason it stays first-class forever, is that it's bundled. Install Herdr on your VPS, ssh in, and your UI is already there. Or run `herdr --remote user@host` and it installs itself. Depending on your network speed, you're a couple of seconds away from an agent running. One command and you're in. Nothing beats that.
Still, the TUI was never meant to be the only client. A runtime means people can build on top of it, and people did! A [Raycast extension](https://x.com/vladscale/status/2080195067088871582), a [Stream Deck with buttons for herdr](https://x.com/timvdhoorn/status/2067907258260795808), an [iOS app](https://x.com/imnotchalk/status/2077647387414384936) that drives a whole session from a phone. More than 500 plugins, one month after the marketplace released. I didn't build any of these.
@@ -39,15 +39,13 @@ The TUI has its limits too. Some of the ideas in my head are hard to build insid
So a solo project reached **25k stars and 340k downloads**, and it became more than one person can carry.
-Herdr is joining <span style="color:#fb651e">Y Combinator, F26 batch</span>. I'm excited to make Herdr a company that builds a developer tool for anyone juggling agents all day. I want to build a small team: people who keep the runtime healthy, robust, fast, running anywhere easily, and more extensible. Letting you do more while Herdr stays small.
+Herdr is joining <span style="color:#fb651e">Y Combinator, F26 batch</span>. I'm excited to make Herdr a company that builds a developer tool for anyone juggling agents all day. I want to build a small team: people who keep the runtime healthy, reliable, fast, easy to run anywhere, and more extensible, so you can do more while Herdr stays small.
-The runtime, what you use right now, stays free. Apache-2.0. That's why I recently switched it from AGPL to Apache: I want everyone to use Herdr freely, without any problem.
+The runtime, what you use right now, stays free. Apache-2.0. That's why I recently switched it from AGPL to Apache: I want everyone to use Herdr freely.
## Where we're going
-I want to build on top of the open Herdr runtime like everyone else. I'll keep supporting the open source while building the features people really need. The demand is already visible: multiple clients, a laptop, a VPS for the six hour job, a sandbox for risky code and ephemeral agents. Herdr can run anywhere today, but those machines are disconnected.
-
-**It should be connected.**
+I want to build on top of the open Herdr runtime like everyone else. I'll keep supporting the open source while building the features people really need. The demand is already visible: multiple clients, a laptop, a VPS for the six-hour job, a sandbox for risky code and ephemeral agents. Herdr can run anywhere today, but those machines are disconnected. They should be connected.
There are many more features in my head, but I don't want to rush. People keep telling me they love that Herdr stays lean, and that's what I want to protect. In an age where adding one more feature costs nothing, choosing what goes in the core is the most important decision, I believe. So the core stays small, and everything else stays possible through extensions: your style, your flows, your company's setup, your themes, your crazy ideas.
diff --git a/website/src/content/blog/live-updates-without-killing-your-terminal-processes.md b/website/src/content/blog/live-updates-without-killing-your-terminal-processes.md
index b78a3caf..6658c488 100644
--- a/website/src/content/blog/live-updates-without-killing-your-terminal-processes.md
+++ b/website/src/content/blog/live-updates-without-killing-your-terminal-processes.md
@@ -16,7 +16,7 @@ Herdr has a different problem. It is a terminal multiplexer, sure, but it is als
It gets frequent fixes for agent detection (isn't it cool that we have all the labs building their own CLIs, plugins, and hooks in their own broken way?), terminal behavior, remote workflows, worktrees, mobile use, update flows, and integrations. Users should not have to choose between getting those fixes and killing every pane in a running session.
-That's a problem: Herdr needed to update like an app while preserving processes like a terminal multiplexer.
+Herdr needed to update like an app while preserving processes like a terminal multiplexer.
## The update problem
@@ -34,7 +34,7 @@ Tmux has the same class of version-skew behavior. Users hit protocol mismatch er
As far as I can tell, mainstream terminal multiplexers do not do in-place server binary replacement while keeping arbitrary live pane processes attached.
-So, that is a small breakthrough, but a real one.
+That is a small breakthrough, but a real one.
## The important detail is PTY ownership
@@ -96,7 +96,7 @@ Full-screen terminal apps are different. Herdr does not fake replay for alternat
## The invariants
-The hard part was not sending FDs. The hard part was making the transaction safe.
+Sending FDs was easier than making the transaction safe.
These were the rules:
@@ -116,12 +116,10 @@ This is not checkpoint/restore. It does not survive a reboot. It does not migrat
It is a same-machine Unix handoff. The running pane process stays attached to its PTY slave. The old Herdr server transfers the PTY master to the new Herdr server. The server binary changes; the pane process keeps running.
-That is the useful boundary.
-
## Why this is cool
Herdr users often keep the exact kind of work open that should not be casually restarted: coding agents, dev servers, shells, REPLs, SSH sessions, debugging sessions, long builds, and local experiments.
A terminal multiplexer should make that work safer, not make updates feel dangerous.
-The interesting part is not that Herdr remembers your layout. The interesting part is that the process inside the pane does not have to know an update happened.
+The process inside the pane does not have to know an update happened.
diff --git a/website/src/content/blog/ten-agents-three-clients-95-percent-less-cpu.md b/website/src/content/blog/ten-agents-three-clients-95-percent-less-cpu.md
index 635e787e..6aef6af1 100644
--- a/website/src/content/blog/ten-agents-three-clients-95-percent-less-cpu.md
+++ b/website/src/content/blog/ten-agents-three-clients-95-percent-less-cpu.md
@@ -6,11 +6,11 @@ ogImage: /assets/og-blog-frames-v1.png
draft: false
---
-Across workloads dominated by unnecessary rendering, total CPU for the Herdr server and its attached clients fell by 89 to 95 percent. The renderer still runs at the same speed. Herdr now asks it to draw fewer frames.
+In workloads dominated by unnecessary rendering, total CPU for the Herdr server and its attached clients fell by 89 to 95 percent. The renderer still runs at the same speed. Herdr now asks it to draw fewer frames.
-The saving grows with the session. With one agent and one client, total CPU fell 91 percent. With ten agents producing background output and three clients, it fell 95 percent. Every frame the server skips is also one less frame to serialize, transmit, and apply in each client.
+The savings grow with the session. With one agent and one client, total CPU fell 91 percent. With ten agents producing background output and three clients, it fell 95 percent. Every frame the server skips is also one less frame to serialize, transmit, and apply in each client.
-Three changes got us there, and none came from a profiler. The first started as a complaint and gave us a rule. Motion should mean something changed.
+We found all three changes without a profiler. The first started as a complaint and gave us a rule: motion should mean something changed.
## The spinner was a complaint before it was a cost