herdr Integration

herdr is a terminal session manager built for coding agents. Nexion offers it next to tmux in the same Sessions panel: open a herdr session, a workspace or a single pane as Nexion spaces, groups and tabs, on this Mac or over SSH.

Overview

Nexion does not redraw herdr. A pane attached to herdr runs herdr's own client inside the terminal, with herdr's interface, keys and mouse. What Nexion adds is the frame around it:

  • • herdr's shape, as Nexion's: a session becomes a space, a workspace (with its linked worktrees) a sidebar group, a pane a tab, named the way herdr names them.
  • • Work from the panel: create sessions and worktrees, split panes, rename groups and tabs, and herdr follows.
  • • Safe by default: closing a tab only detaches. Nexion never installs, updates or starts herdr on its own.

Getting Started

Prerequisites

  • • herdr installed where the session lives: on this Mac, on the SSH host, or both. Tested with herdr 0.9.5; Nexion needs herdr session list --json, and an older herdr without it is reported, not worked around.
  • • Where Nexion looks: ~/.local/bin, Homebrew, mise shims, ~/.nix-profile/bin, ~/.cargo/bin, then PATH. The same list is used on SSH hosts.
  • • For remote hosts: the SSH hosts Nexion already knows (bookmarks, ~/.ssh/config, active connections). No separate credentials.

Open the Sessions Panel

  • • Command Palette: run "herdr: Attach Session..." to open the panel on herdr.
  • • Toolbar: the Sessions button (the same one tmux uses; turn it on as described in tmux Integration) reads "Sessions (tmux, herdr)" when herdr is installed on this Mac.
  • • The herdr | tmux switch: at the top of the panel, with herdr's mark. It appears on this Mac when herdr is installed here, and on an SSH host when herdr is installed here too or an earlier listing found it on that host.

Without herdr nothing changes: the panel keeps its tmux title and shows no switch.

How herdr Maps onto Nexion

herdr Nexion
Session A space, named after the session
Workspace A sidebar group; its linked worktrees sit inside their repository's group
Pane A tab
Workspace shown by one tab That tab, its panes as splits. In a group the workspace is named Group - Tab, outside one just Tab (what the session builder makes)

Names follow herdr: a linked worktree goes by its branch, a tab adds herdr's tab label when the workspace has several, and the pane title when that tab is split. In the sidebar a herdr tab wears a herdr tag, like tmux and SSH, and the line under its name is its branch (or TERMINAL when it has none).

Opening Sessions, Workspaces and Panes

The panel lists every running session with its panes, grouped by workspace and tab. Open as much or as little as you need:

Action Result
Space (session row) A new space named after the session, one group per workspace, one tab per pane. Opening it again returns to that space and adds only the panes not open yet.
Open all (workspace header) The same group, in the current space.
Pane / Tab (pane row) Just that pane's terminal, in a Nexion split or a tab of its own.

herdr allows one client per pane, so a pane already open in Nexion is focused instead of opened a second time. A stopped session shows Start: Nexion starts it and opens it as a space.

New Session: the Builder

With herdr selected, New Session opens a window where you lay the session out as Nexion will show it, then Create makes it in herdr and opens it as a space.

  • • Session and space: the herdr session's name (letters, digits, . _ -) and the space it opens as, the session's name when left empty.
  • • Tabs: each one is a herdr workspace, with a group (optional), a name and a folder. Tabs with the same group open together in that sidebar group.
  • • Panes: one, side by side, stacked, main and two, or a grid. Each pane starts a shell, Claude Code, Codex, Gemini, opencode or a command you type; herdr runs it (herdr pane run), so herdr follows the agent from the start. The tab opens with the same splits herdr has.
  • • Preview: the space as it will open, with the herdr name of every workspace.

Everything goes through herdr's documented commands (workspace create, pane split, pane run). If a step fails, the window says which one, and what was made so far stays running in herdr, listed in the panel.

New Worktree

Hover a repository's main workspace and choose New worktree. The inline form asks for a branch (new or existing) and an optional base; left empty, herdr uses its default (the checkout's HEAD).

