여러 에이전트를 에이전트 뷰로 관리하기

​

빠른 시작

claude agents

​

에이전트 뷰로 세션 모니터링

claude agents --cwd ~/projects/my-app

고정됨
  ✽ clawd walk cycle          걷기 사이클 스프라이트 프레임 그리기          3m

검토 준비 완료
  ∙ jump physics              충돌 수정으로 PR 열기                 #2048  2h

입력 필요
  ✻ power-up design           이중 점프 또는 벽 타기?                    1m

작업 중
  ✽ collision detection       CollisionSystem에 swept-AABB 검사 추가   2m
  ✢ playtest level 3          실행 12 · 모든 체크포인트 통과           4m 후

완료됨
  ✻ title screen              결과: 메뉴, 옵션 및 크레딧 완료       9m
  ∙ sound effects             결과: 14개 SFX를 assets/audio로 내보냄       4h
  … 6 more

​

세션 상태 읽기

​

행 요약

​

풀 리퀘스트 상태

• Claude Code는 풀 리퀘스트의 경우 #1234로, GitLab 병합 요청의 경우 !1234로 레이블을 작성합니다.
• Claude Code는 SSH 또는 tmux를 통한 경우와 같이 하이퍼링크 지원을 감지할 수 없을 때도 링크를 내보냅니다. FORCE_HYPERLINK=0을 설정하여 레이블을 일반 텍스트로 렌더링합니다.
• 세션에 후속 조치를 보낸 후 Claude Code는 행이 라이브 진행 상황으로 돌아가는 동안 레이블을 유지합니다.

• Claude가 gh로 풀 리퀘스트를 편집, 댓글, 닫기 또는 준비 완료로 표시할 때 Claude Code는 명령의 자체 출력이 명명하는 풀 리퀘스트에 연결합니다. 캡처된 출력이 풀 리퀨스트를 명명하지 않는 gh 명령은 링크를 생성하지 않습니다. gh pr merge는 일반적인 경우이며, 결과를 대화형 터미널에만 인쇄하기 때문입니다.
• Claude가 gh pr checkout으로 풀 리퀘스트를 체크아웃하거나 브랜치로 푸시할 때 Claude Code는 gh pr view로 브랜치를 조회하고 열린 풀 리퀘스트에 연결합니다.
• 푸시할 때 풀 리퀘스트가 아직 존재할 필요가 없습니다: Claude Code는 같은 디렉토리에서 최대 5개의 나중 git, gh, glab 또는 curl 명령이 실행된 후 브랜치 조회를 재시도하므로, 푸시 후 생성된 풀 리퀘스트(Claude가 GitHub REST API를 통해 생성한 것 포함)는 재시도가 이를 찾을 때 연결됩니다.

​

엿보기 및 답변

• 입력을 기다리는 세션: 요청하는 정확한 질문, 답변 입력 위에 표시
• 완료된 세션: 결과
• 작업 중인 세션: 전체 상태 문장

​

세션에 연결

​

터미널을 떠나지 않고 세션 전환

• Enter를 눌러 대화를 다시 엽니다.
• Esc를 눌러 전환을 취소하고 대화로 돌아갑니다. Esc가 Still starting — try again in a moment를 표시하면 백그라운드 세션이 아직 준비되지 않았으므로 잠시 후 Esc를 다시 누릅니다.
• Ctrl+C를 두 번 눌러 셸로 종료합니다.

​

목록 구성

• Ctrl+T를 눌러 세션을 맨 위에 고정하고 유휴 상태일 때 프로세스를 계속 실행합니다
• Shift+↑ 또는 Shift+↓를 눌러 세션 순서 변경
• Ctrl+R을 눌러 세션 이름 바꾸기
• 그룹 헤더에서 Enter를 눌러 축소

• /resume이 id 또는 검색 용어를 명명합니다
• 뷰가 --cwd로 범위가 지정됩니다
• 뷰가 --safe-mode로 시작되었습니다
• 뷰가 --permission-mode 또는 --settings와 같은 플래그로 열렸습니다

