If you're just getting started

Make it easy to use

Too busy to read their docs? No problem. You can either:

1. Pass this agent-guide.md to your coding agent, and it will teach you how to set up, use, and troubleshoot Herdr. Or ask it to set up Herdr for you.

2. Install the /herdr agent skill so your agents can drive Herdr themselves: split panes, run commands, and check on neighboring agents.

View all your agents by default

Herdr's main features revolve around helping you command your team of agents. This is easier when you can see them all at once. How I do it:

• Use a single Herdr server, the default one that starts when you run herdr in the terminal.
• Keep the sidebar expanded by default. (Bonus: it pushes your panes toward the center of the screen, which is much more comfortable for your neck. On a wide monitor, this saves you from constantly turning your head to the left.)

Install agent integrations

I feel like this should have been a required step when installing Herdr. Having the Herdr agent integrations unlocks Herdr's real power:

1. It automatically reopens and resumes active agent conversations across reboots, instead of dropping you into an empty shell.
2. For some agents (like Pi and OMP), it reports their states (working, blocked, or idle) directly, instead of Herdr guessing from the screen.

Follow their Integrations guide to set yours up.

Better keyboard shortcuts

A Herdr keyboard shortcut typically involves two motions. For example, to create a new Herdr tab, you'd press the prefix of ctrl+b in one stroke, then press c:

This ctrl+b+<key> pattern was inspired directly by tmux, the OG terminal multiplexer. But this is a bad default. Among tmux users (myself included), ctrl+b was widely considered awkward to press, and it was very common to change this prefix to ctrl+a.

