환경 설정

Herdr는 설정 파일 없이 작동합니다. 사용자 정의 키, 테마, 사이드바 레이아웃, 알림 또는 고급 동작을 원할 때 하나를 추가하세요.

Config 참조에는 유형, 기본값 및 허용되는 값과 함께 모든 설정 및 키 설정이 나열되어 있습니다. 이 페이지에서는 참조 행보다 더 많은 설명이 필요한 설정, 일반적인 레시피 및 구성 구조를 다룹니다.

Herdr는 다음에서 구성을 읽습니다.

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

herdr --help을 실행하여 시스템의 해결된 구성 경로를 확인하세요.

전체 기본 구성을 출력합니다.

herdr --default-config

완전한 시작점을 원한다면 구성으로 저장하세요.

herdr --default-config > ~/.config/herdr/config.toml

구성 값이 유효하지 않은 경우 Herdr는 안전한 기본값으로 돌아가 시작 경고를 표시합니다.

Herdr는 onboarding이 누락되었거나 true인 경우 첫 실행 설정을 표시합니다. 온보딩을 계속하면 onboarding = false이 기록되고 통합 탭에서 설정이 열립니다. 설정 후 해당 흐름을 건너뛰려면 onboarding = false를 설정하세요.

onboarding = false

config.toml을 편집한 후 실행 중인 서버를 다시 로드합니다.

herdr server reload-config

Herdr에서 글로벌 메뉴를 열고 reload config을 선택할 수도 있습니다.

다시 로드는 패널을 다시 시작하지 않고도 대부분의 UI 설정을 적용합니다. 시작 전용 설정은 여전히 ​​다시 시작해야 합니다.

테마, 사이드바 레이아웃, 복사 동작 및 기타 프레젠테이션 설정은 SSH 시스템을 볼 때를 포함하여 클라이언트의 로컬 구성에서 가져옵니다. 패널 기본값, 작업 트리, 통합 및 사용자 정의 명령은 패널이 실행되는 서버에 속합니다. UI의 reload config 작업은 클라이언트의 로컬 설정과 선택한 서버의 구성을 모두 다시 로드합니다. 로컬 키 설정도 다시 로드됩니다. --remote-keybindings server은 대신 선택한 서버의 키 설정을 사용합니다.

연결된 클라이언트가 없으면 서버는 레이아웃 및 새로 생성된 패널에 120×40 가상 터미널을 사용합니다. 다음을 사용하여 헤드리스 오케스트레이션에 대한 대체를 변경합니다.

[server]
headless_cols = 160
headless_rows = 50

하나의 클라이언트가 연결되면 모든 탭이 해당 크기를 따릅니다. 클라이언트가 여러 개인 경우 표시된 각 탭은 가장 최근에 집중하거나 선택하거나 상호작용한 클라이언트를 따릅니다. 하나의 클라이언트를 제외한 모든 탭이 분리되면 모든 탭이 즉시 나머지 클라이언트의 크기로 돌아갑니다. 클라이언트가 남아 있지 않으면 기존 패널 PTY는 마지막 크기를 유지하고 새로운 헤드리스 레이아웃은 구성된 폴백을 사용합니다.

새로 생성된 대화형 패널에 대해 Herdr가 사용하는 실행 파일을 설정합니다.

[terminal]
default_shell = "nu"

설정되지 않거나 비어 있으면 Herdr는 Unix에서 $SHELL을 사용한 다음 /bin/sh을 사용합니다. Windows에서는 PATH을 확인할 때 pwsh.exe(PowerShell 7)를 사용하고 그렇지 않은 경우 받은 편지함 powershell.exe(Windows PowerShell 5.1)을 사용합니다. 이는 쉘 명령줄이 아닌 실행 파일 이름이나 경로입니다. 기존 패널은 다시 만들어질 때까지 현재 셸을 유지합니다. 사용자 정의 명령 키 설정 문자열은 Unix에서 패널 명령의 경우 /bin/sh -c, 분리된 명령의 경우 /bin/sh -lc을 통해 실행됩니다. Windows에서는 cmd.exe /d /c을 통해 실행됩니다.

Herdr가 새로 생성된 대화형 패널 셸을 시작하는 방법을 설정합니다.

[terminal]
shell_mode = "auto"

shell_mode = "auto"은 macOS에서 로그인 셸을 시작하므로 /usr/libexec/path_helper 및 Homebrew 셸 초기화와 같은 로그인 전용 PATH 설정이 새 패널에서 실행됩니다. 다른 플랫폼에서는 기존의 비로그인 셸 동작을 유지합니다. 로그인 쉘 시작을 강제하려면 "login"를 사용하고, 로그인하지 않은 시작을 강제하려면 "non_login"을 사용하십시오. 명령 패널, 분리된 사용자 정의 명령 키 설정 및 명시적 argv 실행은 기존 명령 실행 경로를 유지합니다.

새 패널, 탭 및 작업 공간에 대한 작업 디렉터리 정책을 설정합니다.

[terminal]
new_cwd = "follow"