​

세션 필터링

​

키보드 단축키

​

새로운 에이전트 디스패치

​

에이전트 뷰에서

• /exit 및 /quit는 에이전트 뷰를 닫습니다
• /logout은 로그아웃합니다
• /model은 디스패치 모델을 설정합니다
• /login은 세션에 연결하지 않고 다시 로그인할 수 있도록 로그인 대화 상자를 엽니다
• 기본 /resume 또는 별칭 /continue는 저장소의 과거 세션 선택기를 열어 하나를 백그라운드 세션으로 복구합니다. Claude Code v2.1.212 이상이 필요합니다

​

특정 디렉토리로 디스패치

• 해당 디렉토리에서 claude agents를 엽니다.
• 상위 디렉토리에서 claude agents를 열고 프롬프트에서 @<repo>로 하위 저장소를 언급합니다. @를 입력하면 이러한 대상이 나열됩니다:
  • 실행 디렉토리 아래 한 수준의 Git 저장소
  • 실행한 저장소의 등록된 git worktrees로, 디렉토리 트리 내부에 있으며, 체크아웃된 브랜치로 레이블이 지정됩니다. Claude가 .claude/worktrees/ 아래에 생성한 것들이 표시되며, 체크아웃된 브랜치로 레이블이 지정됩니다. git worktree add ../feature와 같이 저장소 외부에 추가된 Worktree는 나열되지 않습니다
  • 이미 목록에 세션이 있는 모든 디렉토리
  이름에 공백이 포함된 디렉토리는 나열되지 않습니다.
• 셸에서 디렉토리로 cd하고 claude --bg "<prompt>"를 실행합니다.

​

세션 내에서

​

세션을 백그라운드로 보내기

​

/fork로 세션 복사

• 모든 디스패치된 세션과 마찬가지로 복사본은 파일을 편집하기 전에 자신의 worktree로 이동합니다. 이 경우 확인은 복사본이 실행되는 위치를 언급하지 않습니다.
• 세션이 시작 후 연결된 worktree로 이동한 경우 복사본은 이동 전 세션이 있던 위치로 돌아가며, 제자리에서 편집하지 않는 한 자신의 worktree에서 코드 변경을 수행합니다. worktree가 브랜치에 체크아웃되어 있으면 해당 지시는 또한 작업을 기반으로 하는 복사본에 당신의 브랜치를 기반으로 새 브랜치를 만들도록 지시합니다. 당신의 브랜치는 당신의 worktree에서 체크아웃된 상태로 유지되기 때문입니다. 확인은 runs in the origin tree로 끝납니다.
• 주 작업 트리가 있는 저장소의 연결된 worktree 내부에서 세션을 실행한 경우 복사본은 해당 주 작업 트리에서 시작하며, 동일한 worktree 규칙이지만 브랜치 지시는 없습니다. 확인은 여기서도 runs in the origin tree로 끝납니다.
• 베어 저장소 레이아웃의 worktree 내부에서 실행된 세션은 반환할 주 작업 트리가 없으므로 복사본은 그대로 유지되며 확인은 edits this checkout으로 끝납니다. worktree 격리가 꺼져 있는 연결된 worktree 내부가 아닌 세션에서도 동일한 메모가 나타나며, 복사본이 열려 있는 파일을 편집하기 때문입니다.

​

백그라운드로 이동할 때 전달되는 것

• --mcp-config 및 --strict-mcp-config
• --settings
• --add-dir
• --plugin-dir
• --fallback-model
• --allow-dangerously-skip-permissions

​

셸에서

claude --bg "investigate the flaky SettingsChangeDetector test"

claude --agent code-reviewer --bg "address review comments on PR 1234"

claude --resume 1f0e2c9a-6d0b-4c11-9f39-2a77c1d4e8b5 --bg "pick up where you left off and finish the migration"

claude --bg --name "flaky-test-fix" "investigate the flaky SettingsChangeDetector test"