herdr creates the worktree, picks its folder and opens it as a workspace. The panel shows it nested under its repository, highlighted as New and ready for Open all or Tab. Nexion never trusts a repository on your behalf: if git does not trust it, herdr's message is shown and trusting it is done in herdr.

A worktree row also offers Remove…, which asks first: herdr closes its panes and deletes the checkout folder, the branch and its commits stay, and git refuses (nothing is removed) when the checkout has uncommitted changes.

Worktrees and Nexion Tasks

  • • From herdr to Nexion: the Task button on a worktree row opens it as a task of the Nexion project whose folder is the worktree's repository (the task already on that checkout, if there is one). The checkout stays herdr's: Nexion never removes it when the task goes.
  • • From Nexion to herdr: right-click a task that has a worktree and choose Open Worktree in herdr. herdr opens the checkout as a workspace in a running session (you pick which when several run) and its pane opens in a split beside the task, so herdr's agents work in the same checkout.

Working in herdr from Nexion

  • • Split: right-click a single herdr pane and choose herdr > Split Vertically or Split Horizontally. The pane splits in herdr (herdr's focus untouched) and the new herdr pane opens in a Nexion split beside it, as tmux's items do. The Pane menu has the same as Split in herdr Right (⌃⌥⌘D) and Below (⌃⌥⇧⌘D), also in the command palette. A whole-session pane splits with herdr's own keys.
  • • A tab that is a whole workspace: when a Nexion tab is the only one showing a herdr workspace, the workspace is named after it, Group - Tab in a group (the tab App in the group Nexion is the workspace Nexion - App) and Tab outside one. Both ways, always: renaming the tab or its group, or moving the tab to another group, renames the workspace; renaming the workspace in herdr renames the tab (the part after Group - ), and a name typed in herdr without the group gets it back.
  • • Rename a group: when the group is one herdr workspace (every tab a single pane of the same session, in that workspace and its linked worktrees), renaming it renames the workspace in herdr too, and renaming the workspace in herdr renames the group. A group of tabs that are each a whole workspace renames those workspaces instead, as above. Any other group is Nexion's alone.
  • • Rename a tab: a Nexion tab that is exactly one herdr tab keeps the name in step both ways. Renaming it in Nexion renames the herdr tab; a rename in herdr replaces the part of the Nexion name that was herdr's old label, so "pluto · 1" becomes "pluto · build". A name you gave that has no such part stays.
  • • Sidebar: a herdr tab carries a herdr signal on its right edge (a lit bar and the word in the corner), like tmux and SSH tabs, and the line under its name is its branch (or TERMINAL when it has none), so worktrees read apart at a glance.
  • • Agent icon: a herdr tab wears the mark of the agent herdr sees in it (Claude Code, Codex and others), checked while a herdr tab is open: every few seconds on this Mac, every 30 seconds over SSH.

Agents, Live

  • • Agent state: what herdr knows about the agent in each pane drives Nexion: the working line under the tab while it works, a "waiting for you" notification when it is blocked on you, and a "finished" notification (plus notify-when-done and the phone) when herdr counts a turn as done, so a pause mid-answer does not ring. On this Mac it follows herdr's live event stream; over SSH it is checked every 30 seconds.
  • • The agent's own word first: when an agent's Nexion hooks reach the pane (for example Claude Code started inside herdr from a Nexion terminal), they decide working, waiting and finished, as in any other pane. herdr's reading of the screen is used only where no hook arrives. Codex, Antigravity and OpenCode report from any herdr pane open in Nexion, wherever the herdr server was started. Claude Code and Copilot report through Nexion's own terminals, so from a herdr server started elsewhere they do not; for Claude, the pane then offers Add Claude Hooks…, which (after a confirmation) adds Nexion's hooks to Claude Code's settings. They act only in herdr panes outside Nexion's terminals, a backup of your settings is kept, and Settings › Terminal › Notifications removes them.
  • • Start an agent in herdr: with a herdr pane focused, the AI toolbar starts the agent in herdr, in a new pane beside it, so herdr tracks it from the first moment. Your current pane is left as it is.
  • • New herdr tab: from a herdr pane's context menu, or "New tab" on a workspace in the panel. It opens in Nexion next to the tab you came from.
  • • Moved panes: move a pane to another workspace in herdr and its Nexion tab follows it into that workspace's group. The pane itself never drops.
  • • On the phone: a herdr pane shows its full history, read from herdr, and is named after the agent running in it.

herdr's Agent Integrations

herdr has its own integrations for many agents: a small hook or plugin that lets the agent report to herdr directly instead of herdr reading it from the screen. When herdr has detected an agent in one of its panes and its integration is not installed (or is out of date), the Sessions panel shows a banner with Install… and Not Now.

  • • Only after a yes: Install… asks first, naming the file herdr writes and the agent settings it registers it in, on this Mac or on the SSH host shown. Then it runs herdr integration install <agent>. Nexion never installs one on its own.
  • • Not Now hides the offer until you open the panel again. Check what is installed with herdr integration status, remove one with herdr integration uninstall <agent>.
  • • What each one gives is herdr's call. As of herdr 0.9.5, the integrations for pi, OMP, Mastra Code, OpenCode, Kilo and Kimi drive herdr's agent state; Claude Code's tells herdr which conversation runs in the pane, while working and blocked are still read from the screen (Nexion's own hooks cover those, see above).