new_cwd = "follow"은 기본 동작을 유지하고 소스 패널 또는 작업 공간을 상속합니다. 소스 작업 공간이 없으면 Herdr는 $HOME에서 시작됩니다. 항상 $HOME에서 시작하려면 "home"를 사용하고, Herdr의 프로세스 디렉터리를 사용하려면 "current"를 사용하거나 "~/Projects"와 같은 고정 경로를 사용하세요. CLI 또는 소켓 API의 명시적 --cwd 값이 여전히 우선 적용됩니다.

Herdr가 사이드바에서 생성된 Git 작업 트리 체크아웃에 사용하는 루트 디렉터리를 설정합니다.

[worktrees]
directory = "~/.herdr/worktrees"

Herdr는 <directory>/<repo>/<branch-slug> 아래에 결제를 생성합니다. 형제 스타일 체크아웃의 경우 이를 ~/Projects/herdr-worktrees과 같은 디렉터리로 설정합니다. 앱이 구성을 적용하면 상대 값이 절대 경로로 확인됩니다.

작업 트리 작업은 Git 작업 공간 행에서 사용할 수 있습니다. New worktree이 결제를 생성합니다. 입력한 브랜치가 존재하면 기존 로컬 브랜치를 체크아웃합니다. 그렇지 않으면 분기가 생성됩니다. 그런 다음 결제를 새로운 Herdr 작업 공간으로 열고 이를 소스 작업 공간 아래에 그룹화합니다. Open worktree...은 해당 저장소에 대한 기존 Git 작업 트리 체크아웃을 나열합니다. 이미 열려 있는 체크아웃을 선택하면 해당 체크아웃에 초점이 맞춰지고, 닫힌 체크아웃을 선택하면 동일한 그룹에서 열립니다.

그룹화된 작업 트리는 여전히 일반 Herdr 작업 공간처럼 작동합니다. 집중할 수 있고, 이름을 바꾸고, 닫을 수 있으며, 자체 탭과 패널을 포함할 수 있습니다. 상위 행은 원래 작업 공간입니다. 상위 행을 닫으면 전체 Herdr 그룹이 닫히지만 체크아웃 폴더나 분기는 삭제되지 않습니다.

작업 트리 체크아웃을 삭제하려면 그룹화된 하위 작업 공간에서 Delete worktree checkout...을 사용하세요. Herdr는 git worktree remove을 실행하고 먼저 Git에게 안전하게 제거하도록 요청합니다. 체크아웃에서 파일이 수정되었거나 추적되지 않아 Git이 거부하는 경우 Herdr는 강제 제거를 실행하기 전에 다시 묻습니다. 지점은 삭제되지 않습니다.

원격 연결은 임시 연결 유지 및 지원되는 경우 기본적으로 연결 재사용을 통해 SSH 연결을 관리합니다.

[remote]
manage_ssh_config = true

활성화되면 herdr --remote은 사용자 및 시스템 SSH 구성을 먼저 포함하는 비공개 임시 SSH 구성을 작성한 다음 대체 ServerAliveInterval 및 ServerAliveCountMax 값을 추가합니다. 자신의 연결 유지 설정이 승리합니다. Linux 및 macOS 클라이언트는 또한 개인 연결당 OpenSSH 제어 소켓을 사용하여 첫 번째 인증된 연결을 재사용합니다. Windows OpenSSH는 그렇지 않습니다. Herdr가 생성한 구성이나 제어 소켓 없이 일반 ssh을 통해 원격 연결을 실행하려면 manage_ssh_config = false을 설정하세요.

접두어에 대한 안내 소개와 검증된 접두어 없는 설정은 키보드와 마우스을 참조하세요.

Herdr에는 tmux와 유사한 프리픽스 모드가 있습니다. 기본 프리픽스는 ctrl+b입니다. 키 설정 문자열은 명시적입니다. prefix+n은 구성된 접두어를 누른 다음 n를 누르는 것을 의미합니다. ctrl+alt+n은 직접 터미널 모드 단축키입니다.

작은 키 설정 재정의는 다음과 같습니다.

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

keys.prefix은(는) 하나 이상의 키에서 프리픽스 모드를 입력해야 하는 경우에도 배열을 허용합니다. 예를 들어 macOS와 원격 Linux 시스템 간에 하나의 구성을 공유합니다.

[keys]
prefix = ["ctrl+space", "ctrl+s"]

구성된 모든 프리픽스는 동일한 프리픽스 모드로 들어가고 모든 prefix+... 작업을 시작합니다. 첫 번째 항목은 상태 표시줄에 표시되는 기본 프리픽스입니다. prefix+?의 인앱 도움말 패널에 모든 내용이 나열되어 있습니다.

기본 키맵은 프리픽스 우선이므로 Herdr는 쉘, 편집기, tmux 또는 터미널 앱에서 입력을 훔치지 않습니다. 모든 작업과 기본 바인딩을 보려면 Config 참조에서 keys.을 검색하세요. prefix+?의 인앱 도움말 패널에는 활성 바인딩이 표시됩니다.

하나의 작업에 여러 개의 단축키가 필요한 경우 바인딩은 배열이 될 수도 있습니다.

[keys]
next_tab = ["prefix+n", "ctrl+alt+]"]

선택적 작업은 기본적으로 설정되어 있지 않습니다. 프리픽스 모드 동작을 위해 prefix+로 바인딩하거나 의도적으로 직접 단축키를 원할 때 명시적으로 수정된 코드를 사용하십시오. 예를 들어, 크기 조정 모드를 입력하지 않고 tmux 스타일의 원키 입력 패널 크기 조정:

[keys]
resize_pane_left = "ctrl+shift+alt+left"
resize_pane_down = "ctrl+shift+alt+down"
resize_pane_up = "ctrl+shift+alt+up"
resize_pane_right = "ctrl+shift+alt+right"

키 문자열은 일반 키, ctrl+a, shift+n, alt+1, cmd+k 같은 수정자 조합과 enter, tab, esc, left, right, up, down 같은 특수 키를 허용합니다. minus, comma, ampersand, plus 및 backtick와 같은 명명된 구두점도 허용됩니다. n과 같은 일반 직접 출력 가능 키는 입력을 가로채기 때문에 안전하지 않습니다. 의도적으로 직접 바인딩을 원하지 않는 한 prefix+n을 사용하십시오. navigate_workspace_* 및 navigate_pane_* 필드는 탐색 모드 전용이며 j 또는 k과 같은 일반 키를 사용할 수 있습니다. prefix+, esc, enter, tab, shift+tab, left, right 또는 수정되지 않은 1부터 9까지 사용할 수 없습니다. 왼쪽 및 오른쪽 화살표는 패널 왼쪽 및 패널 오른쪽 탐색을 위한 영구 별칭입니다. 이러한 탐색 모드 단축키는 focus_pane_down = "prefix+j"과 같은 일반 작업 바인딩과 독립적입니다. 둘 다 동일한 키를 사용하면 탐색 모드가 열려 있는 동안 탐색 모드 단축키가 우선합니다. Alt, Cmd/Super 및 수정자를 포함한 구두점은 터미널 및 tmux 설정에 따라 다릅니다.

이전 사용자 정의 키 설정이 있고 새 기본값을 원하는 경우 herdr config reset-keys을 실행하세요. Herdr는 config.toml을 백업하고, [keys] 및 [[keys.command]]을 제거하고, 다시 시작한 후 또는 herdr server reload-config 후에 내장된 v2 기본값을 사용합니다.

색인화된 키 설정은 일반 키 설정 필드에서 1..9을 사용합니다.

[keys]
switch_tab = "prefix+1..9"
switch_workspace = "prefix+shift+1..9"
focus_agent = "prefix+alt+1..9"

기존 [keys.indexed] 테이블은 호환성을 위해 계속 구문 분석되지만 새 구성에서는 명시적 작업 필드를 선호해야 합니다.

사용자 정의 명령은 동일한 키 설정 구문을 사용합니다.

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

type = "popup"은 탭 레이아웃을 변경하지 않고 세션 모달 팝업을 엽니다. 팝업은 해당 명령이 종료될 때까지 Escape를 포함한 모든 터미널 입력을 받습니다. width 및 height는 선택 사항입니다. 기본 절반 크기 팝업에서는 생략하거나, 터미널 셀에 숫자를 사용하거나, 터미널 영역의 백분율에 "80%"과 같은 문자열을 사용하세요. 크기에는 팝업 테두리가 포함되며 팝업 최소값보다 작은 값은 고정됩니다. 팝업 명령은 HERDR_PANE_ID을 수신하지 않습니다. 기본 타일 패널에 HERDR_ACTIVE_PANE_ID을 사용하십시오.

Unix 및 macOS에서 팝업 명령은 분할 또는 탭을 추가하지 않고도 임시 터미널을 제공할 수도 있습니다.

[[keys.command]]
key = "prefix+t"
type = "popup"
command = "exec \"${SHELL:-sh}\""
description = "open scratch terminal"
width = "80%"
height = "80%"

Windows에서는 대신 command = "powershell.exe -NoLogo"과 같은 쉘 명령을 사용하십시오. 팝업을 닫고 타일식 터미널 보기를 복원하려면 셸을 종료하세요.

type = "pane"은 임시 확대된 패널을 열고 명령이 종료되면 닫힙니다.

type = "shell"은 백그라운드에서 분리되어 실행됩니다.

type = "plugin_action"은 설치된 플러그인 작업 ID를 호출합니다. 작업 ID가 전역적으로 고유하지 않은 경우 정규화된 ID를 사용하세요.

[[keys.command]]
key = "prefix+l"
type = "plugin_action"
command = "example.layout.apply"
description = "apply layout"

description은 선택 사항입니다. 설정되면 기본 'custom command' 레이블 대신 키 설정 도움말 패널(prefix+?로 열림)에 나타납니다.

사용자 정의 명령은 해당 값을 사용할 수 있는 경우 HERDR_SOCKET_PATH, HERDR_BIN_PATH, HERDR_ACTIVE_WORKSPACE_ID, HERDR_ACTIVE_TAB_ID, HERDR_ACTIVE_PANE_ID 및 HERDR_ACTIVE_PANE_CWD를 수신합니다. 쉘 명령은 Herdr가 감지할 수 있을 때 초점이 맞춰진 패널의 작업 디렉터리에서 실행됩니다.

Windows에서는 사용자 정의 명령 문자열이 cmd.exe /d /c을 사용하므로 환경 변수는 %HERDR_BIN_PATH% 구문을 사용합니다. PowerShell 구문을 실행하려면 명시적으로 호출하십시오(예: powershell.exe -NoProfile -Command "...").