backgrounded · 7c5dcf5d · flaky-test-fix
  claude agents             list sessions
  claude attach 7c5dcf5d    open in this terminal
  claude logs 7c5dcf5d      show recent output
  claude stop 7c5dcf5d      stop this session

​

셸 명령 실행

claude --bg --exec 'pytest -x'

​

파일 편집이 격리되는 방식

• 세션이 이미 연결된 git worktree 내부에 있으며, Claude가 .claude/worktrees/ 아래에 생성했거나 다른 곳에서 git worktree add로 생성했는지 여부
• Claude가 편집하는 파일이 연결된 git worktree 내부에 있으며, 예를 들어 세션 또는 서브에이전트가 git worktree add로 생성한 것
• 작업 디렉토리가 git 저장소가 아니고 WorktreeCreate 훅이 구성되지 않음
• 쓰기가 작업 디렉토리 외부

{
  "worktree": {
    "bgIsolation": "none"
  }
}

• 커밋 및 푸시: Claude는 묻지 않고 커밋하며, 저장소에 원격이 있을 때 브랜치를 푸시합니다.
• 초안 풀 리퀘스트: Claude는 작업이 필요할 때 열며, #N 레이블이 행에 나타납니다.
• 절대 안 됨: main 또는 master로 푸시, 강제 푸시 및 병합.
• 당신의 git 지시가 우선합니다: 작업, CLAUDE.md 또는 메모리가 당신이 직접 커밋 또는 푸시를 처리한다고 말하면 Claude는 git을 당신에게 맡깁니다.

​

세션 삭제 시 제거되는 것

• 에이전트 뷰는 커밋되지 않은 변경 사항을 포함하여 제거하므로 유지하려는 변경 사항을 먼저 커밋합니다.
• claude rm은 커밋되지 않은 변경 사항이 있을 때 worktree를 유지하고 세션 행과 함께 유지합니다.
• 에이전트 뷰와 claude rm 모두 다른 실행 중인 세션이 사용 중이거나 잠금한 worktree를 제거하지 않으며, 다시 삭제해도 변경되지 않습니다. Claude Code는 worktree 및 세션을 유지하고 유지된 디렉토리와 이유의 이름을 지정합니다. 에이전트 뷰에서 세션의 행은 not deleted를 표시합니다. 다른 세션을 닫은 다음 다시 삭제합니다.
• 세션을 삭제할 때 worktree에 Claude Code가 다른 곳에 저장되었는지 확인할 수 없는 커밋이 있으면 Claude Code는 worktree 및 세션을 유지하고 메시지는 worktree의 브랜치와 푸시되지 않은 커밋 수를 지정합니다. 메시지는 또한 두 가지 방법을 제공합니다: 커밋을 푸시하거나 다시 삭제하여 버립니다. 원격의 커밋은 삭제를 차단하지 않습니다. 로컬 복사본의 origin 원격의 기본 브랜치에 있는 커밋도 마찬가지입니다. 해당 브랜치가 주 체크아웃(저장소 디렉토리 자체가 아닌 worktree)에서 체크아웃되어 있는 한. 그 거부 후 당신은 선택합니다:
  • 커밋을 유지하려면 푸시하거나 해당 기본 브랜치에 병합한 다음 세션을 다시 삭제합니다.
  • 버리려면 푸시하지 않고 다시 삭제합니다: 에이전트 뷰의 행에서 Ctrl+X 두 번을 누르거나 거부가 인쇄한 claude rm <id> --discard-unpushed 명령을 실행합니다. 이는 세션 및 worktree를 제거하고 브랜치와 함께 푸시되지 않은 커밋 및 커밋되지 않은 변경 사항을 버립니다.
  다시 삭제할 때 Claude Code는 거부가 표시한 것만 버립니다: worktree가 이후 커밋을 얻었으면 Claude Code는 다시 유지하고 업데이트된 상태를 표시합니다. 다른 완료된 세션의 기록이 worktree의 이름을 지정할 때도 다시 삭제할 때 유지됩니다. 커밋을 푸시한 다음 다시 삭제합니다.
