diff options
Diffstat (limited to 'website/agent-guide.md')
| -rw-r--r-- | website/agent-guide.md | 30 |
1 files changed, 15 insertions, 15 deletions
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 |