기본 제공 테마를 선택하세요.

[theme]
name = "catppuccin"

모든 내장 테마에 대해서는 Config 참조에서 theme.name을 검색하세요. Herdr UI 색상이 호스트 터미널의 ANSI 팔레트를 따르도록 하려면 terminal을 사용하십시오.

Unix에서 Herdr는 크기 조정 또는 SIGWINCH 후에 다시 그릴 때 호스트 터미널의 색상을 다시 읽습니다. 테마 전환기가 밝음/어두움 알림 없이 OSC를 통해 터미널 색상을 변경하는 경우 새 팔레트를 적용한 후 kill -WINCH <client-pid>을 보내세요. 서버가 아닌 연결된 Herdr 클라이언트를 대상으로 합니다. 기존 패널은 계속 실행됩니다. 직접 herdr terminal attach 세션은 팔레트 쿼리를 연결된 응용 프로그램에 남겨둡니다.

호스트 터미널이 밝은/다크 모드 변경을 보고할 때 Herdr가 자체 UI 테마를 전환하도록 하려면 테마 자동 전환을 활성화합니다.

[theme]
name = "catppuccin"
auto_switch = true
light_name = "catppuccin-latte"
dark_name = "catppuccin"

auto_switch의 기본값은 false이므로 기존 테마 구성은 수동 동작을 유지합니다. light_name 또는 dark_name이 생략되면 Herdr는 tokyo-night/tokyo-night-day 또는 gruvbox/gruvbox-light과 같이 구성된 name에 대해 일치하는 내장 형제를 사용합니다. 설정에서 수동 테마를 선택하면 auto_switch이 비활성화됩니다.

개별 색상을 재정의할 수 있습니다.

[theme.custom]
sidebar_bg = "#181825"
active_row_bg = "#1e1e2e"
selection_bg = "#313244"
panel_bg = "reset"
accent = "#a6e3a1"
green = "#a6e3a1"
blue = "#89b4fa"
red = "#f38ba8"
yellow = "#f9e2af"

sidebar_bg은 선택적으로 데스크탑 사이드바에 자체 배경을 제공합니다. 생략하면 사이드바는 호스트 터미널 배경을 유지합니다. active_row_bg은 구분 기호나 스크롤 막대 트랙에 영향을 주지 않고 활성 공간과 초점이 ​​맞춰진 에이전트 행 배경을 변경합니다. selection_bg는 사이드바의 탐색 모드 커서 행 배경을 변경합니다.

색상 값은 16진수, 명명된 색상, rgb(r,g,b) 또는 reset, default, none 및 transparent와 같은 별칭 재설정을 허용합니다.

auto_switch이 활성화되면 공유 사용자 정의 색상 위에 선택적으로 밝은 하위 테이블과 어두운 하위 테이블 레이어가 표시됩니다.

[theme.custom]
accent = "#89b4fa"


[theme.custom.light]
panel_bg = "#eff1f5"
text = "#4c4f69"


[theme.custom.dark]
panel_bg = "#1e1e2e"
text = "#cdd6f4"

활성 팔레트는 내장 테마, [theme.custom], [theme.custom.light] 또는 [theme.custom.dark] 순서로 적용됩니다. 모드 하위 테이블을 생략하면 기존 공유 재정의 동작이 유지됩니다.

사이드바는 주요 Herdr 대시보드입니다. 크기 조정, 축소 모드, 에이전트 패널 순서, 마우스 동작, 패널 테두리 및 기타 프레젠테이션 설정을 보려면 Config 참조에서 ui.를 검색하세요.

ui.pane_borders은 "auto"(기본값, 분할 패널에만 테두리), "always"(단일 패널 프레임 지정) 또는 "off"을 허용합니다. 단일 패널 프레임에는 모든 가장자리가 외부 가장자리이므로 ui.pane_outer_borders = true가 필요합니다. 기존 부울 값은 계속 유효합니다. true는 "auto"을 의미하고 false은 "off"을 의미합니다.

터미널 패널 아래에 데스크탑 탭 행을 배치하려면 [ui] 아래에 tab_bar_position = "bottom"을 설정하십시오. 접두어, 탐색, 복사 및 크기 조정 모드 표시줄은 활성화된 동안 하단 탭 행을 일시적으로 대체합니다. 기본값은 "top"입니다.

탭 행의 오른쪽 가장자리에 순서가 지정된 tmux 스타일 상태 영역을 구성합니다.

[ui]
tab_bar_right = [
  { type = "zoom" },
  { type = "hostname" },
  { type = "datetime", format = "%H:%M" },
  { type = "text", text = "prod" },
  { type = "command", command = "~/.config/herdr/status.sh", interval_seconds = 5, timeout_seconds = 2 },
]
tab_bar_right_separator = " · "

상태 영역은 기본적으로 비어 있습니다. 활성 탭이 확대된 동안 고정된 ZOOM 알약을 표시하려면 zoom을 추가하세요. 기존 탭별 Z 마커는 독립적으로 유지됩니다. hostname, datetime 및 command는 Herdr 서버에서 확인되므로 herdr --remote은 원격 시스템의 값을 표시합니다. 날짜/시간 항목은 strftime 형식을 사용합니다. %z 및 %s와 같이 UTC 오프셋 또는 Unix 타임스탬프가 필요한 지시어는 값이 서버 로컬 벽시계 시간이기 때문에 거부됩니다.