• git이 더 이상 인식하지 않는 worktree(예: git worktree prune 후)는 삭제를 차단하지 않습니다. Claude Code는 세션을 삭제하고 디렉토리를 디스크에 남깁니다.
• git 또는 WorktreeRemove 훅이 worktree를 제거하지 못하면 Claude Code는 worktree 및 세션을 유지하고 메시지는 원인을 지정합니다. 훅의 경우 메시지는 exited 1과 같이 종료된 방식을 말하고 stderr의 시작을 인용합니다. 메시지는 또한 다음 중 어느 것을 수행할지 알려줍니다:
  • 에이전트 뷰의 행에서 Ctrl+X 두 번을 누르거나 claude rm 거부가 인쇄한 claude rm <id> --force-remove-worktree <worktree-id> 명령을 실행하여 어쨌든 디렉토리를 제거하려면 세션을 다시 삭제합니다. Claude Code는 디렉토리가 저장소의 연결된 worktrees 중 하나임을 확인할 수 있을 때만 이를 제공합니다. .claude/worktrees/ 아래에 커밋되지 않은 변경 사항이 없고, 추적된 파일에 대한 변경 사항이 없으며, 내부에 중첩된 저장소가 없고, 다른 세션의 기록이 이를 지정하지 않습니다. worktree의 브랜치는 저장소에 유지됩니다.
  • 커밋 또는 숨김 커밋되지 않은 변경 사항, 디렉토리를 사용 중인 것 닫기 또는 훅 수정과 같이 방해가 되는 것을 수정한 다음 세션을 다시 삭제합니다.
  • 디렉토리를 직접 제거한 다음 세션을 다시 삭제합니다.

• 에이전트 뷰는 버리기 전에 동일한 Ctrl+X 이중 누르기를 요청합니다. 훅으로 생성된 디렉토리의 경우 WorktreeRemove 훅을 실행하고, 없으면 삭제를 거부하고 세션을 유지합니다.
• claude rm은 세션 및 worktree를 유지하고 이유를 지정합니다.

​

모델 설정

/model opus
refactor auth
/model sonnet
run the test suite

• 셸에서 claude --bg와 함께 --model을 전달합니다.
• 실행 중인 세션에 연결하고 /model을 실행하여 전환합니다: 선택기에서 선택하거나 입력한 /model <name>은 선택기에서 s를 누르지 않는 한 새 세션의 기본값으로 저장됩니다. 세션 전용 전환은 세션이 다시 생성되면 유지됩니다.
• 프론트매터가 model 필드를 설정하는 서브에이전트를 디스패치합니다.

​

권한 모드, 모델 및 노력

​

설정 및 공급자

​

LLM 게이트웨이

• ← 또는 /background로 자신의 세션을 백그라운드로 이동합니다
• 세션을 현재 디렉토리로 디스패치합니다
• 현재 디렉토리에서 중지된 세션을 깨우거나 회신합니다

​

권한 모드

• /bg 또는 ←로 백그라운드로 이동: Claude Code는 세션이 있던 권한 모드를 유지하므로 acceptEdits 또는 auto로 전환한 세션은 분리 후에도 해당 모드에 유지됩니다
• ←로 열린 에이전트 뷰에서 디스패치: 대상의 자신의 구성이 먼저 오고, 다른 것이 설정하지 않을 때 온 세션의 권한 모드가 적용됩니다
• 셸에서 시작된 claude agents 또는 claude --bg에서 디스패치: 새 세션은 해당 디렉토리의 새 claude 세션이 시작되는 방식으로 시작되며, 디스패치 기본값에서 열린 에이전트 뷰에서 디스패치하지 않는 한. 세션이 시작되는 권한 모드는 순서를 나열합니다

1. 대상 디렉토리의 permissions.defaultMode. 두 소스 규칙이 적용됩니다:
   • auto 및 bypassPermissions는 관리 설정, --settings 파일 또는 ~/.claude/settings.json에서만 적용됩니다.
   • Claude Code는 온 세션이 있던 것보다 더 허용적인 모드를 선택하는 프로젝트의 .claude/settings.json 또는 .claude/settings.local.json에서 defaultMode를 거부합니다.
