herdr-core Integration

herdr-core (hc) is herdr's headless runtime: it keeps terminals and agents running and draws nothing. Nexion is its interface: every herdr-core terminal is a native Nexion pane, on this Mac or on the machines herdr-core has added.

Overview

  • • Native terminals: a pane runs hc attach, which carries the program's own output, so scrollback, ⌘F, selection and the mouse work as in any Nexion pane.
  • • Nexion's shape: terminals are labelled with their Nexion space, group, tab and layout, so they come back as the same tabs and splits.
  • • Safe by default: closing a pane, a tab or Nexion only detaches. Nexion never installs, updates, restarts or stops herdr-core on its own.

herdr-core and herdr's own interface are separate servers: terminals in one do not show up in the other. For herdr's TUI see herdr Integration.

Getting Started

  • • Install hc on this Mac: from herdr.dev/core. Nexion looks for it where it looks for herdr (~/.local/bin, Homebrew, mise, ~/.cargo/bin, then PATH).
  • • Open the Sessions window: from the toolbar's Sessions button or the Command Palette. With hc installed it opens on herdr-core, first of its three managers (herdr-core, herdr, tmux).
  • • Pick a machine, then its terminals: This Mac, the machines herdr-core has added, and the hosts you can add, each with its terminals grouped by Nexion group.

Without hc nothing changes: the window shows herdr and tmux only.

Sessions and Terminals

New herdr-core Session

The builder lays out tabs and panes as Nexion will show them: each pane becomes a herdr-core terminal running a shell or the agent you picked, in the folder you chose, on the machine you picked. An agent that exits leaves a shell in its place.

  • • Open in: herdr-core has no spaces of its own, so you choose the Nexion one: this space, another, or New space…. The choice is written on the terminals, never a space made because of a name.
  • • Groups and tabs: named in the builder, they become the sidebar group and tabs, and the terminals' labels.

Open all

Open all rebuilds a machine's terminals as their tabs and splits: in the space they were made for (by its id, then by its name), else in this one. Its menu opens them in any space, or in a new one.

The list

  • • Status: each terminal's state as its program reported it, the program in front and its folder.
  • • Stop… and Remove: Stop… ends a terminal after a confirmation; Remove clears a finished one.

Working in a herdr-core Tab

  • • Detach and Reattach: ctrl+\ detaches; closing the pane only detaches too, and Reattach brings it back.
  • • Names, both ways: renaming a tab or moving it to another group updates its terminals' labels, and a tab label changed elsewhere renames the tab.
  • • Splits: splitting a herdr-core tab starts a new terminal beside it, and the layout is labelled so it comes back the same.
  • • Agent icon: the tab shows the agent running in front (Claude Code, Codex and the others), not the herdr-core mark.
  • • Cards and overview: a herdr-core tab gets the Finder, Git, Notes and GitHub cards of the repository it works in, and the space overview counts its processes, CPU and memory.

Machines

Each machine herdr-core has added shows with its state and its hc version.

  • • Add: on a host of your ~/.ssh/config, or Add by address…, runs hc machine add in a terminal window: when the host has no hc, hc asks there whether to copy this Mac's.
  • • Update: shows only when a machine runs another hc than this Mac.
  • • Rename, Forget and Log in: are in its menu. Its terminals keep running through all of them.

Worktrees

In the Worktrees window (⇧⌘B) a worktree opens as herdr-core: new terminals in its folder, labelled like the tab they were asked from and placed under it in the sidebar. See Worktrees.

Agent Status (OSC 7501)

Nexion's terminal answers the Program Status Protocol (OSC 7501): a program such as Claude Code (2.1.295 and later) reports whether it is working, waiting for you or done. Nexion uses that report wherever an agent's own hooks do not reach (herdr-core, SSH, agents without hooks): it shows the working line, and a "waiting for you" notification once. Hooks still come first where they exist. The program's text is never shown.

From the Command Line and the Phone

nexion herdr panes --provider herdr-core lists the Nexion panes showing herdr-core terminals, with their agent and its state; agents read the same through MCP (herdr_panes). nexion git worktree-add --open herdrCore makes a worktree and opens it as herdr-core terminals. The paired phone shows herdr-core tabs with their tag. See herdr Commands.

Safety

Nexion never installs, updates, restarts or stops herdr-core on its own: machines change only from your clicks in the Sessions window, through hc machine, and whatever asks a question runs where you answer it. It talks to the core's socket in your private state folder only, and a new terminal is started with hc run, which starts the core the way herdr does if it is not running. Anyone who can reach that socket can run commands as you, which is herdr-core's own model: keep it private.