명령 항목은 렌더링을 차단하거나 이전 실행을 겹치지 않고 즉시 실행된 다음 interval_seconds에서 실행됩니다. 간격은 1~31,536,000초이고 시간 초과는 1~3,600초일 수 있습니다. Herdr는 성공적인 출력의 마지막 줄을 사용하고, 스타일을 해석하는 대신 ESC 프리픽스가 붙은 터미널 제어 시퀀스를 제거하고, 실패, 빈 출력 또는 timeout_seconds 후 항목을 지우고, 사용자 정의 명령 키 설정과 동일한 활성 작업 공간, 탭, 패널, 소켓, 바이너리 및 작업 디렉터리 컨텍스트를 제공합니다. 명령은 Linux, macOS 및 Windows에서 지원되며 Linux 및 macOS에서는 /bin/sh -lc를 사용하고 Windows에서는 cmd.exe /d /c을 사용합니다.

구분 기호는 보이는 항목 사이에만 나타납니다. 직접 연결하려면 tab_bar_right_separator = ""을 설정하세요. 좁은 탭 행에서는 전체 상태 영역이 탭과 해당 컨트롤로 표시됩니다.

Herdr는 패널에서 터미널을 에뮬레이트하므로 패널 안에 작성된 OSC 0/OSC 2 제목은 Herdr에서 중지됩니다. Herdr는 실행되는 터미널에 자체 제목을 작성하며, 이는 패널 관리자와 터미널 탭 표시줄에 표시됩니다.

[ui]
window_title = "{hostname}: {workspace}"

토큰은 {hostname}, {workspace}, {tab}, {pane}(포커스된 패널의 수동 이름) 및 {terminal_title}(스피너 프레임이 제거된 포커스된 패널의 자체 터미널 제목)입니다. 리터럴 중괄호에는 {{ 및 }}을 작성합니다. 값이 없는 토큰은 빈 것으로 렌더링됩니다.

제목은 Herdr 서버에서 렌더링되므로 {hostname}은 herdr --remote로 연결하거나 SSH를 통해 herdr을 실행할 때를 포함하여 패널이 실행되는 컴퓨터의 이름을 지정합니다. 외부 터미널 제목을 그대로 두려면 window_title = ""을 설정하십시오.

client.window_title.set은 client.window_title.clear이 제목을 돌려줄 때까지 구성된 제목을 재정의합니다.

에이전트 상태는 기본적으로 작은 색상의 점을 사용합니다. 차단됨, 작업 중, 완료됨, 유휴 및 알 수 없는 상태를 모양과 색상으로 구분하려면 설정에서 고유한 기호을 선택하거나 다음을 구성하세요.

[ui]
status_indicators = "symbols"

기호는 정적이므로 이 옵션은 스피너 애니메이션을 활성화하지 않습니다.

확장된 데스크톱 사이드바는 rows의 각 내부 배열을 한 줄로 렌더링합니다. 완전한 기본 레이아웃은 다음과 같습니다.

[ui.sidebar.agents]
row_gap = 0
rows = [
  ["state_icon", "machine", "workspace", "tab"],
  ["agent"],
]


[ui.sidebar.spaces]
row_gap = 0
rows = [
  ["state_icon", "workspace"],
  ["branch", "git_status"],
]

에이전트 행은 다음과 같은 기본 제공 토큰을 허용합니다.

• state_icon — 에이전트의 의미 상태에 대한 색상 아이콘입니다.
• state_text — idle, working, blocked, done 또는 unknown(있는 경우 보고된 디스플레이 라벨 포함)
• machine — 클라이언트에 여러 컴퓨터가 있는 경우의 컴퓨터 레이블입니다. 단일 로컬 기기에서는 생략되었습니다.
• workspace — 작업 공간 이름.
• tab — 사용 가능한 경우 탭 이름입니다.
• pane — 사용 가능한 경우 패널 이름입니다.
• agent — 감지되거나 보고된 에이전트 표시 이름입니다.
• terminal_title — 안전 정규화 후 최신 OSC 0/2 터미널 제목.
• terminal_title_stripped — 하나의 인식된 선행 활동 또는 스피너 문자 모양과 그 뒤의 공백이 제거된 터미널 제목입니다.
• $name — name이라는 사용자 정의 패널 메타데이터.

공간 행은 다음과 같은 내장 토큰을 허용합니다.

• state_icon — 스페이스의 롤업된 에이전트 상태에 대한 색상 아이콘입니다.
• state_text — 롤업된 에이전트 상태에 대한 텍스트입니다.
• workspace — 작업 공간 이름.
• branch — 가능한 경우 Git 브랜치.
• git_status — 0이 아닌 경우 Git의 앞뒤가 계산됩니다.
• $name — name이라는 사용자 정의 작업 공간 메타데이터.

