요약 · Claude Code Agent View는 여러 백그라운드 세션을 한 화면에서 디스패치·모니터링·회신·전환하는 대시보드다. 본문은 진입 방법, 상태·요약 읽기, worktree 격리, 모델·권한 설정, 셸 관리와 단축키까지 워크플로 중심으로 정리한다.
Agent View 한눈에 보기
Claude Code Agent View는 여러 백그라운드 세션을 한 화면에서 디스패치·모니터링·관리하는 터미널 대시보드다. 연구(preview) 단계로 제공되어 인터페이스와 단축키는 향후 변경될 수 있다.
최소 요구 버전은 Claude Code v2.1.139이며, 일부 옵션은 v2.1.141~v2.1.143에서 추가됐다. 문서에 명시된 범위 내 기능을 기준으로 워크플로 운영법을 정리한다.
Agent View는 subagent 또는 agent teams의 대체가 아니라, 이들이 수행하는 작업을 다중 세션 관점에서 관찰하고 조정하는 상위 운영 계층에 가깝다. 팀·개인 모두에게 세션 운영의 가시성과 제어력을 제공한다.
진입과 첫 디스패치(quick start)
터미널에서 claude agents를 실행하면 Agent View가 열린다. Esc로 나가도 세션은 supervisor가 백그라운드에서 계속 돌며 이후 다시 붙어 이어갈 수 있다.
화면 하단 입력창에 프롬프트를 적고 Enter를 누르면 새 백그라운드 세션이 생성된다. 같은 입력창에서 Shift+Enter를 쓰면 생성 직후 해당 세션으로 바로 attach할 수 있다.
첫 실행 시 사용자별 supervisor 프로세스가 자동 기동된다. 인증은 평소 인터랙티브 세션과 동일 자격을 사용하며, 모델 API 외 추가 네트워크 호출을 늘리지 않는다.
세션 그룹과 상태 아이콘 읽기
상단부터 Pinned, Ready for review, Needs input, Working, Completed 그룹으로 정렬되며, 위쪽일수록 사용자의 주의와 개입이 빠르게 필요하다. 핀 고정은 장기 작업을 눈앞에 유지하는 용도다.
상태 색과 애니메이션으로 진행 상황을 읽는다. Working은 애니메이션, Needs input은 노랑, Idle은 흐림, Completed는 녹색, Failed는 빨강, Stopped는 회색으로 표현된다.
아이콘은 살아있는 프로세스 ✻/✽, 종료된 프로세스 ∙(필요 시 재개), /loop 슬립 중 ✢로 구분된다. 우측 PR 닷은 노랑(검토대기/실패), 녹색(통과), 보라(merged), 회색(draft·closed)로 리뷰 파이프라인 상태를 요약한다.
Row 자동 요약의 동작
각 row의 한 줄 요약은 Haiku-class 모델이 생성한다. 활발한 작업 중에는 최대 15초 주기와 턴 종료 시점에 갱신되어, 무슨 일이 진행 중인지 빠르게 훑을 수 있다.
요약 한 번마다 짧은 Haiku 호출이 발생하며, 호출 비용과 데이터 약관은 일반 사용과 동일하게 적용된다. 대량 병렬 실행 시에는 이 자동 요약 호출도 누적될 수 있음을 유의한다.
요약은 의사결정을 돕는 헤드라인 역할을 한다. 코드 차이나 로그는 peek나 attach로 직접 확인하고, 요약으로는 우선순위와 차단 요인을 재빨리 식별하는 습관이 좋다.
Peek와 Reply 활용
선택한 row에서 Space를 누르면 peek 패널이 열린다. 최근 출력이나 대기 중인 질문을 빠르게 확인해 문맥을 잃지 않고 대응할 수 있다.
패널 안에서 답변을 입력하고 Enter를 누르면 즉시 회신된다. 다중 선택지가 있을 때는 숫자 키로 고른다. Tab으로 추천 응답을 채워 초안을 빠르게 완성할 수 있다.
회신이 셸 명령이라면 느낌표로 시작해 입력한다. 예를 들어 !npm test처럼 쓰면 Bash 명령 회신으로 처리되어 필요한 명령을 바로 실행하게 할 수 있다.
Attach·Detach와 /background
Enter 또는 →로 선택한 세션에 풀 인터랙티브로 attach한다. 진행 중 대화와 로그를 실시간으로 보며 세밀한 지시를 내릴 수 있다.
빈 입력에서 ←를 누르면 detach된다. detach해도 백그라운드 세션은 계속 동작하므로, 모니터링은 Agent View에서, 세밀한 개입은 필요할 때만 attach하는 리듬이 효율적이다.
기존 인터랙티브 세션을 백그라운드 전환하려면 /background 또는 /bg를 실행한다. 종료가 필요할 때는 세션 내부에서 /stop을 사용한다.
새 세션 디스패치(셸·세션 내부)
Agent View 하단 입력창에서 프롬프트를 적고 Enter를 칠 때마다 하나의 새 백그라운드 세션이 만들어진다. 짧은 작업과 긴 작업을 섞어 구성해도 된다.
터미널에서도 곧바로 백그라운드 실행을 만들 수 있다. claude –bg "task", claude –agent <name> –bg "…", claude –bg –name "<별명>" 같은 형식을 쓴다.
이미 열려 있는 인터랙티브 세션에서는 /background 또는 /bg 명령으로 백그라운드 전환이 가능하다. 전환 직후 Agent View에서 해당 세션의 상태를 확인할 수 있다.
디렉터리·repo 타깃 지정
기본 타깃은 Agent View를 연 디렉터리다. 폴더별로 세션을 분리하면 변경 범위를 최소화하고 충돌을 줄일 수 있다.
특정 디렉터리를 기준으로 열고 싶다면 claude agents –cwd <path>를 사용한다. 이 옵션은 v2.1.141 이상에서 지원되며, 팀 저장소가 많은 환경에서 유용하다.
입력에 @<repo> 멘션을 써서 형제 디렉터리의 repo로 디스패치할 수도 있다. 멀티 레포 모노레포 혼재 환경에서 작업 대상을 명확히 지정해 혼선을 예방한다.
Worktree 자동 격리 원리
각 백그라운드 세션은 파일 편집 직전에 .claude/worktrees/ 아래 격리된 git worktree로 자동 이동한다. 이로써 병렬 작업 간 변경이 서로 간섭하지 않도록 안전망이 생긴다.
비 git 디렉터리에서는 원본 위치를 직접 편집한다. 이런 경우 서로 다른 세션이 같은 파일을 동시에 만지지 않도록 책임 영역을 명확히 나누는 것이 중요하다.
격리 비활성화는 프로젝트 .claude/settings.json에서 worktree.bgIsolation: "none"으로 설정한다(v2.1.143+). Agent View에서 세션을 삭제(Ctrl+X 두 번)하면 Claude가 만든 worktree와 그 안의 미커밋 변경까지 지워지므로 사전 push/merge가 필요하다.
모델·permission mode·effort 묶어 지정
헤더에는 현재 디스패치 기본 모델이 표시된다. 세션 안에서는 /model 피커로, 셸에서는 –model 플래그로 모델을 바꿀 수 있다.
여러 속성을 한 번에 지정하려면 claude agents –permission-mode plan –model opus –effort high처럼 묶어 전달한다(v2.1.142+). 반복되는 세션 구성 시간을 줄이는 실전 팁이다.
bypassPermissions나 auto 모드는 사전에 인터랙티브 세션에서 한 번 수락해야 활성화된다. 조직 정책상 자동 권한 부여가 필요한 경우 이 조건을 먼저 충족시켜야 한다.
설정·플러그인·MCP 전파
–settings, –add-dir, –plugin-dir, –mcp-config, –strict-mcp-config는 Agent View에 적용되며 이후 디스패치되는 모든 세션으로 전파된다(v2.1.142+). 환경 일관성을 확보하기에 좋은 구조다.
–add-dir, –plugin-dir, –mcp-config는 값마다 반복 지정이 가능하다. 프로젝트별 도구 세트를 분리 구성하면서도 하나의 Agent View에서 통합 운영할 수 있다.
새로운 플러그인과 MCP를 추가할 때는 작은 작업부터 시범 적용하고 문제가 없을 때 핀 세션으로 확장하는 방식이 안전하다. 문제가 생기면 해당 플래그를 제거하고 재기동한다.
셸 관리 명령 모음
실행 중 세션 현황은 claude agents –json으로 확인한다. pid, cwd, kind, startedAt와 함께 sessionId, name, status 등이 JSON으로 출력된다.
개별 세션 제어는 claude attach <id>, claude logs <id>, claude stop <id>(= claude kill), claude respawn <id> 또는 claude respawn –all, claude rm <id>로 수행한다.
supervisor 상태는 claude daemon status로 본다. 버전, 소켓 경로, 워커 수까지 요약되므로 문제 발생 시 1차 점검 포인트로 삼기 좋다.
Supervisor 프로세스가 하는 일과 상태 저장
Supervisor는 사용자별 1개가 동작하며, 첫 백그라운드 디스패치나 Agent View 오픈 시 자동 시작된다. 인증은 인터랙티브 세션과 동일 자격을 재사용한다.
비활성 비핀 세션은 약 1시간 유휴 후 프로세스가 stop되며, 다음 attach·peek·reply 시 자동 재기동된다. 호스트 메모리 부족 시에는 비핀 세션부터 우선 중단해 리소스를 회수한다.
상태 파일은 ~/.claude/daemon.log, ~/.claude/daemon/roster.json, ~/.claude/jobs/<id>/state.json에 저장된다. CLAUDE_CONFIG_DIR를 지정하면 해당 경로로 분리되어 별도 supervisor 인스턴스로 운영된다.
단축키 핵심 정리
화살표 ↑/↓로 이동, Enter로 attach 또는 디스패치, Space로 peek, Shift+Enter로 디스패치+attach, →로 attach가 가능하다. 빈 입력에서 ←는 detach다.
Alt+1..9는 동일 디렉터리의 1~9번 세션으로 빠르게 attach한다. Tab은 추천 응답 또는 서브에이전트 브라우즈에 활용한다.
Ctrl+S 그룹 전환, Ctrl+T pin, Ctrl+R rename, Ctrl+G 외부 에디터 열기, Ctrl+X 정지/삭제, Shift+↑/↓ 재정렬, Esc 닫기, Ctrl+C 입력 초기화(2회 시 종료), ?로 단축키 도움말을 확인한다.
필터링 문법
특정 subagent가 실행 중인 세션만 보려면 a:<name> 형식을 사용한다. 하위 에이전트별 성능 추적에 유용하다.
상태 기준 필터는 s:<state>를 쓴다. 예를 들어 s:working이나 s:blocked로 현재 병목 지점을 한눈에 좁혀볼 수 있다.
PR 연계 작업은 #<number> 또는 PR URL로 해당 이슈·리뷰에 매달린 세션만 선택한다. 리뷰 큐를 비우는 순서를 정할 때 적합하다.
비활성화 옵션과 팀 정책
Agent View를 아예 끄려면 설정에서 disableAgentView를 true로 두거나, 환경변수 CLAUDE_CODE_DISABLE_AGENT_VIEW를 설정한다. 필요 시 관리 정책으로 강제할 수 있다.
팀 환경에서는 표준 진입점과 책임 분리를 정책화하자. 예를 들어 주요 저장소는 Agent View를 허용하고, 일부 민감 레포는 기능을 비활성화해 변경 경로를 제한한다.
정책 변경 시에는 supervisor 재기동 타이밍과 세션 유휴 상태를 고려한다. 핀 세션이 많은 팀은 변경 공지 후 점진적 적용을 권장한다.
제한과 비용 주의
구독 사용량은 그대로 소모되며, 10개 병렬이면 소비 속도도 대략 10배에 가깝다. 요약 호출까지 누적되므로 예산 한도를 미리 정해 두자.
세션은 로컬에서 동작한다. 슬립은 보존되지만 셧다운 후에는 중단되며, 다음 접근 시 중단 지점에서 재기동된다.
Claude가 만든 worktree는 Agent View 내 삭제와 함께 사라진다. 반면 claude rm은 미커밋 변경을 보존한다는 차이를 이해하고, 중요한 변경은 push/merge로 안전하게 승격하자.
한국 개발자가 바로 활용할 워크플로
첫째, 모듈 단위로 작업을 쪼갠다. 핵심 리팩토링, 테스트 보강, 문서화, 릴리스 노트를 각각 별도 세션으로 디스패치한다.
둘째, Ready for review와 Needs input 그룹을 매 시간 확인한다. Space로 peek해 숫자 키와 Tab을 조합해 빠르게 회신하고, 중요한 것은 pin으로 상단에 고정한다.
셋째, 긴 작업은 /background로 넘기고 단축키 Alt+1..9로 오가며 모니터링한다. 배포 전에는 s:working 필터로 남은 작업만 추려 안정적으로 마무리한다.
트러블슈팅 요약
claude agents가 subagent 목록만 출력된다면 환경이 Agent View를 지원하지 않는 버전일 가능성이 높다. claude update로 최신 버전으로 올린다.
프롬프트가 4자 미만이면 "Too short"로 거부된다. 요구 조건을 충족하도록 작업 설명을 명확히 적자.
셧다운 후 Failed로 표시된 세션은 attach·peek·reply 중 아무 경로로나 접근하면 재개된다. 필요 시 claude respawn으로 강제 재기동해도 된다.
자주 묻는 질문
- 어떤 버전부터 Agent View를 사용할 수 있나요?
- v2.1.139 이상에서 사용할 수 있습니다. 디렉터리 지정(–cwd)은 v2.1.141+, 설정·플러그인·MCP 전파 및 모델·권한 묶음 지정은 v2.1.142+, worktree 격리 비활성화는 v2.1.143+에 추가되었습니다.
- 기존 subagent·agent teams와 Agent View는 무엇이 다른가요?
- 역할이 다릅니다. subagent와 agent teams는 작업을 수행하는 실행 단위이며, Agent View는 여러 세션을 한 화면에서 디스패치·모니터링·개입하는 운영 대시보드입니다. 따라서 둘은 상호 보완적으로 함께 사용됩니다.
- 백그라운드 세션은 노트북을 꺼도 유지되나요?
- 부분적으로 유지됩니다. 슬립은 보존되지만 셧다운 시 프로세스는 중단되고, 다음에 attach·peek·reply로 접근하면 마지막 지점에서 재기동됩니다. 유휴 약 1시간이 지나면 비핀 세션은 supervisor가 stop합니다.
- 팀 환경에서 Agent View 기능을 끄는 방법이 있나요?
- 있습니다. 설정에서 disableAgentView를 true로 두거나 환경변수 CLAUDE_CODE_DISABLE_AGENT_VIEW를 설정합니다. 조직의 managed settings로 강제 적용할 수도 있습니다.
