내 환경 × Herdr — 도입 이득과 권장 세팅

사이드바
  ● feature-a   ← blocked (승인 대기 중)
  ○ feature-b   ← working
  ◐ hotfix-c    ← done (아직 안 봄)

curl -fsSL https://herdr.dev/install.sh | sh
# 또는 brew install herdr
herdr --version

herdr integration install claude
herdr integration install opencode     # OpenCode를 최소 1회 실행한 뒤에
herdr integration status               # 버전 확인 — 네이티브 세션 복원 조건

# ~/.config/herdr/config.toml

[ui.toast]
delivery = "system"        # 데스크톱 알림. 알림 플러그인을 쓰면 "terminal"로 변경

[session]
# resume_agents_on_restore = true   # 기본값. 프로젝트를 자주 옮기면 워크스페이스가
                                    # 과하게 쌓일 수 있으니 그때 false 고려

herdr --default-config > /tmp/herdr-default.toml   # 전체 옵션 확인용
herdr server reload-config                          # 재시작 없이 적용

# (a) 자리를 떠도 폰으로 — 크로스 플랫폼
herdr plugin install cobanov/herdr-ntfysh
cp .env.example "$(herdr plugin config-dir cobanov.herdr-ntfysh)/.env"
# HERDR_NTFY_SERVER, HERDR_NTFY_TOPIC 설정
herdr plugin action invoke cobanov.herdr-ntfysh.test

# (b) macOS라면 — 클릭 시 해당 pane으로 점프
herdr plugin install yankewei/herdr-focus-notify
# HERDR_FOCUS_NOTIFY_ACTIVATE_APP=wezterm

# 1) 워크트리 하나에서 OpenCode + Claude Code를 각각 pane에 띄우기
# 2) 사이드바에 두 상태가 뜨는지 확인
herdr agent list

# 3) 상태가 이상하면 이유 확인
herdr agent explain <target> --json

herdr session attach test      # 별도 세션에서 실험
# ... 에이전트 띄우고 대화 몇 번
herdr server stop <세션 지정>   # 정확한 플래그는 herdr server stop --help 확인
herdr session attach test      # 대화 맥락을 들고 살아나면 통합 성공

session: default
├── workspace: feature-a      (워크트리 A)
├── workspace: feature-b      (워크트리 B)
└── workspace: main           (메인 체크아웃)

workspace: feature-a
├── tab: main       ← 오케스트레이터 에이전트 1개 + diff pane
├── tab: workers    ← 서브에이전트 전용
└── tab: edit       ← nvim

npx skills add herdrdev/herdr --skill herdr -g

herdr로 오른쪽에 pane 열고 codex 띄워서 현재 diff 리뷰시켜줘

# Herdr orchestration — house rules

## 역할 분리 (재귀 방지)
HERDR_ROLE=worker 이면 herdr 제어 명령을 일절 사용하지 않는다.
pane/tab/workspace를 만들지 않고, 다른 에이전트를 시작하지 않는다.
작업 결과만 보고한다.

## 토폴로지
- 오케스트레이터는 main 탭에만 존재. 워커를 main 탭에 띄우지 않는다.
- 워커는 label="workers" 탭에만 생성. 없으면 만든다.
- 탭/pane ID는 항상 list로 조회한다. 하드코딩 금지.
- 워커 pane은 최대 3개. 그 이상은 좁아서 못 쓴다.

## 결과 교환 (컨텍스트 절약 + alternate screen 회피)
워커 프롬프트 말미에 항상 추가:
  "전체 결과를 $HANDOFF_DIR/<name>.md 에 쓰고, 응답은 파일 경로 한 줄만."
오케스트레이터는 파일을 읽는다. agent read는 진단 용도로만.

## 권한
자동 승인은 아래를 모두 만족할 때만:
  - 읽기 전용 (ls, cat, git diff, git log, rg)
  - 워크트리 경로 밖을 건드리지 않음
그 외 전부 사용자 호출:
  herdr notification show "승인 필요: <name>" \
    --body "$(herdr agent read <name> --source detection --lines 5)" \
    --sound request
git push / rm / 파일 삭제 / 네트워크 쓰기는 예외 없이 사용자.

## 금지
- 자기가 만들지 않은 pane/tab/workspace 닫기
- herdr server stop
- 메인 Herdr 프로세스 kill

herdr agent start impl     --kind opencode --pane "$p1"   # CC가 OpenCode를
herdr agent start reviewer --kind claude   --pane "$p2"   # OpenCode가 CC를

test "${HERDR_ENV:-}" = 1

split=$(herdr pane split --current --direction right --cwd "$PWD" --no-focus)
p=$(printf '%s\n' "$split" | jq -r '.result.pane.pane_id')

herdr agent start reviewer --kind claude --pane "$p"
herdr agent prompt reviewer "$TASK" --wait --timeout 300000

# blocked로 멈췄으면 판단 전에 반드시 확인
herdr agent get reviewer
herdr agent read reviewer --source detection

# 상태 확인
herdr agent list
herdr agent explain <target> --json
herdr integration status
herdr status

# 레이아웃
herdr workspace list
herdr tab list --workspace "$HERDR_WORKSPACE_ID"
herdr pane list --workspace "$HERDR_WORKSPACE_ID"
herdr pane current --current
herdr pane layout --pane "$HERDR_PANE_ID"

# 설정
herdr --default-config
herdr server reload-config

# 커맨드 그룹 도움말 (서브커맨드 없이 실행)
herdr agent / pane / workspace / tab / worktree / notification / plugin / session

# 알림
herdr notification show "제목" --body "내용" --sound request