토큰은 구성된 순서대로 렌더링됩니다. Herdr는 일반적으로 인접한 값을 ·로 구분하고 state_icon 뒤에 단일 공백을 사용합니다. 누락된 값과 해당 구분 기호가 사라집니다. 해당 토큰에 값이 없으면 행이 사라집니다. 기존 사용자 정의 행은 변경되지 않은 상태로 유지되므로 사용자 정의 다중 시스템 레이아웃에서 시스템 ID를 원하는 경우 명시적으로 machine를 추가하십시오. 각 레이아웃은 최대 16개의 행을 포함할 수 있으며 각 행에는 최대 16개의 토큰이 포함될 수 있습니다.

토큰 항목은 인라인 스타일 테이블일 수도 있습니다.

[ui.sidebar.agents]
rows = [
  ["state_icon", { token = "workspace", bold = false }, "tab"],
  [{ token = "$summary", fg = "#89b4fa", bold = true, dim = false }],
]

fg은(는) 엄격한 #RGB 또는 #RRGGBB을 허용합니다. bold 및 dim은 부울을 허용합니다. 생략된 필드는 토큰의 상황별 스타일을 유지합니다. 명시적인 false는 해당 수정자를 제거합니다. 스타일 지정은 한 번 발생하는 경우에만 적용되므로 동일한 토큰이 다른 행이나 에이전트 재정의에서는 다르게 보일 수 있습니다. 전경 재정의는 해당 항목 내부의 모든 의미론적 전경을 대체합니다. 예를 들어 git_status 스타일이 지정된 앞뒤 개수는 기본 녹색과 빨간색 대신 한 가지 색상을 사용합니다. 토큰 스타일은 구분 기호나 행 배경을 변경하지 않습니다.

텍스트 값 토큰은 최대 16개의 rules 주문도 허용합니다. 각 규칙에는 정확히 하나의 조건(equals, contains, starts_with, gt 또는 lt)과 선택적 fg, bold 및 dim 재정의가 포함됩니다.

[ui.sidebar.agents]
rows = [
  ["state_icon", "workspace", "tab"],
  [{ token = "machine", fg = "#fff", rules = [{ equals = "Local", fg = "#f55" }, { equals = "Fedora", ignore_case = true, fg = "#51a2da" }] }, "agent"],
  [{ token = "$load", fg = "#fff", rules = [{ gt = 80, fg = "#f55", bold = true }, { gt = 50, fg = "#fc0" }] }],
]

첫 번째 일치 규칙이 승리합니다. 지정된 스타일 필드는 발생의 기본값을 재정의합니다. 지정되지 않은 필드는 이를 상속합니다. 일치하는 규칙이 없으면 기본값이 유지됩니다. 일치에서는 표시가 잘리기 전에 전체 토큰 값을 사용합니다. 일치하는 토큰과 해당 구분 기호를 제거하려면 규칙에 hide = true을 설정하세요. 남은 토큰이 없는 행도 사라집니다. 예를 들어 { token = "machine", fg = "#61afef", rules = [{ equals = "Local", hide = true }] }은 레이블이 정확히 Local인 경우 기기 토큰을 숨깁니다. 이는 연결 유형이 아닌 레이블을 비교합니다. hide = false을 사용하거나 생략하면 토큰이 계속 표시됩니다. 재정의가 없는 규칙은 여전히 ​​일치를 중지하고 기본값을 유지합니다.

equals, contains 및 starts_with는 문자열을 사용하며 대소문자를 구분합니다. ASCII 대소문자를 구분하지 않고 일치하려면 ignore_case = true을 추가하세요. ASCII가 아닌 문자는 대소문자를 구분합니다. 빈 문자열은 일반 문자열 일치를 따릅니다. 빈 equals는 빈 값에만 일치하고, 빈 contains 또는 starts_with은 현재 값과 일치합니다.

gt 및 lt은 유한한 숫자 임계값을 사용하여 크거나 작거나 같지 않은 것을 엄격하게 비교합니다. 값은 유한 숫자로 완전히 구문 분석되어야 합니다. 소수 및 지수 형식은 작동하지만 공백, 단위, NaN 및 무한대는 일치하지 않습니다. ignore_case은 숫자 규칙에서 허용되지 않습니다. 비교에서는 정확한 큰 정수 연산이 아닌 부동 소수점 숫자를 사용합니다.

규칙은 에이전트 행, rows_by_agent 재정의 및 공백 행의 텍스트 값 기본 제공 및 사용자 정의 $name 토큰과 함께 작동합니다. 사용자 정의 토큰은 보고된 값과 일치합니다. $load 보고 "90"은 위에서 빨간색과 굵은 글씨를 선택하고, "60"는 노란색을 선택하고 "90%"는 흰색을 유지합니다. 보고되지 않은 토큰은 여전히 ​​사라집니다. state_icon 및 복합 git_status은 규칙이 아닌 고정 스타일만 허용합니다. 구성을 로드할 때 알 수 없는 조건과 잘못된 형식의 규칙이 거부됩니다. 정규식, 퍼지 일치 및 스크립트는 지원되지 않습니다.

row_gap은 Agent 및 Space 패널에 대해 독립적으로 항목 사이의 빈 터미널 행을 제어합니다. 기본값은 항목을 함께 묶는 0입니다. 이전 간격을 복원하려면 1로 설정하세요. rows에 선언된 내용 줄 사이에 공백을 추가하지 않습니다. 연속적으로 들여쓰기된 작업 트리 하위 항목은 하나의 Space 그룹으로 묶인 상태로 유지됩니다.

