Documentation Index
Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
claude agents로 열 수 있는 에이전트 뷰는 모든 백그라운드 세션을 위한 하나의 화면입니다: 무엇이 실행 중인지, 무엇이 입력을 필요로 하는지, 무엇이 완료되었는지를 보여줍니다. 새로운 세션을 디스패치하고, 트랜스크립트를 스크롤하는 대신 한눈에 상태를 확인하고, 필요할 때만 개입합니다. 각 백그라운드 세션은 터미널이 연결되지 않은 상태에서도 계속 실행되는 완전한 Claude Code 대화이므로, 언제든지 열고, 답변하고, 떠날 수 있습니다.
에이전트 뷰는 연구 미리보기이며 Claude Code v2.1.139 이상이 필요합니다.
claude --version으로 버전을 확인합니다. 기능이 발전함에 따라 인터페이스와 키보드 단축키가 변경될 수 있습니다.- 빠른 시작: Claude에게 백그라운드에서 작업할 작업을 제공하고, 확인하고, 필요할 때 개입합니다
- 에이전트 뷰로 세션 모니터링, 상태 아이콘, 엿보기 및 답변, 연결, 구성 및 키보드 단축키 포함
- 에이전트 뷰에서 새로운 에이전트 디스패치, 세션 내에서, 또는 셸에서
- 셸에서 세션 관리
- 백그라운드 세션이 호스팅되는 방식, 감독자 프로세스에 의해
빠른 시작
이 연습은 핵심 에이전트 뷰 루프를 다룹니다: 작업을 디스패치하고, Claude가 작업하면서 행이 업데이트되는 것을 지켜보고, 엿보기로 확인하고 답변하고, 전체 대화를 위해 연결합니다. 디스패치한 세션은 에이전트 뷰를 닫은 후에도 계속 실행되므로, 언제든지 떠났다가 돌아올 수 있습니다.에이전트 뷰 열기
셸에서 다음을 실행합니다:에이전트 뷰가 하단의 입력과 세션이 시작되면서 채워지는 테이블과 함께 열립니다. 언제든지
Esc를 눌러 셸로 돌아갑니다. 세션은 떠나 있는 동안 계속 실행되며 다음에 에이전트 뷰를 열 때 다시 나타납니다.세션 디스패치
작업을 설명하는 프롬프트를 입력하고
Enter를 누릅니다. 새로운 백그라운드 세션이 해당 작업에서 시작되고 작업 중인지, 입력을 기다리는지, 완료되었는지를 보여주는 행으로 나타납니다. 새로운 세션은 에이전트 뷰 헤더에 표시된 모델과 해당 디렉토리에서 claude를 실행할 때 얻을 수 있는 동일한 권한 모드를 사용합니다.여기에 입력하는 모든 프롬프트는 자신의 새로운 세션을 시작합니다. 다른 프롬프트를 입력하고 Enter를 누르면 첫 번째 세션에 후속 메시지를 보내는 대신 첫 번째 세션과 함께 두 번째 세션을 시작합니다. 이렇게 여러 세션을 병렬로 실행할 수 있습니다.각 세션은 구독 할당량을 독립적으로 사용하므로, 한 번에 많은 세션을 디스패치하기 전에 제한사항을 참조하십시오.엿보기 및 답변
화살표 키로 행을 선택하고
Space를 눌러 엿보기 패널을 엽니다. 전체 대화 기록이 아닌 세션의 가장 최근 출력 또는 기다리고 있는 질문을 표시합니다. 답변을 입력하고 Enter를 눌러 에이전트 뷰를 떠나지 않고 전송합니다.연결 및 분리
전체 대화를 원할 때 행에서
Enter 또는 →를 눌러 연결합니다. 세션이 claude를 실행한 것처럼 정확히 터미널을 인수합니다. 빈 프롬프트에서 ←를 눌러 분리하고 테이블로 돌아갑니다.claude agents를 claude 대신 기본 진입점으로 사용할 수 있습니다: 에이전트 뷰에서 모든 작업을 디스패치하고, 전체 대화를 원할 때 연결하고, ←를 눌러 테이블로 돌아갑니다.
에이전트 뷰로 세션 모니터링
claude agents를 실행하여 에이전트 뷰를 엽니다. 전체 터미널을 차지하고 상태별로 그룹화된 모든 세션을 나열하며, 고정된 세션과 입력이 필요한 세션이 맨 위에 있습니다. 각 행은 세션의 이름, 현재 활동 및 마지막 변경 이후 경과 시간을 보여줍니다.
목록은 시작한 모든 백그라운드 세션을 표시하며, 모든 프로젝트에 걸쳐 있습니다. 한 저장소에서 작업하는 세션과 다른 worktree에서 작업하는 세션은 모두 여기에 나타나며, 에이전트 뷰를 연 디렉토리와 관계없이 표시됩니다. 다른 터미널에서 열려 있는 대화형 세션은 백그라운드로 보낼 때까지 나타나지 않습니다. 서브에이전트와 팀원은 세션이 생성하는 별도의 행으로 나열되지 않습니다.
세션 상태 읽기
각 행은 세션의 상태를 나타내는 아이콘으로 시작하며, 아이콘의 색상과 애니메이션이 상태를 보여줍니다:| 상태 | 아이콘 표시 | 의미 |
|---|---|---|
| 작업 중 | 애니메이션 | Claude가 적극적으로 도구를 실행하거나 응답을 생성 중 |
| 입력 필요 | 노란색 | Claude가 특정 질문이나 권한 결정을 기다리는 중 |
| 유휴 | 흐릿함 | 세션이 할 일이 없으며 다음 프롬프트를 기다리는 중 |
| 완료됨 | 녹색 | 작업이 성공적으로 완료됨 |
| 실패 | 빨간색 | 작업이 오류로 종료됨 |
| 중지됨 | 회색 | 세션이 Ctrl+X 또는 claude stop으로 중지됨 |
| 모양 | 의미 |
|---|---|
✻ 또는 애니메이션 ✽ | 세션 프로세스가 활성 상태이며 즉시 응답 |
∙ | 프로세스가 종료됨. 여전히 엿보기, 답변 또는 연결할 수 있으며, Claude는 중단된 위치에서 다시 시작 |
✢ | /loop 세션이 반복 사이에 절전 중. 행은 실행 횟수와 카운트다운을 표시 |
claude respawn --all로 다시 시작합니다.
행 요약
각 행의 한 줄 요약은 Haiku 클래스 모델에 의해 생성되므로 행은 세션이 무엇을 하고 있는지, 무엇이 필요한지, 또는 트랜스크립트를 열지 않고도 무엇을 생성했는지 알려줄 수 있습니다. 세션이 적극적으로 작동하는 동안 요약은 최대 15초마다 한 번, 그리고 각 턴이 끝날 때 한 번 새로고침됩니다. 각 새로고침은 일반 제공자를 통한 하나의 짧은 Haiku 클래스 요청이며, 세션 자체와 동일한 데이터 사용 약관에 따라 청구되고 처리됩니다.풀 리퀘스트 상태
세션이 풀 리퀘스트를 열면 상태 점이 행의 오른쪽 가장자리에 나타나며, 하이퍼링크를 지원하는 터미널에서 풀 리퀘스트에 연결됩니다. 세션이 둘 이상의 풀 리퀘스트를 열었을 때 개수가 점 앞에 나타나고 색상은 가장 주의가 필요한 것을 반영합니다.| 점 색상 | 풀 리퀘스트 상태 |
|---|---|
| 노란색 | 검사 또는 검토 대기 중, 또는 검사 실패 |
| 녹색 | 검사 통과 및 검토 차단 없음 |
| 보라색 | 병합됨 |
| 회색 | 초안 또는 닫힘 |
엿보기 및 답변
선택된 행에서Space를 눌러 엿보기 패널을 엽니다. 세션이 필요로 하는 것, 최근 출력 및 열린 풀 리퀘스트를 보여줍니다. 대부분의 경우 이것으로 충분하며 전체 트랜스크립트를 열 필요가 없습니다.
엿보기 패널에 답변을 입력하고 Enter를 눌러 해당 세션으로 전송합니다. 세션이 객관식 질문을 하는 경우 엿보기 패널은 옵션을 표시하고 숫자 키를 눌러 하나를 선택할 수 있습니다. 다른 차단된 세션의 경우 Tab을 눌러 입력을 편집하기 전에 제안된 답변으로 채웁니다. 답변 앞에 !를 붙여 Bash 명령을 대신 전송합니다.
↑ 및 ↓를 사용하여 패널을 닫지 않고 인접한 세션을 엿보거나 →를 눌러 연결합니다.
세션에 연결
선택된 행에서Enter 또는 →를 눌러 연결합니다. 에이전트 뷰는 claude를 실행한 것처럼 정확히 전체 대화형 세션으로 대체됩니다. 연결하면 Claude는 떠나 있는 동안 발생한 일에 대한 짧은 요약을 게시합니다.
연결된 동안 세션은 다른 Claude Code 세션처럼 작동합니다: 모든 명령, 키보드 단축키 및 기능이 작동합니다.
빈 프롬프트에서 ←를 눌러 분리하고 에이전트 뷰로 돌아갑니다. 대화 상자가 포커스를 가지고 있고 ←에 응답하지 않으면 Ctrl+Z를 눌러 즉시 분리합니다.
분리는 백그라운드 세션을 중지하지 않습니다: ←, Ctrl+C, Ctrl+D, Ctrl+Z 및 /exit은 모두 실행 상태로 둡니다. 세션 내에서 세션을 종료하려면 /stop을 실행합니다.
에이전트 뷰에서 디스패치하거나 백그라운드로 보낸 후, 빈 프롬프트에서 ←를 누르면 에이전트 뷰에서 연결한 세션뿐만 아니라 모든 Claude Code 세션에서 작동합니다. 현재 세션을 백그라운드로 보내고 해당 세션이 미리 선택된 상태로 에이전트 뷰를 열어 터미널을 떠나지 않고 세션을 전환할 수 있습니다. /config에서 이 단축키를 끌 수 있습니다.
목록 구성
에이전트 뷰는 세션을 그룹화하여 입력이 필요한 세션이 맨 위에 있고,검토 준비 완료와 입력 필요가 작업 중과 완료됨 위에 있습니다. 이 그룹 이름은 상태 위의 일대일 매핑이 아닙니다: 세션이 열린 풀 리퀘스트를 가지면 검토 준비 완료로 이동하고, 완료됨은 완료되고, 실패하고, 중지된 세션을 함께 수집합니다. Ctrl+S를 눌러 대신 디렉토리별로 그룹화로 전환합니다. 선택 사항은 실행 간에 저장됩니다.
그룹 내에서:
Ctrl+T를 눌러 세션을 맨 위에 고정Shift+↑또는Shift+↓를 눌러 세션 순서 변경Ctrl+R을 눌러 세션 이름 바꾸기- 그룹 헤더에서
Enter를 눌러 축소
Ctrl+X를 눌러 중지하고 2초 이내에 Ctrl+X를 다시 눌러 삭제합니다. 그룹 헤더에서 Ctrl+X를 누르면 확인 후 해당 그룹의 모든 세션이 삭제됩니다.
삭제하면 세션이 에이전트 뷰에서 제거되고 worktree를 정리하며, 커밋되지 않은 변경 사항을 포함합니다. 따라서 삭제하기 전에 유지하려는 작업을 푸시하거나 커밋합니다. 대화 트랜스크립트는 디스크에 남아 있으며 claude --resume을 통해 사용 가능합니다.
오래된 완료된 세션은 목록을 짧게 유지하기 위해 … N more 행으로 접힙니다. 실패 및 열린 풀 리퀘스트가 있는 세션은 항상 표시됩니다.
세션 필터링
디스패치 입력에 입력하여 디스패치 대신 필터링합니다:| 필터 | 표시 |
|---|---|
a:<name> | 명명된 에이전트를 실행하는 세션 |
s:<state> | 주어진 상태의 세션, 예: s:working. 또한 s:blocked를 수락하여 입력을 기다리는 모든 것 |
#<number> 또는 PR URL | 해당 풀 리퀘스트에서 작업하는 세션 |
키보드 단축키
에이전트 뷰에서?를 눌러 모든 단축키를 확인합니다. 아래 표는 이를 요약합니다.
| 단축키 | 작업 |
|---|---|
↑ / ↓ | 행 간 이동 |
Enter | 선택된 세션에 연결하거나, 입력에 텍스트가 있으면 디스패치 |
Space | 선택된 세션의 엿보기 패널 열기 또는 닫기 |
Shift+Enter | 디스패치하고 즉시 연결 |
→ | 선택된 세션에 연결 |
Alt+1..Alt+9 | 현재 그룹의 세션 1–9에 연결 |
Tab | 빈 입력에서 모든 서브에이전트 검색. 그 외에는 강조된 제안 적용 |
Ctrl+S | 상태와 디렉토리 간 그룹화 전환 |
Ctrl+T | 선택된 세션 고정 또는 고정 해제 |
Ctrl+R | 선택된 세션 이름 바꾸기 |
Ctrl+G | $EDITOR에서 디스패치 프롬프트 열기 |
Ctrl+X | 세션 중지; 2초 이내에 다시 눌러 삭제 |
Shift+↑ / Shift+↓ | 선택된 세션 순서 변경 |
Esc | 엿보기 패널 닫기, 입력 지우기 또는 종료 |
Ctrl+C | 입력 지우기; 두 번 눌러 종료 |
? | 모든 단축키 표시 |
새로운 에이전트 디스패치
에이전트 뷰에서 새로운 백그라운드 세션을 디스패치하거나, 기존 대화형 세션을 백그라운드로 보내거나, 셸에서 직접 시작할 수 있습니다.에이전트 뷰에서
에이전트 뷰 하단의 입력에 프롬프트를 입력하고Enter를 눌러 새로운 백그라운드 세션을 시작합니다. 세션은 프롬프트에서 자동으로 이름이 지정됩니다. 나중에 Ctrl+R로 이름을 바꿀 수 있습니다.
프롬프트에 이미지를 붙여넣어 작업에 스크린샷이나 다이어그램을 포함합니다.
프롬프트의 일부를 접두사로 붙이거나 언급하여 세션이 시작되는 방식을 제어합니다:
| 입력 | 효과 |
|---|---|
<agent-name> <prompt> | 첫 번째 단어가 사용자 정의 서브에이전트 이름과 일치하면 해당 서브에이전트가 프론트매터의 구성으로 세션의 주 에이전트로 실행됨 |
@<agent-name> | 프롬프트의 어디든지 사용자 정의 서브에이전트를 언급하여 주 에이전트로 실행 |
@<repo> | 에이전트 뷰를 연 디렉토리 아래의 저장소를 언급하여 세션을 거기서 실행 |
/<skill> | 스킬을 프롬프트로 디스패치하도록 제안 |
#<number> 또는 풀 리퀘스트 URL | 세션이 이미 해당 PR에서 작업 중이면 디스패치 대신 선택 |
Shift+Enter | 디스패치하고 즉시 새 세션에 연결 |
@name이 서브에이전트와 형제 저장소 모두와 일치하면 서브에이전트가 우선합니다. 첫 단어 일치도 적용되므로 서브에이전트 이름 중 하나로 시작하는 프롬프트는 해당 서브에이전트를 디스패치합니다. 명시적으로 하려면 @ 형식을 사용하거나, 일치를 피하기 위해 다른 단어로 프롬프트를 시작합니다.
특정 디렉토리로 디스패치
새로운 세션은 에이전트 뷰를 연 디렉토리에서 실행됩니다. 다른 디렉토리를 대상으로 하려면:- 해당 디렉토리에서
claude agents를 엽니다. - 여러 저장소를 보유한 상위 디렉토리에서
claude agents를 열고 프롬프트에서@<repo>로 하나를 언급하여 세션을 거기서 실행합니다. - 셸에서 디렉토리로
cd하고claude --bg "<prompt>"를 실행합니다.
세션 내에서
/background 또는 별칭 /bg를 실행하여 현재 대화를 백그라운드 세션으로 이동합니다. /bg run the test suite and fix any failures와 같은 프롬프트를 전달하여 먼저 하나의 추가 명령을 보냅니다.
대화형 세션에서 백그라운드로 이동하면 저장된 대화에서 재개되는 새로운 프로세스가 시작되므로 서브에이전트, 모니터 및 백그라운드 명령을 실행하는 것이 이동되지 않습니다. Claude는 실행 중인 것이 있을 때 백그라운드로 이동하기 전에 확인을 요청합니다. 백그라운드에 있으면 세션은 새로운 서브에이전트, 모니터 및 백그라운드 명령을 시작할 수 있으며, 이들은 나중의 분리 및 재연결 전체에서 계속 실행됩니다.
셸에서
--bg를 전달하여 백그라운드로 직접 이동하는 세션을 시작합니다:
--bg를 --agent와 결합합니다:
파일 편집이 격리되는 방식
에이전트 뷰,/bg 또는 claude --bg에서 시작된 모든 백그라운드 세션은 작업 디렉토리에서 시작됩니다. 파일을 편집하기 전에 Claude는 세션을 .claude/worktrees/ 아래의 격리된 git worktree로 이동하므로 병렬 세션은 동일한 체크아웃을 읽을 수 있지만 각각은 자신의 것에 씁니다. Claude는 세션이 이미 .claude/worktrees/ 아래에 있을 때, 작업 디렉토리가 git 저장소가 아닐 때, 또는 작업 디렉토리 외부에 쓸 때는 이를 건너뜁니다.
git 저장소 외부에서 세션은 작업 디렉토리에 직접 쓰며 서로 격리되지 않으므로 동일한 파일을 편집하는 병렬 세션을 디스패치하지 않도록 합니다.
워크트리는 세션을 삭제할 때 제거되므로 삭제하기 전에 유지하려는 변경 사항을 병합하거나 푸시합니다. 세션의 워크트리 경로를 찾으려면 세션을 엿보거나 연결하고 작업 디렉토리를 확인합니다.
서브에이전트가 시작된 방식에 관계없이 항상 자체 워크트리에서 실행되도록 하려면 프론트매터에서 isolation: worktree를 설정합니다.
모델 설정
에이전트 뷰 헤더에 표시된 모델 이름은 디스패치 기본값입니다. 입력에서 시작하는 새로운 세션은 이 모델을 사용하며, 이는 모든 세션에서/model이 제어하는 것과 동일한 설정입니다. 에이전트 뷰를 열 때 --model을 전달하여 전체 에이전트 뷰 세션에 대해 이를 재정의합니다. 권한 모드, 모델 및 노력을 참조하십시오.
각 백그라운드 세션은 다른 모델에서 실행될 수 있습니다. 한 세션에 대해 이를 재정의하려면:
- 셸에서
claude --bg와 함께--model을 전달합니다. - 실행 중인 세션에 연결하고 거기서
/model을 실행합니다. 세션이 다시 생성되면 변경 사항이 유지됩니다. - 프론트매터가
model필드를 설정하는 서브에이전트를 디스패치합니다.
권한 모드, 모델 및 노력
디스패치된 세션은 실행되는 디렉토리에서 설정 및 권한 모드를 읽으며, 마치 거기서claude를 시작한 것처럼 동일합니다.
에이전트 뷰를 열 때 --permission-mode, --model 또는 --effort 중 하나를 전달하여 에이전트 뷰에서 디스패치하는 모든 세션에 대한 기본값을 설정합니다:
defaultMode를 사용하거나 디스패치된 서브에이전트의 프론트매터에서 permissionMode를 사용하며, 에이전트 뷰 헤더에 표시된 모델을 사용합니다.
bypassPermissions 또는 auto를 사용하는 것은 대화형으로 한 번 실행하여 해당 모드를 수락할 때까지 거부됩니다. 이러한 모드는 감시하지 않는 세션이 승인 없이 작동하도록 허용하기 때문입니다. 이는 claude agents에 모드를 전달하든 claude --bg --permission-mode에 전달하든 동일하게 적용됩니다.
설정, 플러그인 및 MCP 서버
에이전트 뷰는 설정, 플러그인, MCP 서버 및 추가 디렉토리를 로드하기 위해claude와 동일한 구성 플래그를 허용합니다. 각 플래그는 에이전트 뷰 자체에 적용되며 디스패치하는 모든 세션에 전달되므로 이러한 방식으로 로드하는 플러그인 또는 MCP 서버는 해당 세션에서도 사용 가능합니다.
| 플래그 | 효과 |
|---|---|
--settings <file-or-json> | 에이전트 뷰 및 디스패치된 세션에 대한 설정 재정의 |
--add-dir <path> | 추가 디렉토리에 파일 액세스 권한 부여 |
--plugin-dir <path> | 로컬 디렉토리에서 플러그인 로드 |
--mcp-config <file-or-json> | 구성 파일 또는 JSON 문자열에서 MCP 서버 로드 |
--strict-mcp-config | --mcp-config에서만 MCP 서버를 사용하고 다른 MCP 구성 무시 |
--add-dir, --plugin-dir 또는 --mcp-config를 값당 한 번씩 반복합니다. --add-dir a b c와 같은 공백으로 구분된 형식은 claude agents에서 지원되지 않습니다.
다음 예제는 설정 재정의 및 하나의 추가 디렉토리로 에이전트 뷰를 엽니다:
셸에서 세션 관리
모든 백그라운드 세션에는 셸에서 사용할 수 있는 짧은 ID가 있습니다. ID는claude --bg로 세션을 시작할 때 출력되며, 각 세션의 ID는 ~/.claude/jobs/ 아래의 디렉터리 이름입니다. 이 명령은 스크립팅이나 에이전트 뷰를 열고 싶지 않을 때 유용합니다.
| 명령 | 목적 |
|---|---|
claude agents | 에이전트 뷰 열기 |
claude attach <id> | 이 터미널에서 세션에 연결 |
claude logs <id> | 세션의 최근 출력 인쇄 |
claude stop <id> | 세션 중지. claude kill도 허용 |
claude respawn <id> | 대화를 유지하면서 중지된 세션 다시 시작 |
claude respawn --all | 모든 중지된 세션 다시 시작 |
claude rm <id> | 목록에서 세션 제거. 커밋되지 않은 변경 사항이 없으면 worktree 정리 |
백그라운드 세션이 호스팅되는 방식
에이전트 뷰에 나열된 모든 세션은 현재 연결되어 있는지 여부와 관계없이 백그라운드 세션으로 간주됩니다. 반대로claude를 직접 실행하여 시작한 세션은 해당 터미널에 연결되어 있으며 백그라운드로 보내지 않는 한 터미널이 닫힐 때 종료됩니다.
감독자 프로세스
백그라운드 세션은 터미널 및 에이전트 뷰와 별도의 사용자별 감독자 프로세스에 의해 호스팅됩니다. 감독자는 세션을 백그라운드로 보내거나 에이전트 뷰를 열 때 자동으로 시작되며 직접 관리하지 않습니다. 감독자 및 세션은 대화형 세션과 동일한 자격 증명으로 인증하고 모델 API 이상의 추가 네트워크 연결을 하지 않습니다. 각 백그라운드 세션은 자체 Claude Code 프로세스이며 터미널이 아닌 감독자에 의해 관리됩니다. 적극적으로 작업 중이거나, 입력을 기다리거나, 터미널이 연결된 세션은 프로세스를 실행 상태로 유지합니다. 세션이 완료되고 약 1시간 동안 연결되지 않은 상태로 있으면 감독자는 리소스를 확보하기 위해 프로세스를 중지합니다. 트랜스크립트와 상태는 디스크에 유지되며, 다음에 연결하거나, 엿보거나, 답변할 때 감독자는 중단된 위치에서 새로운 프로세스를 시작합니다. 모든 세션이 완료되고 터미널이 연결되지 않으면 감독자 자체가 종료되고 다음에 필요할 때 다시 시작됩니다. 감독자는 디스크에 설치된 Claude Code 바이너리를 감시하고 일반 자동 업데이터가 교체한 후 새 버전으로 다시 시작합니다. 이는 네트워크 검사가 아닌 로컬 파일 감시입니다. 백그라운드 세션은 분리된 프로세스이므로 다시 시작을 통해 계속 실행되고 새 감독자는 다시 연결됩니다.상태가 저장되는 위치
세션 상태는 Claude Code 구성 디렉토리 아래에 저장됩니다.CLAUDE_CONFIG_DIR을 설정하면 감독자는 ~/.claude 대신 해당 디렉토리를 사용하고 자체 세션이 있는 별도의 인스턴스로 실행됩니다.
| 경로 | 내용 |
|---|---|
~/.claude/daemon.log | 감독자 로그 |
~/.claude/daemon/roster.json | 실행 중인 백그라운드 세션 목록, 다시 시작 후 다시 연결하는 데 사용됨 |
~/.claude/jobs/<id>/state.json | 에이전트 뷰에 표시되는 세션별 상태 |
에이전트 뷰 끄기
백그라운드 에이전트 및 에이전트 뷰를 완전히 끄려면disableAgentView 설정을 true로 설정하거나 CLAUDE_CODE_DISABLE_AGENT_VIEW 환경 변수를 설정합니다. 관리자는 관리 설정을 통해 이를 적용할 수 있습니다.
문제 해결
claude agents가 에이전트 뷰를 열지 않고 서브에이전트를 나열함
claude agents가 개수를 출력한 후 구성된 서브에이전트를 나열하고 종료되면, 에이전트 뷰를 사용할 수 없는 환경입니다. 이전 버전은 Bedrock, Vertex AI 또는 Foundry를 통해 연결된 경우를 포함하여 모든 환경에서 에이전트 뷰를 열지 않았습니다. claude update를 실행하여 최신 버전을 설치합니다.
업데이트 후에도 에이전트 뷰가 열리지 않으면, 설정 또는 환경 변수에 의해 꺼져 있는지 확인합니다.
에이전트 뷰가 세션 없이 열림
에이전트 뷰는 첫 번째 세션을 디스패치할 때까지 비어 있습니다. 하단의 입력에 프롬프트를 입력하고Enter를 누릅니다.
백그라운드 작업이 실행 중이어서 에이전트를 열 수 없음
←를 눌러 현재 세션을 백그라운드로 전환할 때 Cannot open agents — N background task(s) running이 표시되면, 세션에 서브에이전트, 워크플로우 또는 백그라운드 셸 명령과 같은 진행 중인 작업이 있으며, 바로가기는 이를 자동으로 중단하지 않습니다. /tasks를 실행하여 실행 중인 작업을 확인한 후 /bg를 실행하여 중단을 확인합니다. 백그라운드할 때 전송되는 항목과 전송되지 않는 항목에 대해서는 세션 내에서를 참조합니다.
프롬프트가 너무 짧아서 거부됨
디스패치 입력은 대화형 오프닝이 아닌 작업 설명을 예상합니다. 4자 미만의 프롬프트는Too short 힌트와 함께 거부되므로 실수로 누른 키가 세션을 시작하지 않습니다. 세션이 수행할 작업을 설명합니다. 예를 들어 investigate the flaky checkout test와 같이 설명합니다.
머신을 깨운 후 세션이 중지됨으로 표시됨
백그라운드 세션은 절전 또는 종료를 견디지 못하므로, 실행 중이던 세션은 깨어난 후 중지됨으로 표시됩니다. 이들 중 하나에 연결하거나, 엿보거나, 답변하면 세션이 중단된 위치에서 다시 시작됩니다. 모두 한 번에 다시 시작하려면claude respawn --all을 실행합니다.
세션이 연결 후 응답이 느림
세션이 완료되고 약 1시간 동안 연결되지 않으면 감독자는 리소스를 확보하기 위해 프로세스를 중지합니다. 연결하면 중단된 위치에서 새로운 프로세스를 시작하는데 시간이 걸립니다. 작업 중이거나 입력을 기다리는 세션은 이런 식으로 중지되지 않습니다..claude/worktrees/가 채워지고 있음
워크트리는 세션을 삭제할 때 제거됩니다. 세션이 정리 없이 종료되면 프로젝트 디렉토리에서 git worktree list로 남은 항목을 나열하고 각각을 git worktree remove <path>로 제거합니다. 워크트리 정리를 참조합니다.
제한 사항
에이전트 뷰는 연구 미리보기 상태이며 다음과 같은 제한 사항이 있습니다:- 속도 제한 적용: 백그라운드 세션은 대화형 세션과 동일하게 구독 사용량을 소모하므로 10개의 에이전트를 병렬로 실행하면 할당량을 약 10배 빠르게 소모합니다.
- 세션은 로컬입니다: 백그라운드 세션은 사용자의 머신에서 실행되며 머신이 절전 모드로 전환되거나 종료되면 중지됩니다.
- 워크트리는 세션과 함께 삭제됩니다: 자체 워크트리에서 파일을 편집한 세션을 삭제하기 전에 변경 사항을 병합하거나 푸시합니다.
관련 리소스
Claude를 병렬로 실행하는 다른 방법은 다음을 참조하십시오:- 에이전트를 병렬로 실행: 에이전트 뷰를 서브에이전트, 에이전트 팀 및 워크트리와 비교합니다
- 에이전트 팀: 서로 메시지를 주고받는 여러 세션을 조정합니다
- 웹의 Claude Code: 로컬 대신 관리되는 클라우드 환경에서 세션을 실행합니다