From the Command Line

nexion herdr sessions, panes and open do from a script, or from an agent through MCP, what the Sessions panel does: list sessions, see which herdr panes Nexion shows and what their agents are doing, and open a session, workspace or pane in Nexion. They never start a session. See herdr Commands.

This Mac and SSH

On this Mac the pane runs herdr directly. Over SSH, Nexion runs herdr on the host through its own SSH connection (with the bookmark key and jump host you already use), which is herdr's documented "SSH to the server and run herdr there" path. herdr --remote is not used: it would open a second connection with its own authentication and need herdr on the Mac too.

Agent state, renames made inside herdr and branch names follow on SSH hosts too, read every 30 seconds over the tab's existing connection (branches less often). These background reads never open a connection of their own, and any login shell on the host works (bash, zsh, fish). herdr splits inside an SSH tab come back attached when Nexion restarts. Opening a worktree as a Nexion task is this Mac only.

Detach, Reattach and Stop

  • • Closing only detaches: closing a pane, a tab or a space, quitting Nexion or losing SSH detaches the client. The herdr session and its processes keep running.
  • • Reattach: when the herdr client exits, the pane keeps its last screen and offers Reattach, Sessions… and Close. Reattach is one attempt per click, never automatic.
  • • Restore at launch: herdr tabs come back only if their session is still running. Nexion never starts or recreates a session on its own; a pane that cannot attach says why.
  • • Close, stop, delete: the only destructive actions, in the panel, labelled, and all of them ask first. Close… on a workspace closes it with its tabs and panes (the session keeps running), Stop… on a running session ends it, Delete… on a stopped session removes it and its saved layout, and Remove… on a worktree deletes its checkout.
  • • No takeover: Nexion never takes a pane away from another herdr client.

herdr-core

herdr's headless runtime, with Nexion as its interface, has its own page: herdr-core Integration.

Not Supported (Yet)

  • • Two windows on one pane: a pane open in Nexion and in herdr's own interface shares one terminal size, so the smaller window wins.

Troubleshooting

Problem Solution
No herdr | tmux switch Install herdr in one of the folders listed above. On an SSH host, the switch shows once herdr is installed on this Mac too or a listing has found it there.
herdr reported as too old Update herdr (tested with 0.9.5). Nexion never updates it for you.
A restored tab does not attach Its session is no longer running. Start it from the panel, then use Reattach.
Agent state lags or misses a step Start the herdr server from a Nexion terminal so the agent's Nexion hooks reach it, and install herdr's integration for the agent when the panel offers it.
New worktree fails on trust Trust the repository in herdr, then try again.