rows_by_agent에서 알려진 에이전트에 대한 전체 에이전트 레이아웃을 재정의합니다.

[ui.sidebar.agents]
rows = [
  ["state_icon", "agent", "state_text"],
  ["workspace", "tab"],
]


[ui.sidebar.agents.rows_by_agent]
claude = [
  ["state_icon", "agent", "state_text"],
  ["terminal_title_stripped"],
  ["workspace", "tab"],
]

재정의는 rows을 대체합니다. 그것은 그것을 확장하지 않습니다. 재정의 키는 claude, codex, pi 등 대소문자를 구분하는 정식 에이전트 ID입니다. claude-code와 같은 감지 별칭은 허용되지 않습니다. 사용자 정의 보고 에이전트를 포함하여 재정의가 없는 에이전트는 rows를 사용합니다.

사용자 정의 $name 토큰은 리터럴 텍스트가 아닌 동적 값입니다. 레이아웃에 토큰을 추가한 다음 스크립트나 플러그인에서 해당 값을 보고합니다.

[ui.sidebar.agents]
rows = [
  ["state_icon", "agent", "$model"],
  ["$summary"],
  ["workspace", "tab"],
]

herdr pane report-metadata <pane_id> \
  --source my-agent-hook \
  --token model=opus \
  --token summary="reviewing authentication"

사용자 정의 Space 토큰에 대해 동일한 방식으로 herdr workspace report-metadata을 사용합니다. 보고되지 않은 사용자 정의 토큰은 사라집니다.

메타데이터 보고자는 값만 제공합니다. 스타일은 로컬 사이드바 구성으로 유지됩니다. 제한, 지우기, 순서 지정 및 만료에 대해서는 CLI 참조: 보고서 메타데이터을 참조하세요.

사이드바 행 설정은 확장된 데스크탑 사이드바에만 영향을 미칩니다. 축소된 보기와 모바일 보기는 간결한 레이아웃을 유지합니다.

Herdr는 백그라운드 에이전트가 완료되거나 입력이 필요할 때 알림을 보낼 수 있습니다.

[ui.toast]
delivery = "herdr"
delay_seconds = 1


[ui.toast.herdr]
position = "bottom-right"

인앱 토스트의 경우 herdr, SSH를 통해서도 작동하는 외부 터미널 알림의 경우 terminal, 로컬 OS 알림 서비스의 경우 system, 팝업을 비활성화하려면 off을 선택합니다. Herdr는 활성 탭에 대한 팝업을 억제합니다. 위치, 지연 동작 및 클립보드 피드백 설정을 보려면 Config 참조에서 ui.toast를 검색하세요.

macOS에서 system은(는) 먼저 terminal-notifier를 시도하고 사용할 수 없거나 실패하면 /usr/bin/osascript(으)로 대체됩니다. 대체는 알림 센터에서 스크립트 편집기로 나타나며 호스팅 터미널을 활성화할 수 없습니다. brew install terminal-notifier와 함께 terminal-notifier을 설치합니다. 지원되고 감지된 단말기의 경우 알림을 클릭하면 단말기 앱이 활성화될 수 있습니다. 또는 지원되는 외부 터미널이 알림을 소유하도록 하려면 terminal을 선택합니다.

소리 알림은 로컬 Herdr 클라이언트를 통해 재생됩니다. 사용자 정의 사운드는 mp3 파일이어야 합니다. Herdr는 설정 파일 디렉터리의 상대 경로를 확인합니다.

[ui.sound]
path = "sounds/notification.mp3"
done_path = "sounds/done.mp3"
request_path = "sounds/request.mp3"

path은 모든 소리 알림에 대해 하나의 소리를 설정합니다. done_path 및 request_path는 완료되고 입력이 필요한 사운드만 무시합니다.

에이전트별 사운드 재정의는 default, on 또는 off를 허용합니다. claude, codex, devin, droid 등 감지된 에이전트 라벨을 키로 사용하세요. Droid는 기본적으로 음소거되어 있습니다.

[ui.sound.agents]
droid = "off"
claude = "on"

스크롤백 제한, 중첩 실행 및 기타 고급 또는 실험적 설정에 대해서는 Config 참조을 검색하세요. 패널 화면 기록을 활성화하기 전에 세션 상태 및 복원을 참조하세요. 해당 가이드에서는 패널 내용 저장의 보안 장단점을 설명합니다.

응용 프로그램과 플러그인은 패널 터미널 출력에 표시되는 표준 Kitty 그래픽 프로토콜을 통해 통합됩니다. Herdr는 기본적으로 호환되는 외부 터미널에서 이러한 이미지를 렌더링합니다. 외부 소켓 패널 오버레이 API가 제거되었습니다. 대체 소켓 이미지 API가 없습니다.

팝업, 메뉴 및 알림은 해당 영역 주변의 이미지를 자릅니다. 각 이미지의 나머지 부분은 계속 표시되며 오버레이가 닫히면 가려진 부분이 다시 나타납니다. 대화 상자 배경으로 인해 이미지가 어두워지지 않습니다.