I think we should go one step further: use no prefix at all. Most of us are used to keyboard shortcuts that involve a single motion, like cmd+t (I'm on macOS) to create a new tab in Google Chrome. And we can do that here!

Isn't that so much better?

To bind cmd+t to creating a new Herdr tab:

# ~/.config/herdr/config.toml

[keys]
new_tab = "cmd+t" # previously prefix+c

For any custom keys you set, make sure to disable the conflicting keys set by your terminal emulator. I use Ghostty, so I disabled its built-in cmd+t:

# ~/.config/ghostty/config

keybind = cmd+t=unbind

Here are my full custom Herdr keys as of this writing. Take what you like, and don't forget to unbind conflicting keys. Notice how I don't completely replace the prefix shortcuts, as they're great for less common actions and avoiding conflicts with other apps. I also set my prefix to ctrl+space, which is even easier to press than ctrl+a.

# ~/.config/herdr/config.toml

[keys]

# General
prefix = "ctrl+space"
settings = "cmd+,"
detach = "prefix+d"
reload_config = "prefix+r"
goto = "cmd+g"
workspace_picker = ["prefix+w", "alt+w"]
split_vertical = ["prefix+|", "cmd+d"]
split_horizontal = ["prefix+-", "cmd+shift+d"]
zoom = ["prefix+z", "alt+z"]
resize_mode = "prefix+,"
toggle_sidebar = "cmd+shift+b"
copy_mode = "alt+enter"

# Navigation
focus_agent = "cmd+alt+1..9"
switch_tab = "cmd+1..9"
switch_workspace = "alt+1..9"
last_pane = "alt+tab"
previous_workspace = "cmd+alt+left"
next_workspace = "cmd+alt+right"

# Workspace and tab management
rename_workspace = "alt+r"
new_tab = "cmd+t"
rename_tab = "cmd+r"
close_pane = "cmd+w"

Better tab names

By default, Herdr asks you to name each new tab, which gets old fast. Turn the prompt off with prompt_new_tab_name = false, and you get plain numbers instead. It's difficult to know what's going on in a tab, especially when you have multiple tabs/agents running across different workspaces:

‎ 1 ‎‎‎‎ ‎ ‎ 2 ‎ ‎ ‎‎‎‎ 3 ‎‎‎ ‎ ‎ +

You can install a Herdr plugin like herdr-automatic-rename, a plugin that I created, to automatically name them either after their foreground process:

‎ [1] zsh ‎‎‎ ‎ ‎ [2] nvim ‎ ‎ ‎‎‎‎ [3] ssh ‎‎‎ ‎ ‎ +

Or, even more useful, after the agent session context:

‎ [1] Debug transient issue ‎ ‎ ‎ ‎‎‎ [2] Improve test suite ‎‎‎ ‎ ‎ +

This makes it much easier to quickly know what each agent is working on and prioritize the more important ones.

Make it yours by extending it

Community plugins

Herdr is highly configurable and extensible. Any aspects you don't like can likely be reconfigured or changed.

Check out their community plugins if you haven't already. There are more than 1,400 of them as I'm writing this:

• Want a code review and file viewer sidebar? Check.
• Want a kanban board in your Herdr? Check.
• Want a more integrated nvim experience? Check.

Your own plugins

It's easy to build your own plugins to solve any friction you have in Herdr.

The plugins you make can just be private. Most of mine are. (Although if you make one and think others will find it helpful, I encourage you to open source it!)

Prototyping personal software is an area where AI shines, so you can also point your agent to the docs' plugins page and let it work.

A preview of mine, for your inspo:

herdr-prompt-picker

This popup appears whenever I type "@" or "/" in Claude Code. When I type "@", this picker shows a list of files and a preview of their content. When I type "/", this picker shows a list of my available skills and a preview of their SKILL.md.

herdr-screen-picker

This popup appears via a manual keyboard shortcut. The picker shows a list of file paths or URLs that appear on the screen. Selecting a file opens it with nvim in a new Herdr tab. Selecting a URL opens it in my browser.

herdr-resource-manager

This one was inspired by Orca's Resource Manager feature. This popup shows the CPU and memory consumed by my Herdr workspaces, agents, and tabs. Useful when my laptop's fan gets loud and I want to quickly spot the culprit.

You can see the pattern. I love the Herdr popup's form factor. :)

While this plugin still works, seeing it break my setup after the 0.12 update made me curious about what's going on under the hood. Luckily, Neovim 0.12 ships almost everything built-in, so you and I can run treesitter with no plugin at all.

nvim-treesitter is a manager sitting on top of three layers: parsers, queries, and a bit of Lua to glue it all together. Let's dive in.

Parsers

A parser is a small compiled library, one per language, that turns source text into a syntax tree: lua.so, python.so, and so on. (A syntax tree, or formally a parse tree, is a data structure that represents how a program or snippet is organized.)

Neovim 0.12 only bundles support for seven languages out of the box: c, lua, markdown, markdown_inline, query, vim, and vimdoc. For any other language, you need to compile the parser yourself.

First, find the grammar repo for your desired language. This requires a quick Google search, like <lang> treesitter grammar. This "grammar" repo contains instructions and rules on how to turn a source text in that language into a syntax tree.

Next, install the tree-sitter CLI, clone the language's grammar repo, and build it. Below is JSON as an example, but the pattern is the same for any language: clone tree-sitter-<lang> and build it to <lang>.so.

git clone https://github.com/tree-sitter/tree-sitter-json
cd tree-sitter-json
tree-sitter build -o ~/.config/nvim/parser/json.so

Neovim searches for parsers as parser/{lang}.* in every directory on its runtimepath, so dropping json.so into ~/.config/nvim/parser/ is all you need to do.

Queries

Once we have the syntax tree, treesitter can run queries in order to do jobs like highlighting, folding, etc. A query is written as an S-expression pattern (sort of like regex but for the syntax tree instead of raw text) that matches the right parts of the tree for a given job.

Queries also assign matches with capture names, which are labels that look like @keyword, @string, or @comment. Neovim uses these labels to decide what should be highlighted, folded, or otherwise processed.

Queries live as .scm files under a queries/<lang>/ directory on the runtimepath, one file per job:

• queries/<lang>/highlights.scm for highlighting
• queries/<lang>/folds.scm for folding
• queries/<lang>/injections.scm for embedded languages

For the seven built-in languages, Neovim already bundles their queries along with the parsers. For anything else, drop your own into ~/.config/nvim/queries/<lang>/.

The big query corpus that nvim-treesitter shipped for hundreds of languages lives in its repo, so you can copy the ones you need into your config. Note that your file replaces the bundled queries for that language (first on runtimepath wins), so prepend ; extends to it if you mean to add to them instead.

Putting it together

Great work making it here. Let's run this to start highlighting:

vim.treesitter.start()

With no arguments, treesitter attaches the highlighter to the current buffer using the language for its filetype. It also turns off the old regex syntax highlighting. Re-enable that with vim.bo.syntax = 'ON' if some plugin still needs it.

To auto run this everywhere, put the call in a FileType autocommand:

vim.api.nvim_create_autocmd('FileType', {
  callback = function(args)
    pcall(vim.treesitter.start, args.buf)
  end,
})

The pcall swallows the error for filetypes with no parser installed. For folding, set two options:

vim.wo.foldmethod = 'expr'
vim.wo.foldexpr = 'v:lua.vim.treesitter.foldexpr()'

Unfortunately, Neovim doesn't provide indentation out of the box. To set it up, find it in the archived nvim-treesitter code, although note that it's still experimental. For most languages, I think Neovim's built-in indent rules are good enough.

When to skip the plugin

Just because you can doesn't mean you should. When going plugin-free, you give up things like :TSInstall, automatic parser updates, the giant query corpus, and textobjects like vaf to select a function. If you use those, keep the plugin for convenience. Its main branch still does this job well and now calls these same core APIs under the hood.

But by setting up treesitter yourself, you get something with no moving parts that can break: no plugin rewrite forcing a migration, the whole thing is a parser file, a few queries, and a small snippet of Lua.

Introduction

When I run Claude Code on a larger task, I often end up waiting on it while wanting to step away: coffee, a meeting, or a walk. I didn’t want to keep checking my laptop just to see whether it needed input or had finished.

Over the past month, I’ve been using a simple setup that lets me:

• keep Claude Code running on my Mac,
• attach to the same session from my phone,
• and get notified when it needs attention.

tmux new -s session_name

claude

tmux attach -t session_name

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "terminal-notifier -title \"🔔 Claude Code\" -message \"I need your input\" -sound default -activate 'com.googlecode.iterm2' && curl -d \"🔔 Claude Code: I need your input\" ntfy.sh/my-topic"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "terminal-notifier -title \"✅ Claude Code\" -message \"I'm done!\" -sound default -activate 'com.googlecode.iterm2' && curl -d \"✅ Claude Code: I'm done!\" ntfy.sh/my-topic"
          }
        ]
      }
    ]
  },
}