# Setup Herdr > Install herdr (terminal-native agent multiplexer), set up its Claude Code and OpenCode integrations, and configure shell profiles to auto-launch herdr on startup (replacing any existing Zellij autostart block). Use when the user wants to install or configure herdr. - Skill: `atman-33/setup-herdr` (Agent Skill) - Install (CLI): `npx skillmds@latest add atman-33/setup-herdr` - Raw SKILL.md: https://api.skillmd.com/api/skills/atman-33/setup-herdr/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: atman-33 (https://skillmd.com/u/atman-33) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/atman-33/setup-herdr --- ## Task Install `herdr` (https://herdr.dev), a terminal-native agent multiplexer, wire up its Claude Code / OpenCode integrations, and configure shell profiles so `herdr` launches automatically on startup — replacing any existing Zellij autostart installed by `setup-zellij`. ## Environment note: this session can be hosted on either side This skill touches both a Windows environment and a WSL environment, and the agent session driving it can be hosted on **either** — the interop direction flips accordingly: - **Hosted in WSL:** reach Windows via `powershell.exe`/`pwsh.exe`, and read/edit Windows profile files directly at their `/mnt/c/...` path rather than shelling a multi-line edit through `powershell.exe -Command` — quoting an edit through a nested shell is fragile; a direct file edit is not (the same class of problem step 4's here-string warning describes). - **Hosted on Windows:** reach WSL via `wsl -- `, as this skill's snippets show by default. Determine which applies once, then use the matching direction for every step below. The same preference — direct file access over a shell-quoted command — also applies to the idempotency checks in steps 1, 3, and 4: read a file's content and inspect it rather than piping it through `grep`/`Select-String` across the interop boundary. ## Steps ### 1. Check herdr installation (per environment) A PATH-only check false-negatives: herdr's own installer doesn't add itself to PATH (see step 2), so the binary can be present — even running — without `Get-Command`/ `which` finding it. Check, in order, until one hits: **Windows:** `Get-Command herdr -ErrorAction SilentlyContinue` → known install dirs (e.g. `Test-Path "$env:LOCALAPPDATA\Programs\Herdr\bin\herdr.exe"`) → a running process (`Get-Process herdr -ErrorAction SilentlyContinue`). **WSL:** `which herdr` → `$HOME/.local/bin/herdr` (the installer's default target). Record whichever path resolved it — step 4 needs it to invoke herdr if it never lands on PATH. If found by any check, mark the environment "already installed" and skip to step 3 for it. Only when every check is empty, continue to step 2 for that environment. --- ### 2. Install herdr (only after user confirmation) These are official installers that download and execute a remote script — always show the exact command and get the user's go-ahead before running it via Bash/PowerShell (same convention as how `setup-harness` handles `uv`/`openspec` installs). **WSL/Linux:** ```bash curl -fsSL https://herdr.dev/install.sh | sh ``` **Windows** (official support is currently **beta/preview**, ConPTY-based — mention this to the user): ```powershell irm https://herdr.dev/install.ps1 | iex ``` > The installer places the binary at `${HERDR_INSTALL_DIR:-$HOME/.local/bin}` (WSL) and > does **not** edit any shell rc file itself — it only warns if that directory isn't > already on `PATH`. If it warns, tell the user to add > `export PATH="$HOME/.local/bin:$PATH"` to their shell profile (or note it as a > follow-up; don't silently add it as part of this skill's own autostart block). If the user declines, mark that environment "skipped (declined)" and continue with the other environment. --- ### 3. Install integrations (idempotent check, then run) For each environment where herdr is now present: **Claude Code integration** (Windows and WSL): read `~/.claude/settings.json` directly and check for an existing herdr hook entry, and check whether the hook script exists (`~/.claude/hooks/herdr-agent-state.sh` on WSL, `herdr-agent-state.ps1` on Windows). If both are present, mark "already configured"; otherwise run: ```bash herdr integration install claude ``` **OpenCode integration** (WSL/Linux/macOS only — **not supported on Windows**; mark the Windows environment "N/A" and don't attempt it there): check whether `~/.config/opencode/plugins/herdr-agent-state.js` exists. If so, mark "already configured"; otherwise run: ```bash herdr integration install opencode ``` --- ### 4. Configure shell profiles: remove Zellij autostart > **PowerShell profile paths** — Do NOT hardcode `C:\Users\...\Documents\...`. > - **PS7**: `$PROFILE` resolves correctly in all cases. > - **Windows PowerShell**: build the path with > `Join-Path ([Environment]::GetFolderPath("MyDocuments")) "WindowsPowerShell\Microsoft.PowerShell_profile.ps1"` > so OneDrive-redirected Documents folders are handled automatically. > Direct file access (Read/Edit tool) at the resolved path is more reliable than > shelling a multi-line edit through `powershell.exe -Command`. Process the same **four profiles** as `setup-zellij`, independently: PowerShell 7 (`$PROFILE`), Windows PowerShell (path resolved via `GetFolderPath` above), WSL `~/.bashrc`, and WSL `~/.zshrc` (only if zsh is installed). For each profile, remove any existing Zellij autostart block. Zellij's autostart shows up in **two** forms — check for and remove whichever is present: **Manual block** (PowerShell profiles and WSL bash/zsh) — look for the `# Auto-start Zellij` comment; if present, remove it together with the block that follows, through the matching closing `}` (PowerShell) or `fi` (bash/zsh): ```powershell # Auto-start Zellij if (-not $env:ZELLIJ) { $cwd = (Get-Location).Path zellij options --default-shell --default-cwd $cwd } ``` ```bash # Auto-start Zellij if [[ -z "$ZELLIJ" ]]; then zellij fi ``` (e.g. `sed -i '/# Auto-start Zellij/,/^fi$/d' ~/.bashrc` for bash/zsh — the block shape is fixed and known, so a range delete from the comment through the next `^fi$` is safe.) **Official zsh method** (WSL `~/.zshrc` only) — `setup-zellij` also recognizes Zellij's own `zellij setup --generate-auto-start zsh` mechanism and skips adding a second block when it finds one already there. If *this* skill finds that mechanism, it must still remove it. Look for a line containing `generate-auto-start`; if present, remove it along with its neighboring comment and any `ZELLIJ_AUTO_ATTACH` export: ```bash # Zellij auto-attach (added by ...) eval "$(zellij setup --generate-auto-start zsh)" export ZELLIJ_AUTO_ATTACH=true ``` If neither form is found in a given profile, note "(nothing to remove)" and continue. Also remove any existing `# Auto-start herdr` block if present (from a previous `setup-herdr` run), as herdr is no longer auto-launched from profiles. --- ### 5. Report results (follow the Output Format below) ## Output Format ``` ## herdr Setup | Environment | herdr install | Claude Code integration | OpenCode integration | |---------------|------------------|----------------------------|-------------------------| | WSL/Linux | | | | | Windows | | | N/A (not supported on Windows) | | Profile | Zellij autostart removed | Profile Path | |-----------------------|-----------------------------------------------------------------------------|--------------| | PowerShell 7 | | <$PROFILE path> | | Windows PowerShell | | | | WSL bash | | ~/.bashrc | | WSL zsh | | ~/.zshrc | ### Actions taken - ### Next steps - Run `herdr --version` to double check the install landed correctly. - Launch herdr manually with `herdr` (or the full path on Windows) to confirm it works. ```