Herdr on this machine

Use these local sources when answering questions about Herdr configuration, commands, or behavior. Prefer direct evidence over remembered defaults.

Evidence order

1. For the user’s effective configuration, read managed file $DOTFILES/herdr-cfg/config.toml. The file is intentionally self-documenting: comments preserve the meaning of available settings, and uncommented values are deliberate overrides. It is linked to runtime path ~/.config/herdr/config.toml.
2. For defaults and command syntax supported by the installed binary, run command herdr --default-config, command herdr --help, or the relevant nonmutating command-group help.
3. For implementation details and fuller documentation, inspect source checkout $DOTFILES/herdr.
4. Reconcile versions before applying source-checkout findings to the installed binary. Draft source and documentation may describe unreleased behavior.

Reading files and printing help or the default config does not require HERDR_ENV=1. Commands that inspect or control a live Herdr session do require a Herdr-managed pane, as described in SKILL.md.

Local paths

• Managed config: $DOTFILES/herdr-cfg/config.toml
• Local config notes: $DOTFILES/herdr-cfg/README.md
• Herdr source checkout: $DOTFILES/herdr
• Config data model and defaults: $DOTFILES/herdr/src/config/model.rs
• Commented default-config template: $DOTFILES/herdr/src/main.rs
• Unreleased English documentation: $DOTFILES/herdr/docs/next/website/src/content/docs

For guided config documentation, begin with file configuration.mdx. For the generated key catalog, use file config-reference.mdx together with the config model and command herdr --default-config.

Configuration changes

When the user requests a local configuration change, edit managed file $DOTFILES/herdr-cfg/config.toml, preserve its explanatory comment style, and validate it with:

HERDR_CONFIG_PATH="$DOTFILES/herdr-cfg/config.toml" \
  herdr config check

Reloading the running server with command herdr server reload-config is a live session-control action. Perform the HERDR_ENV=1 check first.

Flatten agent tabs

For requests such as “flatten my tabs” or “one agent per tab”, use the dotfiles command instead of selecting panes and destination tabs manually. Run it inside Herdr, after the environment check in SKILL.md:

just --justfile "$DOTFILES/justfile" herdr-flatten
just --justfile "$DOTFILES/justfile" herdr-flatten --run

The first command previews moves in the calling pane’s live workspace. The second applies them. When the user requests flattening, run the preview, inspect the plan, and apply it within that authorization. A request to inspect or preview the layout authorizes only the first command.

The command keeps one recognized agent per existing tab, preferring the focused agent, and moves each extra agent directly into a new tab with pane move --new-tab --no-focus. These moves preserve running processes and avoid creating placeholder shells. Repeating the command after flattening plans no further moves.

Non-agent panes stay where they are and appear in the report. Tabs containing shells may therefore still have multiple panes. Do not close those panes as part of flattening. If the user requests exactly one pane per tab, explain which non-agent panes remain before arranging any further changes.

The command refreshes the layout before each move and stops on a failed move or a changed pane identity. Earlier successful moves remain applied. Inspect the layout and rerun the preview before retrying; the command replans from live state. It does not lock the layout against concurrent changes.

Implementation: $DOTFILES/herdr-cfg/flatten.ts. Run its tests with:

cd "$DOTFILES"
bun test herdr-cfg/flatten.test.ts

Installed fork and Codex

The vendored v0.9.3 fork keeps zero-based tab shortcuts and labels. Build it with command just herdr-install from directory $DOTFILES. Command herdr update replaces the custom binary with an upstream release. Check command herdr status server separately from command herdr --version, since installing a binary does not replace a running server.

The managed Codex defaults set configuration key tui.alternate_screen to "never". Codex reads this setting when its process starts and renders inline so Herdr copy mode can scroll its output. Inline rendering works independently of daemon mode.

Herdr’s managed starts and restores, and the Zsh function codex for manual launches, pass flag --no-daemon to keep session hooks tied to the launching pane. See file $DOTFILES/herdr-cfg/README.md for applying these settings and performing a server handoff.

Existing Codex processes survive live handoff with their original settings. A shared Codex daemon can also retain another pane’s inherited caller context. When investigating that case, compare environment variable CODEX_THREAD_ID with live API field agent_session.value before choosing a pane; do not infer identity from cwd or recency alone. Use the verified explicit pane ID rather than a stale --current context.

Do not edit the herdr source checkout merely to answer a configuration or behavior question. Modify that checkout only when the user explicitly requests Herdr source or documentation work.