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

claude agents로 여는 에이전트 뷰는 모든 백그라운드 세션을 한 화면에서 보여줘요: 뭐가 실행 중이고, 뭐가 내 입력을 기다리고, 뭐가 끝났는지. 스크롤하며 트랜스크립트를 뒤지지 않아도 세션 상태를 한눈에 보고, 필요할 때만 개입하면 됩니다. 각 백그라운드 세션은 터미널이 붙어 있지 않아도 계속 도는 완전한 Claude Code 대화라서, 열었다 답하고 언제든 나갈 수 있어요. 이 문서는 퀵스타트, 세션 모니터링·필터링, 새 에이전트 파견, 셸에서 세션 관리, 격리, 백그라운드 호스팅까지 다룹니다.

출처: 공식문서

본문

에이전트 뷰는 당신이 매 단계를 지켜보지 않아도 되는 독립 작업이 여럿 있을 때 씁니다. 버그 수정, PR 리뷰, 플래키 테스트 조사 세 개를 세 행으로 파견하고 다른 창에서 계속 작업하다가, 행이 입력을 필요로 하거나 결과가 있을 때 확인하세요. 어떤 에이전트의 세션에 더 직접적으로 작업하고 싶으면 행에 붙어(attach) 전체 대화로 들어갑니다. 에이전트 뷰·서브에이전트·에이전트 팀·워크트리를 비교하려면 Run agents in parallel을 보세요.

에이전트 뷰는 Research preview 상태입니다. 인터페이스와 키보드 단축키는 기능이 진화하며 바뀔 수 있어요.

퀵스타트

에이전트 뷰 열기 — 셸에서 실행:

claude agents

디렉터리의 워크스페이스 신뢰 대화상자를 아직 수락하지 않았다면 claude와 같은 대화상자가 에이전트 뷰 전에 나타납니다. 거부하면 에이전트 뷰 없이 종료됩니다. 에이전트 뷰는 아래 입력과 세션이 시작되면서 채워지는 테이블로 열립니다. Esc로 셸에 복귀하세요. 세션은 내가 없는 동안 계속 돌고 다음에 열면 다시 나타나요.

세션 파견 — 작업을 설명하는 프롬프트를 치고 Enter를 누르면 새 백그라운드 세션이 그 작업으로 시작되어, 작업 중·나를 기다림·완료를 보여주는 행으로 나타납니다. 새 세션은 에이전트 뷰 헤더에 표시된 모델을 씁니다. 여기서 치는 모든 프롬프트는 각자 새 세션을 시작합니다. 여러 세션을 이렇게 병렬로 돌릴 수 있어요. 각 세션은 구독 할당량을 독립적으로 쓰므로 많이 파견하기 전에 Limitations를 보세요.
엿보기와 답장 — 방향키로 행을 선택하고 Space로 엿보기(peek) 패널을 엽니다. 세션의 최근 출력이나 대기 중 질문을 전체 트랜스크립트 없이 보여줍니다. 답을 치고 Enter로 에이전트 뷰를 떠나지 않고 보냅니다.
붙었다 떼기 — 행에서 Enter나 →로 붙어 전체 대화를 볼 수 있습니다. 세션은 전체 인터랙티브 Claude Code 세션으로 터미널을 차지합니다. 빈 프롬프트에서 ←로 떼고 테이블로 돌아갑니다.
기존 세션 가져오기 — 이미 열어둔 세션을 에이전트 뷰로 옮기려면 그 안에서 /bg를 실행하거나, 빈 프롬프트에서 ←를 눌러 백그라운드로 보내며 에이전트 뷰를 엽니다. 메시지가 없는 새 세션에서는 /bg가 먼저 메시지를 보내라고 하고, ←는 즉시 동작합니다. 세션은 계속 돌고 파견한 것들 옆에 행으로 나타납니다.

일반 claude 세션 안에서는 프롬프트 푸터의 ← 힌트가 기다리는 백그라운드 에이전트 수를 셉니다 (← 2 agents). 99를 넘으면 99+로 표시됩니다. 카운트는 터미널이 포커스된 동안 약 10초마다, 포커스가 돌아오면 즉시 갱신돼요.

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

claude agents를 실행해 에이전트 뷰를 엽니다. 전체 터미널을 차지하고 모든 세션을 상태별로 그룹화해 나열하며, 고정(pinned) 세션과 입력이 필요한 세션을 위에 둡니다. 각 행은 세션 이름, 현재 활동, 나이(세션 생성부터 카운트)를 보여줍니다. 기본적으로 모든 프로젝트에 걸쳐 시작한 모든 백그라운드 세션을 보여줍니다. 한 프로젝트로 좁히려면:

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

다른 터미널에 열어둔 인터랙티브 세션은 백그라운드로 보내기 전까지는 나타나지 않습니다. 세션이 스폰한 서브에이전트·팀메이트는 별도 행으로 나열되지 않아요.

세션 상태 읽기

각 행은 상태를 색과 애니메이션으로 보여주는 아이콘으로 시작합니다:

상태	아이콘	의미
Working	애니메이션	Claude가 도구를 실행하거나 응답 생성 중
Needs input	노랑	질문 답, 권한 결정, 샌드박스/MCP 입력 요청 같은 당신만 줄 수 있는 것을 기다림. 붙은 터미널이 필요한 명령(`/install-github-app`, `/mcp` 설정 목록)도 여기를 잡아둠
Idle	흐림	할 일이 없고 다음 프롬프트를 기다림
Completed	초록	작업 성공
Failed	빨강	오류로 종료
Stopped	회색	`Ctrl+X`·`claude stop`으로 중지, 외부에서 프로세스 종료, 백그라운드 서비스 꺼짐 중 종료

아이콘의 모양은 별도로 기반 프로세스가 도는지를 보여줍니다: ✻ 또는 애니메이션 ✽는 프로세스가 살아 즉시 답함, ∙는 프로세스가 종료됨(엿보기 가능, 답·붙으면 이어서 재시작), ✢는 /loop 세션이 반복 사이에 잠자는 것. 행 오른쪽의 #N/!N 라벨은 pull request·merge request 링크입니다.

에이전트 뷰가 열려 있는 동안 로컬 백그라운드 세션이 입력을 필요로 하거나 끝나거나 실패하면 구성한 터미널 알림 채널로 알림을 보냅니다. 백그라운드 세션은 작업을 계속하는 데 터미널이 필요 없어요. 별도 슈퍼바이저 프로세스가 돌리므로 에이전트 뷰를 닫거나 셸을 닫아도 파견한 작업은 계속됩니다.

행 요약

각 행의 한 줄 요약은 Haiku급 모델로 생성돼 트랜스크립트를 열지 않아도 세션이 뭘 하는지·뭘 필요로 하는지·뭘 만들었는지 알려줍니다. 작업 중 행은 최대 15초마다 한 번 세션 자체 최근 출력에서 갱신되고, 각 턴이 끝날 때 모델이 새 요약을 씁니다. 끝-턴 요약과 중간 재작성은 정상 프로바이더를 통한 짧은 Haiku급 요청 하나로, 세션과 같은 데이터 사용 조건으로 청구됩니다. Haiku급 모델이 없는 서드파티 프로바이더·게이트웨이에서는 세션의 메인 모델을 대신 쓰고, ANTHROPIC_DEFAULT_HAIKU_MODEL로 선택할 수 있습니다.

Pull request 상태

세션이 pull request를 열면 Claude Code가 행 오른쪽에 PR로 연결된 라벨을 붙입니다: #1234(PR), !1234(GitLab MR). 하이퍼링크 감지를 못 해도(SSH·tmux) 링크를 방출하고, FORCE_HYPERLINK=0으로 일반 텍스트로 렌더링합니다. 세션이 둘 이상 PR에 연결되면 3 PRs처럼 개수를 보여줍니다. PR 번호 색: 노랑(체크·리뷰 대기 또는 실패), 초록(체크 통과·차단 리뷰 없음), 보라(병합됨), 회색(Draft·닫힘). PR로 끝나는 작업은 번호가 초록이 됐을 때 리뷰·병합하세요.

엿보기와 답장

선택한 행에서 Space로 엿보기 패널을 엽니다. 행이 터미널 끝에서 자르는 문장으로 시작하는데, 어떤 문장이냐는 상태에 달렸어요: 나를 기다리는 세션은 묻는 정확한 질문(입력 위), 끝난 세션은 결과, 작업 중 세션은 전체 상태 문장. 연결된 PR이 그다음에 나열됩니다. 대부분의 경우 엿보기 패널로 충분해서 전체 트랜스크립트를 열 필요가 없습니다.

엿보기 패널에서 답을 치고 Enter로 그 세션에 보냅니다. 미리 정의된 선택지가 있는 질문은 번호 목록으로 표시되고 번호 키로 고를 수 있어요. 권한 프롬프트는 번호 선택지 없이 텍스트로 표시됩니다. Tab으로 제안 답을 채워 편집 후 보낼 수 있고, 답을 !로 시작하면 Bash 명령으로 보냅니다.

PermissionRequest/PreToolUse 훅이 검증할 수 없는 출력을 반환하면 행이 훅 이벤트와 hook output invalid: 및 검증 오류를 보류 요청 텍스트 앞에 표시합니다. 전달 불가능한 답(백그라운드 서비스 도달 불가)은 저장돼 세션 프로세스가 다시 시작될 때 다음 프롬프트로 보내집니다. !로 시작하는 답은 저장되지 않아요. ↑/↓로 패널을 닫지 않고 옆 세션을 보고, →로 붙을 수 있습니다.

세션에 붙기

선택한 행에서 Enter나 →로 붙습니다. 에이전트 뷰가 전체 인터랙티브 세션으로 대체되고, Claude가 내가 없는 동안 일어난 일의 짧은 리캡을 올립니다. 붙어 있는 동안 /install-github-app와 /mcp 설정 목록이 정상 동작하며, 아무도 안 붙어 있으면 이 명령들은 대화상자를 열 수 없어 세션이 Needs input에 open this session to manage MCP servers 같은 행으로 나타납니다.