2. 온 세션의 권한 모드

​

디스패치 기본값

claude agents --permission-mode plan --model opus --effort high

​

재시작 전체에서 지속되는 것

​

설정, 플러그인 및 MCP 서버

claude agents --settings ./ci-settings.json --add-dir ../shared-lib

​

셸에서 세션 관리

​

세션을 JSON으로 나열

​

스크립트에서 세션 상태 읽기

​

백그라운드 세션이 호스팅되는 방식

​

감독자 프로세스

• 작업 중, 권한 프롬프트 또는 다른 대화 상자에서 일시 중지됨, 또는 연결됨: 프로세스가 계속 실행됩니다. 실행 중인 서브에이전트, 워크플로우 또는 모니터는 작업 중으로 간주됩니다.
• 완료되었거나 다음 메시지를 기다리는 중이며, 약 1시간 동안 연결되지 않음: 감독자가 리소스를 확보하기 위해 프로세스를 중지합니다. 질문을 하여 턴을 끝낸 세션은 다음 메시지를 기다리는 중으로 간주됩니다. 대화는 디스크에 저장되며, 다음에 연결하거나 답변할 때 세션은 중단된 위치에서 재개됩니다. Ctrl+T로 세션을 고정하여 프로세스를 계속 실행 상태로 유지합니다.
• 감독자가 실행 중인 동안 예기치 않게 종료됨: 감독자가 프로세스를 다시 시작합니다. ← 또는 /background로 백그라운드된 세션을 직접 종료하면(예: kill 사용) 다시 시작하는 대신 중지된 것으로 표시됩니다. 종료로 인해 끝난 세션의 경우 세션이 종료 후 실패 또는 중지로 표시됨을 참조하세요.
• 자동 업데이트 후: 감독자가 자신을 새 버전으로 다시 시작하고 유휴 세션을 백그라운드에서 이동합니다. 작업 중이거나, 입력을 기다리거나, 연결된 세션은 중단되지 않습니다.

​

상태가 저장되는 위치

​

에이전트 뷰 끄기

​

문제 해결

​

claude agents가 에이전트 뷰를 열지 않고 서브에이전트를 나열함

​

에이전트 뷰가 세션 없이 열림

​

백그라운드로 이동하면 Background this session? 대화 상자가 표시됨

• 이동할 수 없는 작업: 세션에 백그라운드 세션으로 이동할 수 없는 작업이 있습니다. 예를 들어 실행 중인 모니터와 같은 작업입니다. 대화 상자는 Claude Code가 중단할 작업의 이름을 지정하고, 별도로 이동할 작업의 개수를 세어줍니다.
• 실행 중인 서브에이전트가 있는 워크플로우: 동적 워크플로우에 여전히 실행 중인 서브에이전트가 있습니다. 워크플로우 자체는 이동되지만, 실행 중인 서브에이전트는 처음부터 다시 시작되며, 대화 상자는 개수를 표시합니다.
• 자동 아티팩트 답변: Claude가 아티팩트의 댓글에 자동으로 답변하고 있습니다. 이러한 답변은 백그라운드 세션에서 계속되며, 대화 상자는 이를 표시합니다.

​

프롬프트가 너무 짧아서 거부됨

​

머신 종료 후 세션이 실패 또는 중지로 표시됨

• 48시간 이내에는 세션이 실패로 표시됩니다. 연결하거나 답변하면 중단된 위치에서 다시 시작됩니다.
• 48시간 이후, 예를 들어 머신이 며칠 동안 꺼져 있었던 경우, 세션은 ended while the background service was off와 함께 중지로 표시됩니다. 행에서 Enter를 누르면 바닥글에 Press enter again to resume this session (it ended while the background service was off), or ctrl+x to delete it.이 표시됩니다. 같은 행에서 Enter를 다시 누르면 저장된 대화를 다시 시작합니다. 답변 또는 claude attach <id>는 바닥글 프롬프트 없이 다시 시작합니다.

