Herdr

Herdr은(는) 무엇을 하나요?

Herdr는 터미널을 워크스페이스, 탭, 패널로 구성하고, 패널 내에서 실행 중인 코딩 에이전트를 인식하며, herdr CLI를 통해 현재 세션을 노출합니다.

제어 명령을 내리기 전에, 이 에이전트가 Herdr 관리 패널 내에서 실행 중인지 확인하십시오:

test "${HERDR_ENV:-}" = 1

확인에 실패하면 Herdr 내에서 실행 중이 아니라고 말하고 중지하십시오. Herdr 외부에서 포커스된 Herdr 세션을 검사하거나 제어하지 마십시오.

확인이 통과되면 PATH에 있는 herdr 바이너리가 현재 세션과 통신합니다. 이를 사용하여 주변 작업을 검사하고, 터미널 레이아웃을 생성하고, 에이전트와 명령을 시작하고, 출력을 읽고, 상태 변경을 기다리십시오.

현재 CLI 익히기

설치된 바이너리가 명령 구문의 권위자입니다. 다음으로 시작하십시오:

herdr --help

그런 다음 하위 명령 없이 해당 명령 그룹을 실행하여 관련 명령 그룹을 출력하십시오:

herdr agent
herdr pane
herdr workspace
herdr tab
herdr worktree
herdr terminal
herdr notification
herdr integration
herdr session

발견 목적으로 herdr를 단독으로 실행하지 마십시오. TUI를 실행하거나 연결합니다. 인수를 생략하여 변경을 유발하는 중첩 명령을 시험하지 마십시오. herdr workspace create와 같은 명령은 기본값으로 유효하며 실행됩니다.

대부분의 제어 명령은 JSON을 반환합니다. 예측하는 대신 해당 응답에서 식별자와 상태를 읽으십시오.

레이아웃, 패널 및 에이전트 이해하기

작업에 맞는 기본 요소를 선택하십시오:

• 워크스페이스, 탭 및 패널 토폴로지는 터미널 위치를 구성합니다.
• 패널 명령은 원시 터미널, 셸, 테스트, 서버, 입력 및 출력을 제어합니다.
• 에이전트 명령은 현재 패널을 차지하고 있는 인식된 코딩 에이전트를 제어합니다.

패널은 에이전트를 포함하지 않아도 존재합니다. agent start는 기존의 사용 가능한 셸 패널이 필요하며 레이아웃을 생성, 분할 또는 이동하지 않습니다. 일반 프로세스에는 패널 명령을 사용하십시오. Herdr가 에이전트 신원을 확인하거나 idle, working, blocked, done 및 unknown 수명 주기 상태를 해석해야 할 때는 에이전트 명령을 사용하십시오.

에이전트 명령은 고유한 활성 에이전트 이름 또는 현재 해당 에이전트를 호스팅하는 패널 ID를 허용합니다. 터미널 ID나 에이전트 종류 레이블만으로는 허용하지 않습니다. 이름은 [a-z][a-z0-9_-]{0,31}과 일치해야 하며 활성 에이전트 간에 고유해야 합니다. 이름은 현재 패널 점유자를 따르며 해당 에이전트가 종료, 해제 또는 교체되면 지워집니다.

idle은 에이전트가 입력을 받을 준비가 되었고 해당 탭이 포커스된 Herdr UI에서 보였음을 의미합니다. done은 보이지 않는 백그라운드 작업이 완료된 후의 동일한 기본 유휴 상태입니다. 탭에 포커스를 맞추거나 포커스 명령으로 패널 또는 에이전트를 대상으로 지정하면 표시된 것으로 표시됩니다. CLI 읽기는 표시된 것으로 표시하지 않습니다. blocked는 Herdr가 승인 또는 질문 UI를 인식했음을 의미합니다. unknown은 에이전트가 존재하지만 Herdr가 자신 있게 분류할 수 없음을 의미합니다. 완료를 증명하지 않습니다.

ID 및 호출자 컨텍스트 사용하기

공개 ID는 불투명한 안정적인 핸들입니다:

• 워크스페이스: w1
• 탭: w1:t1
• 패널: w1:p1

닫힌 탭과 패널 ID는 재사용되지 않습니다. 다른 워크스페이스로 이동된 패널은 새 워크스페이스로 한정된 패널 ID를 받습니다. pane move 후에는 .result.move_result.pane.pane_id 또는 활성 에이전트 이름을 계속 사용하십시오. 이전 값은 .result.move_result.previous_pane_id로 보고됩니다. 이동된 프로세스의 상속된 호출자 컨텍스트만 해당 이전 ID를 계속 확인할 수 있으므로 일반적인 에이전트 대상으로 사용하지 마십시오.

