Configuration Reference

All configuration files, settings, and customization options.

Config File Locations

File	Location	Purpose
`keymap.toml`	`~/.config/clhorde/keymap.toml`	Keybindings, settings, quick prompts
`templates.toml`	`~/.config/clhorde/templates.toml`	Prompt templates
`history`	`~/.local/share/clhorde/history`	Prompt history (auto-managed)
`prompts/`	`~/.local/share/clhorde/prompts/`	Per-prompt persistence (UUID v7 JSON)
`daemon.sock`	`~/.local/share/clhorde/daemon.sock`	Daemon Unix domain socket
`daemon.pid`	`~/.local/share/clhorde/daemon.pid`	Daemon PID file (stale detection)

Config paths respect $XDG_CONFIG_HOME and $XDG_DATA_HOME. The config file is optional—everything has sensible defaults.

Keybindings (`keymap.toml`)

Only specify what you want to change. Missing keys silently use defaults.

# ~/.config/clhorde/keymap.toml
# Only override what you want — missing keys keep defaults.

[normal]
quit = ["q"]
insert = ["i"]
select_next = ["j", "Down"]
select_prev = ["k", "Up"]
view_output = ["Enter"]
interact = ["s"]
increase_workers = ["+", "="]
decrease_workers = ["-"]
toggle_mode = ["m"]
retry = ["r"]
resume = ["R"]
move_up = ["K"]
move_down = ["J"]
search = ["/"]
shrink_list = ["h"]
grow_list = ["l"]
show_help = ["?"]
toggle_select = ["Space"]
select_all_visible = ["V"]
visual_select = ["v"]
delete_selected = ["d"]
kill_selected = ["x"]

[insert]
cancel = ["Esc"]
submit = ["Enter"]
accept_suggestion = ["Tab"]
next_suggestion = ["Down"]
prev_suggestion = ["Up"]

[view]
back = ["Esc", "q"]
scroll_down = ["j", "Down"]
scroll_up = ["k", "Up"]
interact = ["s"]
toggle_autoscroll = ["f"]
kill_worker = ["x"]
export = ["w"]
toggle_split = ["t"]

[interact]
back = ["Esc"]
send = ["Enter"]

[filter]
confirm = ["Enter"]
cancel = ["Esc"]

Key Name Reference

Key Name	Description
`"a"` – `"z"`, `"A"` – `"Z"`	Single letter characters
`"0"` – `"9"`	Digit characters
`"+"`, `"-"`, `"/"`, `"?"`, etc.	Symbol characters
`"Enter"`	Enter / Return key
`"Esc"`	Escape key
`"Tab"`	Tab key
`"Space"`	Space bar
`"Backspace"`	Backspace key
`"Up"`, `"Down"`, `"Left"`, `"Right"`	Arrow keys

Each action takes an array of keys. When any of the listed keys is pressed, the action fires.

Settings

Add a [settings] section to keymap.toml:

[settings]
max_saved_prompts = 100    # Maximum prompt files to keep (default: 100)
worktree_cleanup = "manual" # "manual" (default) or "auto"
list_ratio = 40            # Prompt list width percentage (10-90, default: 40)

Setting	Type	Default	Description
`max_saved_prompts`	integer	100	Maximum number of prompt files to keep. Oldest completed prompts are pruned first.
`worktree_cleanup`	string	`"manual"`	`"manual"` keeps worktrees after completion. `"auto"` removes them when workers finish.
`list_ratio`	integer	40	Percentage width of the prompt list panel (10–90). The output panel gets the rest.

Templates (`templates.toml`)

Define reusable prompt snippets in a separate file:

# ~/.config/clhorde/templates.toml

[templates]
review = "Review this code for bugs and security issues:"
explain = "Explain what this code does:"
test = "Write unit tests for this code:"
refactor = "Refactor this code to be more idiomatic:"

In insert mode, type :review and press Tab to expand. Combine with a directory prefix:

/path/to/project: :reviewTab
→ /path/to/project: Review this code for bugs and security issues:

Quick Prompts

Add a [quick_prompts] section to keymap.toml:

[quick_prompts]
g = "let's go"
c = "continue"
y = "yes"
n = "no"

These keys send the associated message instantly when viewing a running prompt. Keys must not conflict with view mode bindings (j, k, q, s, f, x, w, t, Esc, arrows). View bindings take priority on conflict.

Config CLI Management

$ clhorde-cli config path           # Print config file path
$ clhorde-cli config init           # Create config with all defaults
$ clhorde-cli config init --force   # Overwrite existing config
$ clhorde-cli config edit           # Open config in $EDITOR (or vi)

config init creates a fully populated keymap.toml with all default values, making it easy to see every available option.