​

세션을 열면 대화가 이미 열려 있다고 표시됨

• 예를 들어 claude --resume 또는 /resume으로 대화를 다시 시작한 터미널: 행은 Open in a terminal을 표시하고 거기서 계속하라는 힌트를 표시하며, 행을 열면 Can't open — this session is running in another terminal을 표시합니다. 해당 터미널에서 계속하거나 종료한 후 행을 다시 엽니다.
• 다른 비대화형 Claude Code 프로세스, 예를 들어 같은 대화를 위한 백그라운드 세션 프로세스가 아직 종료되지 않은 경우: 행을 열면 This conversation is already open in another running Claude session을 표시합니다. 해당 프로세스를 사용하거나 종료될 때까지 기다린 후 행을 다시 엽니다.

​

세션을 열면 저장된 트랜스크립트가 없다고 표시됨

​

터미널 호스트가 죽었거나 세션이 응답하지 않음

​

터미널 호스트 죽음

• 에이전트 뷰에서 행은 terminal host process died — press Enter to restart를 표시합니다. 행에서 Enter를 누르면 Claude Code는 새로운 호스트 프로세스에서 세션을 다시 시작합니다.
• 셸에서 claude attach <id>는 이미 실패로 표시된 세션을 다시 시작합니다. 그렇지 않으면 원인을 보고하고 종료하며, claude attach <id>를 다시 실행하라고 알려줍니다.

​

세션이 응답하지 않음

• 에이전트 뷰에서 바닥글은 Press enter again to restart this session — it isn't responding (its conversation is saved and resumes).를 표시합니다. 같은 행에서 Enter를 다시 누르면 Claude Code는 응답하지 않는 프로세스를 중지하고 세션을 다시 시작합니다; 두 번째 누름 없이는 아무것도 중지하지 않습니다.
• 셸에서 claude attach <id>는 원인을 보고하고 종료하며, claude stop <id>를 실행한 후 claude attach <id>를 실행하라고 알려줍니다.

​

세션이 시작되기 전에 possibly low memory 메모와 함께 실패함

​

에이전트 뷰에서 백그라운드 서비스가 응답하지 않음

claude daemon stop --any --keep-workers

​

Could not resolve authentication method 오류로 디스패치 실패

claude daemon stop --any --keep-workers

​

macOS에서 백그라운드 세션이 Desktop, Documents 또는 Downloads를 읽을 수 없음

​

macOS에서 백그라운드 세션이 로컬 네트워크 호스트에 도달할 수 없음

​

연결 후 세션이 응답이 느림

​

.claude/worktrees/가 채워지고 있음

​

제한 사항

• 속도 제한 적용: 백그라운드 세션은 대화형 세션과 동일하게 구독 사용량을 소모하므로 10개의 에이전트를 병렬로 실행하면 할당량을 약 10배 빠르게 소모합니다.
• 세션은 로컬입니다: 백그라운드 세션은 사용자의 머신에서 실행되며 머신이 절전 모드로 전환되어도 유지되지만 머신이 종료되면 중지됩니다.
• Claude에서 생성한 워크트리는 에이전트 뷰의 세션과 함께 삭제됩니다: 자체 워크트리에서 파일을 편집한 세션을 삭제하기 전에 변경 사항을 커밋합니다. 일부 삭제는 워크트리를 대신 유지합니다.

​

관련 리소스

• 에이전트를 병렬로 실행: 에이전트 뷰를 서브에이전트, 에이전트 팀 및 worktrees와 비교합니다
• 세션 간 메시징: 세션이 서로 발견 사항을 전달하도록 합니다
• 에이전트 팀: 서로 메시지를 주고받는 여러 세션을 조정합니다
• 웹의 Claude Code: 로컬 대신 관리되는 클라우드 환경에서 세션을 실행합니다

​

버전 기록