Herdr는 애플리케이션 변경이나 환경 전환 없이 적합한 파일 전송을 자동으로 선택합니다. 로컬 Unix Ghostty 클라이언트에서는 이미지 데이터를 터미널 출력으로 인코딩하는 대신 임시 파일을 통해 보낼 수 있습니다. 작은 파일 소비 프로브가 먼저 지원을 확인합니다. 다른 터미널, SSH 실행 클라이언트 및 중첩된 멀티플렉서는 이 마지막 홉 최적화를 위해 인라인 출력을 유지합니다.

적합한 로컬 클라이언트의 경우 기본 RGBA 이미지는 픽셀 바이트가 아닌 Herdr 소유 스냅샷에 대한 경로로 서버에서 클라이언트로 이동합니다. 지원되지 않는 클라이언트 및 실패한 전송은 인라인 전달로 대체됩니다. 원격 서버 경로는 로컬 터미널로 전달되지 않습니다. Herdr는 이미지 배치, 클리핑 및 가시성을 제어합니다.

Linux에서 전체 파일, 비압축 RGBA 업로드는 Herdr가 픽셀을 읽기 전에 쓰기 시 복사 스냅샷을 사용할 수 있습니다. 이를 위해서는 Herdr의 개인 /var/tmp 저장소에 복제하기 위한 파일 시스템 지원이 필요합니다. 지원되지 않는 파일 시스템, 임시 파일 업로드, 공유 메모리 및 기타 형식은 일반 로더를 사용합니다. 스냅샷은 각각 16MiB, 총 64MiB로 제한됩니다. 애니메이션 및 지원되지 않는 클라이언트는 필요할 때 픽셀을 읽습니다. Herdr는 이미지를 수락한 후 변경 가능한 생산자 경로에 의존하지 않습니다.

PNG 업로드는 전체 디코딩 및 유효성 검사를 유지합니다. Herdr는 손상된 이미지 검증을 외부 터미널로 연기하지 않습니다.

Kitty 그래픽 렌더링을 비활성화하려면:

[terminal]
kitty_graphics = false

레거시 experimental.kitty_graphics 설정은 기존 구성에 계속 적용됩니다. 둘 다 설정된 경우 terminal.kitty_graphics이 우선 적용됩니다.

이 설정을 변경하려면 영향을 받는 Herdr 서버를 다시 시작하거나 클라이언트를 다시 연결해야 합니다. 원격 세션에서는 서버의 설정이 Kitty 그래픽 구문 분석을 제어하고, 로컬 클라이언트의 설정은 외부 터미널로의 출력을 제어합니다.

Herdr는 기본적으로 서버가 다시 시작된 후 지원되는 에이전트 대화를 재개합니다.

[session]
resume_agents_on_restore = true
startup_per_agent_delay_ms = 100

자동 복원은 시작 경합을 줄이기 위해 기본적으로 100밀리초 간격으로 한 번에 하나의 에이전트를 시작합니다. 첫 번째 적격 에이전트이 즉시 시작됩니다. 간격을 비활성화하려면 startup_per_agent_delay_ms = 0을 설정하십시오. 수동 실행 및 명시적인 터미널 연결은 영향을 받지 않습니다. 변경 사항을 적용하려면 Herdr 서버를 다시 시작하세요.

공식 통합의 유효한 기본 세션 참조가 있는 창만 재개할 수 있습니다. 다른 패널은 일반 셸로 복원됩니다. 지원되는 에이전트 및 지속성 동작은 세션 상태 및 복원을 참조하세요.

macOS에서 하드웨어 커서를 숨기는 AI 에이전트 TUI는 기본 입력 방법 후보 패널이 포커스가 있는 패널을 따르지 못하게 할 수 있습니다. 다음을 사용하여 해당 패널에 대한 커서 앵커를 표시합니다.

[experimental]
reveal_hidden_cursor_for_cjk_ime = true
cjk_ime_agents = ["claude", "pi", "codex"]

cjk_ime_agents을 제한하면 관련 없는 응용 프로그램에 추가 하드웨어 커서가 표시되는 것을 방지할 수 있습니다. 허용되는 에이전트 이름과 커서 모양을 보려면 Config 참조에서 이러한 키를 검색하세요.

macOS 및 Windows에서 Herdr는 프리픽스 명령 및 프리픽스 실행 모드가 활성화되어 있는 동안 일시적으로 ASCII 지원 입력 소스로 전환할 수 있습니다.

[experimental]
switch_ascii_input_source_in_prefix = true

macOS에서는 현재 ASCII 지원 키보드 레이아웃으로 전환됩니다. Windows에서는 IME를 영어(ASCII) 입력으로 전환합니다. Herdr는 터미널 입력으로 돌아가거나 텍스트 필드를 입력할 때 이전 입력 소스를 복원합니다. 이 설정은 다른 플랫폼에는 영향을 미치지 않습니다.

로그는 시작 경고, 통합 상태 또는 소켓 API 동작을 진단할 때 유용합니다.

공통 로그 파일:

~/.config/herdr/herdr.log
~/.config/herdr/herdr-client.log
~/.config/herdr/herdr-server.log

로그는 자동으로 회전됩니다. 문제를 보고할 때 현재 로그와 순환된 형제 항목을 포함합니다.