border-collie

a plugin for herdr

border-collie

Keeps the herd in order: recent spaces on top, pins for the ones you live in, tabs and agents named after their work, and a picker to jump between agents.

herdr plugin install Yggdrasill501/border-collie

Source on GitHub Read the docs

v0.6.0 · MIT · Linux and macOS · written in Rust

before

spaces

  1. 1~
  2. 2meety
  3. 3daily-log
  4. 4meety-clone

tabs

  • 1
  • 2
  • 3

agents

  • w9:p1
  • w6:p3
after

spaces

  1. 1meety-clonewhere you are
  2. 2meetywhere you were
  3. 3~
  4. 4daily-log

tabs

  • PR 457
  • Linear tasks needing at…
  • meety

agents

  • pr-457
  • linear-tasks-needing-attention

An illustration of the example in the README, not a screenshot of herdr.

What it does

  • Recent spaces on top

    Switch to a space, stay a second, and it moves to the top. Without pins, space 1 is always the current one and space 2 the one you came from, so jumping back is always the same key. Or set sort_by = "status" to put spaces with a blocked agent first.

  • Tabs named after their agents

    A tab takes the terminal title of its most recently active agent, or the directory name when the title is generic.

  • Agents named after their work

    Each agent gets a unique name such as pr-457, which herdr accepts anywhere it takes an agent: herdr agent focus pr-457.

  • Pinned spaces

    Pin the spaces you live in to fixed top slots, the way harpoon pins files. Everything else stays sorted by recent use below them.

  • Agent picker

    One key opens a list of every agent, most recently active first. Press a digit to jump straight there.

  • Next agent that needs you

    One key jumps to an agent that is blocked on a question or has finished, without opening anything.

Your names win
Tabs and agents you rename yourself are never touched.
No background process
herdr runs a small Rust binary from its event hooks; a naming run typically takes a few milliseconds.

Install

Requirements

  • herdr 0.9 or newer, on Linux or macOS
  • Rust 1.89 or newer (cargo), to build the plugin on install

Installation

shell 
herdr plugin install Yggdrasill501/border-collie

That is all: border-collie starts working on the next space switch or agent update. To apply it to everything immediately:

shell 
herdr plugin action invoke border-collie.name

To update, run the install command again. To remove it, first run herdr plugin action invoke border-collie.reset to put tab numbers back and clear agent names, then:

shell 
herdr plugin uninstall border-collie

Configuration

border-collie works without configuration. To change a setting, create config.toml in the plugin's config directory, which herdr plugin config-dir border-collie prints:

config.toml 
sort_spaces   = true   # move the focused space to the top
sort_by       = "recent"  # or "status": spaces needing attention first
name_tabs     = true   # name tabs after their agents
name_agents   = true   # name agents after their work
dwell_ms      = 1000   # how long a space must stay focused before it moves
tab_label_max = 24     # longest tab label, in characters

Every line is optional; the values above are the defaults. Changes apply on the next hook run, with no reload. With sort_by = "status", unpinned spaces are grouped by their most urgent agent (blocked, done, working, idle), most recently focused first within each group.

Suggested keybindings

Sorted spaces pair well with number keys. In herdr's own config.toml:

herdr config.toml 
[keys]
switch_workspace = "prefix+1..9"        # prefix+2 is always the previous space
switch_tab       = "prefix+shift+1..9"

Pin or unpin the current space:

herdr config.toml 
[[keys.command]]
key = "prefix+shift+p"
type = "plugin_action"
command = "border-collie.toggle-pin"
description = "pin or unpin this space"

Open the agent picker:

herdr config.toml 
[[keys.command]]
key = "prefix+a"
type = "plugin_action"
command = "border-collie.pick-agent"
description = "jump to an agent"

Jump to the next agent that is blocked or has finished:

herdr config.toml 
[[keys.command]]
key = "prefix+shift+a"
type = "plugin_action"
command = "border-collie.next-attention"
description = "next agent needing attention"

To rename everything on demand:

herdr config.toml 
[[keys.command]]
key = "prefix+shift+c"
type = "plugin_action"
command = "border-collie.name"
description = "name tabs and agents"

How names are chosen

SourceExample
Tab Title of the tab's most recently active agent, cut to tab_label_max Linear tasks needing at…
Agent The same title in herdr's name alphabet (a-z, 0-9, -), at most 32 characters linear-tasks-needing-attention

When a title is empty or generic (Claude Code), the directory name is used instead. Two agents that would get the same name become meety and meety-2.

border-collie only renames a tab that still has herdr's numeric label, or an agent that has no name, or one whose current name border-collie set. Rename something yourself and border-collie leaves it alone from then on. To hand a tab back, rename it to a number.

How it works and troubleshooting are covered in the README.