Herdr configuration

Herdr의 config.toml 위치, key, keybinding, theme, notification, reload와 검증 방법.

• Herdr는 config file 없이도 실행되며, 필요할 때 TOML 파일을 추가한다.
• Linux/macOS 기본 경로는 ~/.config/herdr/config.toml, Windows는 %APPDATA%\herdr\config.toml이다.
• 전체 기본값은 herdr –default-config로 현재 binary에서 직접 생성하는 것이 가장 안전하다.
• 잘못된 값은 safe default로 fallback되며 startup warning이 표시된다.

Linux / macOS: ~/.config/herdr/config.toml
Windows:         %APPDATA%\herdr\config.toml

• HERDR_CONFIG_PATH는 기본 config file 경로를 override한다.
• herdr –help는 현재 실행 환경에서 resolve된 config 경로를 표시한다.
• custom sound 같은 상대 경로는 config file directory를 기준으로 해석된다.

# 검토용으로 전체 기본 설정 출력
herdr --default-config
 
# Linux / macOS 기본 경로에 저장
mkdir -p ~/.config/herdr
herdr --default-config > ~/.config/herdr/config.toml

onboarding = false
 
[terminal]
default_shell = "zsh"
shell_mode = "auto"
new_cwd = "follow"
 
[worktrees]
directory = "~/.herdr/worktrees"
 
[theme]
name = "catppuccin"
 
[ui.toast]
delivery = "herdr"
delay_seconds = 1

• onboarding = false: first-run setup을 다시 표시하지 않는다.
• terminal.default_shell: 새 interactive pane의 shell executable을 지정한다. command line이 아닌 executable 이름 또는 경로다.
• terminal.shell_mode: auto, login, non_login 중 shell startup mode를 선택한다.
• terminal.new_cwd: follow, home, current 또는 고정 경로를 사용한다. CLI의 명시적 –cwd가 우선한다.
• worktrees.directory: Herdr가 만든 Git worktree checkout의 root directory다.

[keys]
prefix = "ctrl+b"
goto = "prefix+g"
new_tab = "prefix+c"
next_tab = "prefix+n"
previous_tab = "prefix+p"
focus_pane_left = "prefix+h"
split_horizontal = "prefix+minus"

• 기본 keymap은 shell, editor, tmux 입력을 가로채지 않도록 prefix-first 방식이다.
• key string은 ctrl+a, alt+1, prefix+n, enter, esc, minus 같은 형식을 사용한다.
• 일반 printable key를 prefix 없이 binding하면 평상시 typing을 가로챌 수 있다.
• 하나의 action에 여러 shortcut이 필요하면 next_tab = ["prefix+n", "ctrl+alt+]"]처럼 array를 사용한다.
• active binding은 Herdr 안에서 prefix+?로 확인한다.

[[keys.command]]
key = "prefix+alt+g"
type = "popup"
command = "lazygit"
description = "run lazygit"
width = "80%"
height = "80%"

• type은 popup, pane, shell, plugin_action을 사용할 수 있다.
• Unix custom pane command는 /bin/sh -c, detached command는 /bin/sh -lc를 사용한다.
• Windows command string은 cmd.exe /d /c로 실행되므로 PowerShell syntax가 필요하면 powershell.exe를 명시한다.

[theme]
name = "catppuccin"
auto_switch = true
light_name = "catppuccin-latte"
dark_name = "catppuccin"
 
[ui.sidebar.agents]
row_gap = 0
rows = [
  ["state_icon", "workspace", "tab"],
  ["agent"],
]

• theme.name은 built-in theme를 선택한다. host terminal ANSI palette를 따르려면 terminal을 사용한다.
• theme.auto_switch는 terminal이 보고한 light/dark appearance에 따라 Herdr theme을 전환한다.
• sidebar rows는 표시할 token과 줄 구성을 정의한다. 지원 token과 제한은 공식 Config reference에서 확인한다.

[ui.toast]
delivery = "herdr"
delay_seconds = 1
 
[ui.toast.herdr]
position = "bottom-right"
 
[ui.sound]
path = "sounds/notification.mp3"

• delivery는 herdr, terminal, system, off를 사용할 수 있다.
• custom sound는 MP3 file을 사용하며 상대 경로는 config file directory 기준이다.
• HERDR_DISABLE_SOUND를 설정하면 sound notification을 비활성화한다.

[remote]
manage_ssh_config = true
 
[session]
resume_agents_on_restore = true

• remote.manage_ssh_config = true이면 Herdr가 temporary private SSH config와 connection reuse socket을 관리한다. 사용자의 ~/.ssh/config와 system config가 먼저 포함된다.
• session.resume_agents_on_restore는 공식 integration이 유효한 native session reference를 제공한 pane에만 적용된다.

1. HERDR_CONFIG_PATH로 지정한 config file이 기본 platform 경로를 대체한다.
2. 선택된 config file의 TOML 설정을 읽는다.
3. CLI/socket API의 명시적 값이 해당 동작에서 config보다 우선한다. 예: workspace create –cwd PATH.
4. invalid value는 safe default로 fallback되고 warning을 출력한다.

# 현재 binary가 제공하는 전체 기본값과 비교
herdr --default-config
 
# 실행 중인 server에 변경 적용
herdr server reload-config
 
# server와 client 상태 확인
herdr status
 
# keybinding section backup 후 초기화
herdr config reset-keys

• reload는 대부분의 UI setting에 적용되지만 startup-only setting은 restart가 필요하다.
• config reset-keys는 config.toml을 backup하고 [keys]와 keys.command를 제거한 뒤 built-in keymap을 사용한다.
• log는 보통 ~/.config/herdr/herdr.log, herdr-client.log, herdr-server.log에서 확인한다.

• config file에 API token, password, private key를 직접 저장하지 않는다.
• pane screen history나 log에는 terminal output과 민감한 command가 남을 수 있다. persistence 설정을 켜기 전에 저장 범위와 file permission을 확인한다.
• HERDR_LOG의 debug level은 운영 중 필요한 기간에만 사용하고 공유하기 전에 token, path, host 정보를 redact한다.
• remote attach는 기존 SSH trust와 key policy를 따른다. host key 검증을 우회하지 않는다.

• 변경이 반영되지 않으면 HERDR_CONFIG_PATH와 herdr –help의 resolve된 경로가 같은지 확인한다.
• startup warning이 나오면 해당 key를 공식 Config reference와 herdr –default-config에서 검색한다.
• 새 pane의 shell이나 PATH가 예상과 다르면 terminal.default_shell과 terminal.shell_mode를 점검하고 pane을 새로 만든다.
• key 입력이 가로채지면 prefix 없는 printable binding을 제거하고 herdr config reset-keys로 기본값을 복원한다.
• remote attach가 불안정하면 먼저 일반 ssh TARGET을 검증하고 필요할 때만 remote.manage_ssh_config = false로 비교한다.

• Herdr CLI
• Herdr configuration
• Herdr Config reference
• Herdr keyboard guide

• codex:: 2026-07-27 Added config location, TOML authoring, terminal, worktree, keybinding, theme, notification, remote, validation, and security guidance.