붙은 세션은 항상 fullscreen 모드로 렌더링됩니다(백그라운드 세션엔 스크롤백이 없으므로). PgUp/PgDn/마우스 휠로 스크롤하고 Ctrl+O로 트랜스크립트 모드. 빈 프롬프트에서 ←나 /exit로 떼고 에이전트 뷰로 돌아갑니다. Windows에서 붙은 직후 약 0.5초 안에 ←를 누르면 Ambiguous ←, press again to detach가 표시될 수 있어요. Ctrl+Z도 떼지만 출발 지점(에이전트 뷰 또는 셸)으로 갑니다. Ctrl+C는 붙는 동안 표준 인터럽트 동작을 유지합니다(응답·! 셸 명령 취소, 떼지 않음). 떼는 건 절대 백그라운드 세션을 멈추지 않습니다: ←, Ctrl+Z, /exit, 더블 Ctrl+C·Ctrl+D 모두 실행 상태로 둬요. 세션을 끝내려면 그 안에서 /stop을 실행하세요.

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

포그라운드에서 도는 세션(에이전트 뷰에서 붙은 게 아니라 터미널에서 시작한 것)에서 빈 프롬프트의 ←는 백그라운드로 보내며 그 행이 선택된 채 에이전트 뷰를 엽니다. 프롬프트의 마지막 텍스트를 지운 직후나 프롬프트 히스토리 이동 직후 ←를 누르면 확인을 요청합니다: 첫 번째 누름은 Press ← again to open agents, 두 번째가 전환합니다.

←가 포그라운드 세션을 백그라운드로 보내면 에이전트 뷰가 리스트 위에 Your conversation moved to the background를 보여주고 그 행이 미리 선택됩니다. Enter로 재개, Esc로 전환을 취소해 대화로 복귀, Ctrl+C 두 번으로 셸로 종료. 여기에서 이 단축키는 leftArrowOpensAgents 설정으로 끌 수 있습니다 (/config).

목록 정리

에이전트 뷰는 세션을 그룹화해 입력이 필요한 것을 위로 두고 Ready for review와 Needs input이 Working·Completed 위에 옵니다. 이 그룹 이름은 위 상태와 1:1 대응하지 않아요. Ctrl+S로 디렉터리 기준 그룹화로 전환합니다(선택은 유지). 그룹 안에서: Ctrl+T로 세션을 위에 고정하고 유휴 중에도 프로세스 실행 유지, Shift+↑/Shift+↓로 순서 재배치, Ctrl+R로 이름 변경, 그룹 헤더에서 Enter로 접기.

목록에서 세션을 제거하려면 Ctrl+X로 중지하고 2초 안에 다시 Ctrl+X로 삭제합니다. 그룹 헤더에서 Ctrl+X는 확인 후 그 그룹의 모든 세션을 삭제합니다. 삭제는 무엇을 제거하는지에 나온 유지 케이스를 빼고 목록에서 세션을 제거하며, 대화 트랜스크립트는 항상 로컬 머신에 남아 claude --resume으로 쓸 수 있습니다.

v2.1.212 이상에서 세션을 되살리려면 파견 입력에 /resume을 입력합니다. 이 저장소의 과거 세션(목록에서 삭제한 것 포함)을 최신순으로 고르는 피커가 열립니다. 이미 행이 있는 세션은 나열되지 않아요. 피커는 순수 /resume에만 열립니다 — ID나 검색어를 명명하는 /resume, --cwd 스코프, --safe-mode, --permission-mode·--settings 같은 플래그로 연 뷰에서는 attach to a session to run it 힌트를 보여줍니다.

화면에 안 들어가는 완료 세션은 … N more 행으로 접힙니다. 실패·PR 열린 세션은 항상 보입니다.

세션 필터링

파견 입력에 입력해 파견 대신 필터링하세요:

필터	표시
`a:<name>`	그 이름 에이전트를 실행 중인 세션
`s:<state>`	해당 상태 세션, 예: `s:working`. `s:blocked`는 당신을 기다리는 모든 것
`#<number>` 또는 PR/MR URL	그 PR/MR에 작업 중인 세션
다른 URL	첫 프롬프트에 그 URL이 포함된 세션

키보드 단축키

?로 모든 단축키를 봅니다. 주요 단축키: ↑/↓(행 이동), Enter(선택 세션 붙기, 또는 입력에 텍스트가 있으면 파견), Space(엿보기 패널 열기·닫기), Shift+Enter(파견 입력에 새 줄), Ctrl+Enter(즉시 파견·붙기), →(붙기), Alt+1..Alt+9(포커스 세션 디렉터리의 세션 1–9에 붙기), Tab(빈 입력 시 서브에이전트 탐색), Ctrl+S(상태·디렉터리 그룹화 전환), Ctrl+T(고정·고정 해제), Ctrl+R(이름 변경), Ctrl+G($VISUAL/$EDITOR로 파견 프롬프트 열기), Ctrl+J(새 줄), Ctrl+X(중지; 2초 안에 다시 누르면 삭제), Shift+↑/Shift+↓(순서 재배치), Esc(엿보기 닫기·입력 지우기·종료), Ctrl+C(입력 지우기; 두 번 종료), ?(모든 단축키).

Ctrl+S, Ctrl+T, Ctrl+G는 keybindings.json을 따릅니다. agents:switchView·agents:togglePin 액션(Agents 컨텍스트)과 chat:externalEditor 바인딩(Chat 컨텍스트)으로 재바인딩할 수 있어요. 다른 단축키는 재바인딩할 수 없습니다.

