Configuration

All herdr-plus configuration lives under ~/.config/herdr-plus/, honoring $XDG_CONFIG_HOME. There’s no central config file — everything is a file per entry.

Directory layout

~/.config/herdr-plus/
  projects/          # one *.toml per project (control mode)
    options-cafe.toml
    bevio.toml
    ...
  quick-actions/     # one *.toml per action (quick-actions mode)
    github.toml
    google.toml
    ...

• projects/ holds your project templates for control mode. Each *.toml defines one project. This directory starts empty — control mode’s onboarding screen explains how to add your first one.
• quick-actions/ holds your quick actions. Each *.toml defines one action. This directory is seeded with editable examples the first time you run the mode.

The per-mode subdirectory name is the mode’s slug (quick-actions), so future modes get their own folder. Projects hang directly off the config root (not under a mode slug) because they’re a first-class concept.

The file-per-entry model

In both directories the rule is the same: add a file to add an entry, delete a file to remove it. File names don’t matter — only the contents. Entries are sorted by their name in the UI.

Important: A malformed or invalid file fails the whole load for that directory, with an error naming the offending file. This is deliberate: a typo surfaces loudly instead of an entry silently going missing.

Seeding behavior

• quick-actions/ is seeded with bundled examples only when the directory doesn’t yet exist. Once it exists, herdr-plus leaves it alone — so deleting an example won’t make it reappear.
• projects/ is never seeded. An empty directory is meaningful: it triggers control mode’s onboarding empty-state. herdr-plus only ever creates the empty folder for you to drop files into.

Per-project (per-repo) overrides

A repo can ship its own quick actions. Add a .herdr-plus/ directory at the repo root that mirrors the global layout, with one *.toml per action in its quick-actions/ subdirectory:

your-repo/
  .herdr-plus/
    quick-actions/
      make-build.toml
      make-test.toml

When you launch the quick-actions picker from inside that repo, these actions appear grouped under a Project heading above your Global ones. The directory is read-only and never auto-created — it’s read only when a repo actually provides it. See Quick Actions for the full behavior.

XDG_CONFIG_HOME behavior

herdr-plus follows the XDG convention:

• If XDG_CONFIG_HOME is set, config lives in $XDG_CONFIG_HOME/herdr-plus/.
• Otherwise it falls back to ~/.config/herdr-plus/, so the location is the same on macOS and Linux.

Note: herdr’s own config (the config.toml that herdr-plus install writes to) follows the same rule under herdr/ rather than herdr-plus/. See Keybindings.

See also

• Control Mode & Projects — the project file format.
• Actions Reference — the action file format.
• Examples & Cookbook — ready-to-copy files.