Herdr는 호출자의 컨텍스트를 각 관리 패널에 주입합니다:

printf '%s\n' "$HERDR_WORKSPACE_ID" "$HERDR_TAB_ID" "$HERDR_PANE_ID"

패널 명령이 호출 패널을 대상으로 해야 할 때는 --current를 선호하십시오. 대상을 생략하면 UI 포커스 패널을 사용할 수 있으며, 이는 사용자 또는 다른 클라이언트에 속할 수 있습니다.

다음으로 라이브 상태를 발견하십시오:

herdr workspace list
herdr tab list --workspace "$HERDR_WORKSPACE_ID"
herdr pane current --current
herdr pane list --workspace "$HERDR_WORKSPACE_ID"
herdr agent list

생성 응답은 다음에 사용할 ID를 노출합니다. workspace create는 .result.workspace, .result.tab 및 .result.root_pane을 반환합니다. tab create는 .result.tab 및 .result.root_pane을 반환합니다. pane split은 새 패널을 .result.pane으로 반환합니다.

에이전트 시작 및 조정하기

기본적으로 현재 탭의 형제 패널과 현재 작업 디렉토리를 사용하십시오. 사용자가 명시적으로 해당 토폴로지나 위치를 요청하지 않는 한 워크스페이스, 탭, 워크트리 또는 다른 cwd를 생성하지 마십시오.

사용자가 요청한 방향을 존중하십시오. 그렇지 않으면 호출자 패널을 검사하십시오:

herdr pane layout --pane "$HERDR_PANE_ID"

넓은 패널은 오른쪽으로, 좁거나 높은 패널은 아래로 분할하십시오. 사용할 수 없을 정도로 좁은 열이나 짧은 행을 만드는 반복적인 동일 방향 분할을 피하십시오. 사용자의 포커스를 호출 패널에 유지하고 호출자의 작업 디렉토리를 명시적으로 보존하십시오:

herdr pane split --current --direction right --cwd "$PWD" --no-focus

적절할 때 right를 down으로 바꾸십시오. .result.pane.pane_id에서 새 패널 ID를 읽으십시오.

사용 가능한 셸 패널은 대화형 프롬프트 상태여야 하며, 셸 자체가 포그라운드에 있고 포그라운드 명령, 편집기 또는 에이전트가 실행 중이 아니어야 합니다. 해당 패널에서 유용한 고유 이름을 가진 지원되는 에이전트를 시작하십시오:

herdr agent start reviewer --kind codex --pane <반환된-패널-id>

사용자가 요청한 종류를 사용하십시오. herdr agent를 실행하여 설치된 종류 목록과 옵션을 확인하십시오. 네이티브 에이전트 인수는 -- 뒤에 전달하십시오:

herdr agent start reviewer --kind codex --pane <반환된-패널-id> -- <에이전트-인수...>

agent start는 Herdr가 동일한 패널에서 예상 에이전트를 감지하고 대화형 입력을 받을 준비가 되었다고 간주한 후에만 반환됩니다. 기본 30초 시작 시간 제한이 있습니다.

에이전트 표면을 통해 작업을 제출하십시오:

herdr agent prompt reviewer "현재 diff를 검토하고 실행 가능한 결과만 보고하십시오." --wait --timeout 120000

agent prompt는 패널의 라이브 bracketed-paste 모드를 존중하면서 텍스트와 인코딩된 Enter를 원자적으로 제출합니다. 일반적인 에이전트 작업의 경우 --wait로 충분합니다. 첫 번째 안정된 idle, done 또는 blocked 상태를 기다립니다. 이러한 기본값을 --until로 반복하지 마십시오.

비작업 상태에서 전송된 프롬프트는 5초 이내에 관찰 가능한 수명 주기 변경을 생성해야 합니다. 그렇지 않으면 Herdr는 무기한 기다리는 대신 agent_prompt_stalled를 반환합니다. 이 대기는 수명 주기 상태를 추적하며 개별 턴을 추적하지 않습니다. 에이전트가 이미 작업 중인 경우 활성 턴의 완료가 이를 충족할 수 있습니다.

--until은 이미 실행 중인 에이전트가 입력을 요청하기를 기다리는 등 상태별 워크플로우에만 사용하십시오:

herdr agent wait reviewer --until blocked --timeout 120000

--until 없이 단독 agent wait는 agent prompt --wait와 동일한 안정된 상태 기본값을 사용합니다.

대화형 에이전트 UI 제어에는 논리적 키를 사용하십시오:

herdr agent send-keys reviewer esc
herdr agent send-keys reviewer ctrl+c