새 에이전트 파견

에이전트 뷰에서

에이전트 뷰 아래 입력에 프롬프트를 치고 Enter로 새 백그라운드 세션을 시작합니다. 이름은 Haiku급 모델이 쓰는 짧은 라벨로 자동 생성됩니다(Ctrl+R로 나중에 변경). 이미지를 프롬프트에 붙여 스크린샷·다이어그램을 포함할 수 있습니다. 800자 또는 세 줄보다 긴 붙여넣기 텍스트는 [Pasted text #N] 자리표시자로 접혀 입력을 한 줄로 유지합니다.

프롬프트의 일부에 접두사를 붙이거나 언급해 세션이 시작되는 방식을 제어하세요:

입력	효과
`<agent-name> <prompt>`	첫 단어가 커스텀 서브에이전트 이름과 일치하면 그 서브에이전트가 frontmatter 구성으로 세션 메인 에이전트로 실행
`@<agent-name>`	프롬프트 어디서나 커스텀 서브에이전트를 언급해 메인 에이전트로 실행
`@<repo>`	저장소를 언급해 거기서 세션 실행
`/<command>`	프롬프트로 파견할 스킬·명령 제안
`! <command>`	Claude 세션 대신 셸 명령을 백그라운드 작업으로 실행. 붙고·보고·떼는 행으로 나타남
`#<number>` 또는 PR/MR URL	그 PR/MR에 작업 중 세션이 있으면 새로 파견하지 않고 그 행 선택

에이전트 뷰 자체에서 실행되는 소수의 명령: /exit·/quit(에이전트 뷰 닫기), /logout(로그아웃), /model(파견 모델 설정), /login(로그인 대화상자), 순수 /resume(또는 /continue)(과거 세션 피커).

@name이 서브에이전트와 형제 저장소 모두와 일치하면 서브에이전트가 우선합니다. 반복 작업을 스킬로 만들면 프롬프트 재입력 없이 에이전트 뷰에서 같은 워크플로우를 반복 시작할 수 있어요.

특정 디렉터리로 파견

새 세션은 에이전트 뷰를 연 디렉터리에서 실행됩니다. 다른 디렉터리를 타깃하려면: 그 디렉터리에서 claude agents 열기, 부모에서 @<repo>로 자식 저장소 언급(@를 치면 한 단계 아래 git 저장소, 실행 저장소의 등록된 git 워크트리, 이미 목록에 세션이 있는 디렉터리 나열), 또는 셸에서 cd 후 claude --bg "<prompt>" 실행. 디렉터리 기준 그룹화일 때 파견은 선택 행의 디렉터리로 프롬프트를 보냅니다.

세션 안에서

두 명령이 작업을 백그라운드로 옮깁니다: /background는 현재 대화를 보내고 터미널을 해방하고, /fork는 당신이 그 자리에서 계속 작업하는 동안 사본을 보냅니다.

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

/background(별칭 /bg)로 현재 대화를 백그라운드 세션으로 옮깁니다. /bg run the test suite and fix any failures처럼 프롬프트를 넘겨 먼저 한 번 더 지시할 수 있습니다. /bg 실행 시 Claude가 응답 중이면 그 응답은 백그라운드 세션에서 계속됩니다. 서브에이전트·백그라운드 셸 명령·워크플로우·모니터 같은 백그라운드 작업이 아직 돌고 있는 세션을 종료하면 즉시 종료 대신 Background work is running 대화상자가 표시됩니다.

/fork로 세션 복사

/fork로 현재 대화를 새 백그라운드 세션으로 복사하는 동안 원본은 계속 실행됩니다. 사본은 그 시점까지의 모든 것을 담아 시작하고 모델·권한 모드·effort 수준·추가한 디렉터리·"don't ask again" 권한 부여도 이어받습니다. 복사 후 두 대화는 독립적입니다.

/fork는 v2.1.212 이상 필요합니다. v2.1.161~v2.1.211에서는 /fork가 forked subagent(지금은 /subtask)를 시작합니다. /fork open a draft pull request with the work so far처럼 프롬프트를 넘기면 사본이 즉시 작업을 시작합니다. 프롬프트가 없으면 사본은 첫 지시를 기다리고 행에 space to send it a prompt를 보여줍니다.

사본은 어디서 시작하나—격리: 일반 파견 세션처럼 사본은 파일 편집 전 자기 워크트리로 이동. 세션이 시작 후 연결된 워크트리로 이동했다면 사본은 이동 전 위치에서 시작하고 runs in the origin tree로 확인이 끝납니다. 링크된 워크트리 안에서 세션을 시작했다면 사본은 메인 워킹 트리에서 시작합니다. bare 저장소 레이아웃의 워크트리에서 시작한 세션은 돌아갈 메인 워킹 트리가 없어 사본이 그 자리에 남고 확인이 edits this checkout로 끝납니다. 사본이 상속하지 않을 런치 플래그(교체된 시스템 프롬프트, --tools 허용 목록)로 시작한 세션은 포크할 수 없습니다.

백그라운드로 보낼 때 넘어가는 것

백그라운드는 저장된 대화에서 재개하는 새 프로세스를 시작하고 진행 중 작업이 거기로 이동합니다: 실행 중 백그라운드 셸 명령, 백그라운드 서브에이전트, 다이내믹 워크플로우, /loop로 만든 예약 작업, artifact 댓글 자동 답장이 모두 이어받아 계속 실행됩니다. 진행 중 작업을 이어받는 대신 멈추려면 CLAUDE_DISABLE_ADOPT=1을 설정하세요. 모니터처럼 넘어갈 수 없는 작업은 중지되고, 그런 작업이 실행 중이면 Background this session? 대화상자가 표시됩니다.

백그라운드에 들어가면 세션은 새 서브에이전트·모니터·백그라운드 명령을 시작할 수 있고 그것들은 이후의 detach·reattach를 넘어 계속됩니다. 원래 런치의 구성 플래그가 백그라운드 세션으로 이어집니다: --mcp-config, --strict-mcp-config, --settings, --add-dir, --plugin-dir, --fallback-model, --allow-dangerously-skip-permissions. --allow-dangerously-skip-permissions를 이어받으면 bypassPermissions가 도달 가능하게 유지되지만 새로 부여하는 것은 없습니다.

셸에서

--bg(또는 긴 형태 --background)로 곧장 백그라운드로 가는 세션을 시작하세요:

claude --bg "investigate the flaky SettingsChangeDetector test"

프롬프트는 위치 인자이고 -p 값이 아닙니다. Claude Code는 세션이 생기기 전에 --bg와 -p/--print의 결합을 거부합니다. 정의한 특정 서브에이전트(예: code-reviewer)를 메인 에이전트로 실행하려면 --bg를 --agent와 결합하세요:

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

이름이 서브에이전트와 일치하지 않으면 시작이 실패합니다. 기존 대화를 백그라운드에서 계속하려면 전체 세션 ID를 --resume으로 전달하세요:

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

--bg를 --continue·순수 --resume·이름·파일 경로와 결합하면 항상 사본을 시작합니다. --name으로 표시 이름을 설정할 수 있습니다:

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

백그라운드 후 Claude는 세션의 짧은 ID와 관리 명령을 출력합니다:

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 세션 대신 백그라운드 작업으로 셸 명령을 실행하려면 --exec를 전달하세요:

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

에이전트 뷰에서는 파견 입력의 첫 문자로 !를 입력해 같은 종류의 작업을 파견합니다. 명령은 PTY 기반 작업으로 실행되고 에이전트 뷰에서 행으로 나타나며 최근 출력 한 줄이 상태입니다. 모델은 호출되지 않고 출력은 어떤 세션에도 보내지지 않습니다. 출력을 보려면 행에 붙거나 Space로 엿보거나 claude logs <id>를 실행하세요. 행과 출력은 명령 종료 후 약 5분 뒤 자동 정리됩니다.

파일 편집이 어떻게 격리되는지

모든 백그라운드 세션(에이전트 뷰·/bg·claude --bg 출처)은 작업 디렉터리에서 시작합니다. 파일을 편집하기 전에 Claude는 세션을 .claude/worktrees/ 아래 격리된 git 워크트리로 이동시켜, 병렬 세션이 같은 체크아웃을 읽되 각자 자기 것에 씁니다.

Claude는 다음 경우 워크트리를 건너뜁니다: 세션이 이미 연결된 git 워크트리 안일 때, 편집하는 파일이 연결된 git 워크트리 안일 때, 작업 디렉터리가 git 저장소가 아니고 WorktreeCreate 훅이 없을 때, 쓰기가 작업 디렉터리 밖일 때. git 워크트리가 비현실적인 저장소의 격리를 끄려면 worktree.bgIsolation을 "none"으로 설정하세요:

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

git 저장소 밖에서는 세션이 작업 디렉터리에 직접 쓰고 서로 격리되지 않으므로 같은 파일을 편집하는 병렬 세션 파견을 피하세요. 다른 VCS를 쓰면 WorktreeCreate 훅을 구성해 git처럼 편집을 격리하세요.

백그라운드 세션이 Claude가 들어간 워크트리에서 코드 변경을 만들면, Claude Code는 세션·워크트리를 삭제해도 작업이 살아남도록 끝내기 전에 작업을 보존하라고 지시합니다: 커밋·푸시(질문 없이 커밋, 리모트 있으면 브랜치 푸시), Draft pull request(작업이 요구할 때, 행에 #N 라벨), Never(main·master 푸시, force-push, 병합). 당신의 git 지시가 우선합니다(작업·CLAUDE.md·memory가 직접 커밋·푸시한다고 하면 Claude는 git을 당신에게 맡깁니다). 어떤 작업이든 Claude는 뭘 했고 작업이 어디 있는지(경로·브랜치·PR·답) 보고하는 보고로 끝냅니다.

세션 삭제가 제거하는 것

에이전트 뷰에서 Ctrl+X 두 번이나 claude rm으로 세션을 삭제합니다. 아래 유지 케이스를 빼고 세션은 목록을 떠납니다. 트랜스크립트는 claude --resume으로 머신에 남고 제거는 슈퍼바이저 재시작에 걸쳐 유지됩니다.

Claude가 세션용으로 만든 워크트리에 일어나는 일: 에이전트 뷰는 커밋 안 된 변경 포함 제거(먼저 보관할 것을 커밋하세요), claude rm은 커밋 안 된 변경이 있으면 워크트리와 세션 행을 유지, 둘 다 다른 실행 세션이 쓰거나 잠근 워크트리는 제거하지 않음(행에 not deleted), 워크트리의 커밋이 다른 곳에 저장됐는지 확인할 수 없을 때(미푸시 커밋) 워크트리와 세션을 유지하며 브랜치 이름과 미푸시 커밋 수를 명명. 그 후 선택: 푸시 후 다시 삭제하거나, claude rm <id> --discard-unpushed로 커밋을 버리고 다시 삭제. git이 더 이상 인식하지 못하는 워크트리(git worktree prune 후)는 삭제를 막지 않고 디렉터리는 디스크에 남깁니다. git이나 WorktreeRemove 훅이 워크트리를 제거하지 못하면 워크트리와 세션을 유지하고 원인을 명명합니다.

모델 설정

에이전트 뷰 헤더의 모델 이름은 파견 기본값입니다. 입력에서 시작하는 새 세션은 이 모델을 사용하며, 사용자 설정의 model 설정에서 옵니다. 에이전트 뷰 전체의 파견 기본값을 덮어쓰려면 --model을 전달하세요. 에이전트 뷰 안에서 파견 입력에 /model 다음에 모델 이름을 치고 Enter로 바꿉니다. 헤더가 그 모델과 (session) 마커로 갱신되고 이후 파견 세션이 그 모델을 씁니다. /model default로 덮어쓰기를 지웁니다. 이 오버라이드는 현재 claude agents 실행 동안만 지속되고 settings 파일에 쓰지 않습니다.

각 백그라운드 세션은 다른 모델로 돌 수 있습니다: 셸에서 claude --bg에 --model 전달, 실행 세션에 붙어 /model 실행, or model 필드를 설정한 서브에이전트 파견.

권한 모드, 모델, effort

백그라운드 세션은 settings·프로바이더·권한 모드·모델·effort를 어디서·어떻게 파견했는지에서 가져옵니다.

Settings·프로바이더: 백그라운드 세션은 실행하는 디렉터리에서 settings를 읽습니다(그 디렉터리에 claude를 시작한 것처럼). 프로젝트 settings의 env 값(ANTHROPIC_MODEL·프로바이더 변수)이 그 디렉터리의 모든 백그라운드 세션에 적용됩니다. 파견한 셸의 PATH로도 실행됩니다.

LLM gateway: LLM gateway를 쓰면 게이트웨이 변수를 settings 파일의 env 블록에 두세요. 셸에만 ANTHROPIC_BASE_URL을 export했다면, 슈퍼바이저가 같은 게이트웨이를 export한 셸에서 시작됐을 때만(그리고 ←·/background로 백그라운드, 현재 디렉터리로 파견, 현재 디렉터리의 정지 세션 깨우기인 경우) 백그라운드 세션에 닿습니다.

권한 모드는 세션 시작 방식에 달렸습니다: /bg·←로 백그라운드면 세션이 있던 권한 모드를 유지. claude agents(셸에서 시작)나 claude --bg로 파견하면 그 디렉터리의 새 claude 세션이 시작하는 방식으로 시작. ←로 연 에이전트 뷰에서 파견한 세션은 첫 번째 적용 항목에서 가져옵니다: (1) 타깃 디렉터리의 permissions.defaultMode — 단 auto·bypassPermissions는 managed settings·--settings 파일·~/.claude/settings.json에서만 유효하고, 프로젝트 .claude/settings.json/.claude/settings.local.json의 defaultMode가 온 세션보다 더 관대하면 거부됩니다. (2) 온 세션의 권한 모드. 관대함 순서: plan → Manual·dontAsk → acceptEdits·auto(서로보다 관대) → bypassPermissions.

파견 기본값: 에이전트 뷰에서 파견하는 모든 세션의 기본값을 설정하려면 열 때 --permission-mode, --model, --effort, --agent 중 아무거나 전달하세요:

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

--agent는 파견 프롬프트가 @name이나 첫 단어로 명명하지 않을 때 쓰는 서브에이전트를 설정합니다. claude agents는 --dangerously-skip-permissions(--permission-mode bypassPermissions의 축약)과 --allow-dangerously-skip-permissions도 받습니다. --restricted로 파견 세션 모두를 restricted mode로 시작할 수 있습니다 (v2.1.248 이상). 활성 기본값이 파견 입력 아래 푸터에 표시됩니다.

bypassPermissions 모드는 보고 있지 않은 세션이 승인 없이 행동하게 하므로, claude --bg --permission-mode bypassPermissions는 인터랙티브하게 claude --dangerously-skip-permissions를 한 번 실행해 면책 공지를 수락하기 전까지 거부됩니다.

재시작에 걸쳐 유지되는 것: 백그라운드 세션에 고른 권한 모드·모델·effort, 그리고 가지고 다니는 구성 플래그가 슈퍼바이저가 프로세스를 멈추고 재시작할 때 모두 유지됩니다. 세션이 effort를 --effort·/effort가 아니라 settings에서 가져왔다면, Claude Code는 세션 프로세스를 시작할 때마다 settings를 다시 읽습니다. /rename이나 Ctrl+R로 설정한 이름도 유지됩니다. 붙어 있는 동안 Ctrl+S로 숨긴 프롬프트도 세션에 유지됩니다(붙여넣은 내용은 제외).

Settings, 플러그인, MCP 서버

에이전트 뷰는 settings·플러그인·MCP 서버·추가 디렉터리를 로드하는 claude와 같은 구성 플래그를 받습니다. 에이전트 뷰는 --settings와 --plugin-dir을 자신에게 적용하고 모든 구성 플래그를 파견 세션에 전달합니다.

플래그	효과
`--settings <file-or-json>`	에이전트 뷰와 파견 세션의 settings 덮어쓰기
`--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 같은 공백 구분 형태는 지원되지 않습니다. --settings·--plugin-dir은 agents 앞뒤 어디든, --add-dir·--mcp-config는 agents 뒤에 두세요.

셸에서 세션 관리

모든 백그라운드 세션에는 셸에서 쓸 수 있는 짧은 ID가 있습니다. claude --bg로 세션을 시작할 때 출력되고, 각 세션의 ID는 ~/.claude/jobs/ 아래의 디렉터리 이름입니다.

명령	목적
`claude agents`	에이전트 뷰 열기
`claude agents --cwd <path>`	`<path>` 아래 시작된 세션으로 스코프해 열기
`claude agents --json`	세션을 JSON 배열로 출력하고 종료. 목록 참조
`claude attach <id>`	이 터미널에서 세션에 붙기
`claude logs <id>`	세션의 최근 출력 출력
`claude stop <id>`	세션 중지. `claude kill`도 가능
`claude respawn <id>`	실행·정지 세션 재시작(업데이트된 바이너리 반영용). 저장된 대화 재개
`claude respawn --all`	실행 중인 모든 세션 재시작
`claude rm <id>`	목록에서 세션 제거(안전할 때 Claude가 만든 워크트리 포함). 트랜스크립트는 `claude --resume`으로 유지
`claude rm <id> --discard-unpushed <commit>@<worktree-id>`	미푸시 커밋 때문에 거부된 삭제 실행, 워크트리·브랜치·커밋 폐기 (v2.1.260 이상)
`claude rm <id> --force-remove-worktree <worktree-id>`	git/`WorktreeRemove` 훅이 워크트리를 못 지워 거부된 삭제 실행, 디렉터리는 지우고 브랜치는 저장소에 유지 (v2.1.268 이상)
`claude daemon status`	슈퍼바이저 상태·버전·소켓 디렉터리·워커 수 출력
`claude daemon stop --any`	슈퍼바이저와 호스팅 백그라운드 세션 중지. `--keep-workers`로 백그라운드 세션은 남김

세션을 JSON으로 목록

claude agents --json은 활성 세션을 JSON 배열로 출력하고 종료합니다. --all로 완료 백그라운드 세션도, --cwd <path>로 디렉터리 한정. 각 항목: cwd·kind·startedAt(항상), id(백그라운드), state(working·blocked·done·failed·stopped), pid·status(busy·waiting·idle, 프로세스 살아있는 동안), waitingFor(status가 waiting일 때: permission prompt, input needed, sandbox request, worker request, dialog open), sessionId·name(설정 시).

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

claude agents --json이 Claude Code 밖에서(스테이터스 바·스케줄러·백그라운드 감독 세션) 세션 상태를 읽는 지원되는 방법입니다. claude agents --json --all을 폴링하고 각 항목의 state, status, waitingFor를 읽으세요. 턴을 끝내고 다음 지시를 기다리는 세션은 done으로 읽히지 blocked가 아닙니다. blocked는 항상 계속하기 전에 당신에게 뭔가가 필요하다는 뜻입니다.

~/.claude/jobs/<id>/ 아래 파일은 안정적인 인터페이스가 아닙니다. 세션이 자기 말로 진행 상황을 보고하게 하려면 state.json을 편집하는 대신 $CLAUDE_JOB_DIR/tmp 아래에 자체 파일을 쓰게 하세요.

백그라운드 세션이 어떻게 호스팅되는지

Claude Code는 에이전트 뷰에 나열된 모든 세션을 현재 붙어 있든 아니든 백그라운드 세션으로 취급합니다. 반대로 claude를 직접 실행해 시작한 세션은 그 터미널에 묶여 닫으면 끝납니다(← 등으로 백그라운드로 보내지 않으면). /status로 세션 종류를 확인할 수 있습니다.

슈퍼바이저 프로세스

슈퍼바이저는 에이전트 뷰나 터미널을 닫아도 백그라운드 세션이 계속 돌게 하는 백그라운드 서비스입니다. Claude Code는 처음 세션을 백그라운드하거나 에이전트 뷰를 열 때 시작하며 직접 관리할 필요가 없습니다. 각 세션은 슈퍼바이저 아래의 자체 Claude Code 프로세스이고, 프로세스에 일어나는 일은 상태에 달렸습니다:

작업 중, 권한 프롬프트·대화상자에서 일시정지, 붙어 있음: 프로세스는 계속 실행. 실행 중 서브에이전트·워크플로우·모니터도 작업으로 침
끝났거나 다음 메시지를 기다리며 약 1시간 붙어 있지 않음: 슈퍼바이저가 리소스를 위해 프로세스를 중지. 대화는 디스크에 남고 다음에 붙거나 답하면 이어서 재개. Ctrl+T로 고정해 실행 유지
슈퍼바이저 실행 중 예기치 않게 종료: 슈퍼바이저가 프로세스 재시작. ←·/background로 직접 백그라운드한 세션을 kill로 끝내면 재시작 대신 stopped로 표시
자동 업데이트 후: 슈퍼바이저가 새 버전으로 재시작하고 유휴 세션을 백그라운드로 이동. 작업·대기·붙은 세션은 방해받지 않음

세션 프로세스가 멈추거나 재시작하면, Claude가 시작한 백그라운드 셸 명령·다이내믹 워크플로우·백그라운드 서브에이전트는 다음 프로세스로 이어지고, 서브에이전트가 시작한 실행 중 모니터·셸 명령은 프로세스와 함께 멈춥니다.

상태가 저장되는 곳

CLAUDE_CONFIG_DIR을 설정하지 않으면 상태는 ~/.claude 아래 저장됩니다. ~/.claude/daemon.log(슈퍼바이저 로그), ~/.claude/daemon/roster.json(실행 중 백그라운드 세션 목록, 재시작 후 재연결용), ~/.claude/jobs/<id>/state.json(세션 상태, 파일 파싱 대신 claude agents --json으로 읽기), ~/.claude/jobs/<id>/tmp/(세션 스크래치 디렉터리, Write·Edit이 여기선 프롬프트 없음, 세션 삭제 시 제거). 각 백그라운드 세션에는 CLAUDE_JOB_DIR 환경변수가 ~/.claude/jobs/<id>로 설정되어, 실행하는 셸 명령이 병렬 세션과 충돌 없이 $CLAUDE_JOB_DIR/tmp에 임시 파일을 쓸 수 있습니다.

에이전트 뷰 끄기

백그라운드 에이전트와 에이전트 뷰를 완전히 끄려면 disableAgentView 설정을 true로 하거나 CLAUDE_CODE_DISABLE_AGENT_VIEW 환경변수를 설정하세요. 관리자는 managed settings로 강제할 수 있습니다.

트러블슈팅(요약)

claude agents가 에이전트 뷰 대신 서브에이전트를 나열 — 환경에서 에이전트 뷰를 못 씀. claude update 실행, 끄졌는지 확인
Background this session? 대화상자 — 백그라운드가 멈추거나·재시작하거나·무인 실행할 진행 중 작업이 세션에 있음. /tasks로 확인 후 확인하거나 Stay 선택
너무 짧은 프롬프트 거부 — 4자 미만은 Too short 힌트로 거부. 작업 설명을 쓰세요
종료 후 세션 failed/stopped 표시 — 48시간 안에 failed(붙거나 답하면 재개), 48시간 지나면 stopped(ended while the background service was off, Enter 다시 누르면 재개). 절전만으로는 세션을 멈추지 않아요
대화가 이미 열려 있다는 메시지 — 두 프로세스가 같은 트랜스크립트에 쓸 수 없음. 다른 터미널에서 재개했거나 다른 프로세스가 잡고 있음
저장된 트랜스크립트 없음 메시지 — 첫 응답이 끝나기 전에 다른 대화에서 백그라운드된 정지 세션. Enter 다시 누르거나 claude respawn <id>
터미널 호스트 사망/응답 없음 — 슈퍼바이저가 원인 표시 후 재시작 제공. 셸 명령을 실행하는 행은 절대 재시작하지 않음(명령 재실행 방지)
possibly low memory 노트 — host 메모리 부족으로 프로세스가 시작 전 종료. 메모리 확보 후 재시도
백그라운드 서비스 미응답 — 슈퍼바이저가 멈춤. claude daemon stop --any --keep-workers로 중지하고 다음 claude agents가 새로 시작. Windows에서 미응답이면 taskkill /PID <pid>
Could not resolve authentication method — 워커가 자격증명을 못 받음. /login·API 키 확인 후 claude daemon stop --any --keep-workers
macOS의 Desktop/Documents/Downloads 못 읽음 — 시스템 설정 > Privacy & Security > Files and Folders에서 접근 허용
macOS 15+ 로컬 네트워크 차단 — Local Network 권한 허용
.claude/worktrees/가 차오름 — git worktree list로 남은 항목을 찾아 git worktree remove <path>로 제거

제한

Rate limit 적용: 백그라운드 세션은 인터랙티브와 같은 사용량을 소비하므로 10개 병렬 실행은 할당량을 약 10배로 씀
세션은 로컬: 백그라운드 세션은 내 머신에서 실행. 절전엔 보존되지만 종료 시 멈춤
Claude가 만든 워크트리는 에이전트 뷰에서 세션과 함께 삭제됨: 자기 워크트리에서 파일을 편집한 세션을 삭제하기 전에 변경을 커밋하세요

더 알아보기

병렬 에이전트 실행 — 에이전트 뷰·서브에이전트·에이전트 팀·워크트리 비교
크로스세션 메시징 — 세션끼리 결과 전달
에이전트 팀 — 서로 메시지하는 여러 세션 조율
Claude Code on the web — 로컬 대신 관리 클라우드 환경에서 세션 실행