Herdr는 바이트를 쓰기 전에 모든 키의 유효성을 검사합니다. 확인된 에이전트를 통해 결과를 읽으십시오:

herdr agent get reviewer
herdr agent read reviewer --source recent-unwrapped --lines 120

대기가 실패하거나 blocked를 반환하면, 보낼 입력을 결정하기 전에 agent get 및 agent read를 검사하십시오. 원시 터미널 제어가 의도적인 경우에만 패널 표면을 사용하십시오.

다른 패널에서 일반 명령 실행하기

동일한 지오메트리 규칙으로 형제 패널을 생성하고, 호출자의 작업 디렉토리를 보존하며, 사용자 포커스를 변경하지 않은 상태로 유지하십시오:

herdr pane split --current --direction right --cwd "$PWD" --no-focus

.result.pane.pane_id에서 새 패널 ID를 읽은 다음 명령을 실행하고 검사하십시오:

herdr pane run <반환된-패널-id> "just test"
herdr pane wait-output <반환된-패널-id> --match "test result" --timeout 120000
herdr pane read <반환된-패널-id> --source recent-unwrapped --lines 120

pane run은 명령 텍스트와 Enter를 원자적으로 보냅니다. pane wait-output은 선택한 스냅샷을 즉시 검색하므로 이미 존재하는 출력도 일치할 수 있습니다. 리터럴 부분 문자열에는 --match <text>를, Rust 정규 표현식에는 --regex <패턴>을 사용하십시오. --timeout을 생략하면 무기한 대기할 수 있습니다.

작업에 맞는 읽기 소스를 사용하십시오:

• visible: 현재 렌더링된 뷰포트.
• recent: 최근 렌더링된 출력(소프트 래핑 포함).
• recent-unwrapped: 소프트 래핑이 결합된 최근 출력. 로그 및 트랜스크립트에 선호합니다.
• detection: 에이전트 감지에 사용되는 일반 텍스트 하단 버퍼 스냅샷.

색상 및 터미널 스타일이 증거인 경우 --format ansi를 사용하십시오. 그렇지 않으면 텍스트를 사용하십시오.

--lines는 Herdr에게 패널의 사용 가능한 화면 및 호스트 스크롤백에서 더 많은 행을 요청합니다. 증가시켜도 완료된 응답의 더 많은 부분이 나타나지 않으면 패널이 터미널의 대체 화면에서 에이전트를 실행 중일 가능성이 높습니다. 대체 화면을 벗어나는 행은 Herdr의 호스트 스크롤백으로 들어가지 않으므로 더 많은 줄 수로 복구할 수 없습니다.

해당 읽기가 실패한 후, 에이전트에게 임시 디렉토리에 완전한 응답을 Markdown으로 작성하고 파일 경로만 회신한 다음 파일을 직접 읽도록 요청하십시오. 이는 최후의 수단으로만 사용하십시오. 초기 프롬프트에서 파일 출력을 요청하지 마십시오.

안전 및 조정 규칙

• 사용자가 컨텍스트 전환을 요청하지 않는 한 백그라운드 작업에는 --no-focus를 사용하십시오.
• --current, 명시적 패널 ID 또는 고유한 에이전트 이름을 사용하십시오. 다른 클라이언트의 포커스 패널에 의존하지 마십시오.
• JSON 응답에서 ID를 구문 분석하십시오. 사이드바 순서나 예제에서 파생하지 마십시오.
• 사용자가 명시적으로 요청하지 않는 한 생성하지 않은 워크스페이스, 탭, 패널 또는 세션을 닫지 마십시오.
• 사용자가 명시적으로 서버와 해당 패널 프로세스를 중지하려는 의도가 없는 한 활성 세션에서 herdr server stop을 실행하지 마십시오.
• 기본 Herdr 프로세스를 종료하지 마십시오. 격리된 서버가 필요한 실험에는 명명된 테스트 세션을 사용하십시오.
• CLI 서버 오류는 종료 상태 1과 함께 stderr의 JSON입니다. CLI 구문 오류는 종료 상태 2로 종료됩니다.

로컬 관용구

위의 HERDR_ENV=1 게이트는 패널 내에서 현재 세션을 제어하는 것에 적용됩니다. 구성 편집, 플러그인 설치, 에지언트 감지 디버깅, 소켓/CLI 주변 자동화 구축과 같은 호스트 수준 작업은 모든 터미널에서 합법적입니다. 해당 작업에 대해서는 references/local-idioms.md를 읽으십시오: 알림 전달 설정, 에이전트 감지 유지 관리, Claude Code 훅의 사이드바 메타데이터, 이벤트 구독 패턴, 워크트리 흐름 및 플러그인 작성 노트.