클로드 코드 백그라운드 실행 — 에이전트 뷰 사용법
클로드 코드를 백그라운드로 돌리는 방법은 세 가지입니다. ① 셸에서 claude --bg "작업 내용"으로 바로 띄우거나, ② 이미 쓰고 있는 세션에서 /background를 치거나, ③ claude agents로 에이전트 뷰를 열어 거기서 작업을 던지는 것입니다. 백그라운드 세션은 터미널을 닫아도 계속 돌아가고, 나중에 claude attach로 다시 들어가면 됩니다. 아래는 Claude Code 2.1.202 기준(2026년 7월 29일 확인)으로 명령·화면·주의점을 정리한 내용입니다.
claude --version으로 버전을 먼저 확인하세요. 화면과 단축키는 앞으로 바뀔 수 있습니다.
1. 백그라운드로 넘기는 세 가지 방법
| 방법 | 언제 쓰나 |
|---|---|
claude --bg "작업 내용" |
셸에서 바로 던지고 끝낼 때. 세션 ID를 출력하고 즉시 돌아옵니다. |
claude agents |
여러 작업을 던져 놓고 한 화면에서 상태를 볼 때. 입력창에 프롬프트를 치면 그때마다 새 세션이 하나씩 뜹니다. |
세션 안에서 /background 또는 빈 프롬프트에서 ← |
지금 하던 대화를 그대로 백그라운드로 넘기고 터미널을 비울 때. /fork는 복사본을 넘기고 현재 대화는 그대로 둡니다. |
주의할 점은 에이전트 뷰 입력창의 동작입니다. 프롬프트를 하나 더 치면 앞 세션에 이어서 말하는 게 아니라 두 번째 세션이 새로 시작됩니다. 이어 말하려면 그 줄을 골라 답장하거나 붙어야 합니다.
2. 에이전트 뷰 화면 읽는 법
claude agents를 실행하면 터미널 전체를 차지하는 목록이 뜹니다. 세션은 상태별로 묶이고, 손이 필요한 것이 위로 올라옵니다.
Needs input
✻ power-up design double jump or wall climb? 1m
Working
✽ collision detection Adding swept-AABB checks 2m
Completed
✻ title screen result: menu, options, credits done 9m줄 앞 아이콘은 색으로 세션 상태를, 모양으로 프로세스가 살아 있는지를 나타냅니다.
| 상태 | 뜻 |
|---|---|
| Working (움직이는 아이콘) | 도구를 실행하거나 답을 만드는 중 |
| Needs input (노랑) | 질문·권한 승인 등 내가 답해야 진행됨 |
| Idle (흐림) / Completed (초록) / Failed (빨강) / Stopped (회색) | 대기 / 정상 종료 / 오류 종료 / Ctrl+X·claude stop으로 중지됨 |
모양 ✻ vs ∙ |
✻는 프로세스가 살아 있는 상태, ∙는 프로세스가 끝난 상태입니다. ∙여도 열어서 이어 말하면 멈춘 지점부터 다시 시작합니다. |
각 줄의 한 줄 요약은 하이쿠급 모델이 만들어 줍니다. 세션이 일하는 동안에는 15초에 한 번 세션 출력만으로 갱신되고, 턴이 끝날 때 모델이 새로 씁니다. 이 요약도 토큰을 쓰는 짧은 요청이라는 점은 알아 두는 게 좋습니다.
3. 키보드 조작 — 확인·답장·붙기
| 키 | 하는 일 |
|---|---|
Space |
엿보기(peek) 패널. 마지막 출력이나 물어보는 질문만 보여 줍니다. 여기서 바로 답장할 수 있고, !로 시작하면 Bash 명령으로 보냅니다. |
Enter 또는 → |
붙기(attach). 전체 대화로 들어갑니다. 들어가면 자리 비운 동안의 요약을 먼저 보여 줍니다. |
← (빈 프롬프트에서) |
떼기(detach). 세션은 계속 돌아갑니다. Ctrl+Z는 처음 출발한 곳(셸 또는 에이전트 뷰)으로 돌아갑니다. |
Ctrl+X |
중지. 2초 안에 한 번 더 누르면 목록에서 삭제합니다. |
Ctrl+T / Ctrl+R / Ctrl+S |
고정 / 이름 변경 / 디렉터리별 묶기로 전환 |
떼는 동작(←, Ctrl+Z, /exit)은 세션을 끝내지 않습니다. 안에서 끝내려면 /stop입니다. 단축키 전반은 클로드 코드 단축키 글에 정리해 두었습니다.
4. 셸에서 관리하기 (스크립트용)
에이전트 뷰를 열지 않고도 셸에서 다룰 수 있습니다. 세션 ID는 claude --bg가 출력해 주고, ~/.claude/jobs/ 아래 디렉터리 이름이기도 합니다.
| 명령 | 하는 일 |
|---|---|
claude agents --cwd <경로> |
그 디렉터리 아래에서 시작한 세션만 봅니다(기본은 전체 프로젝트). |
claude agents --json |
세션 목록을 JSON 배열로 출력하고 종료합니다. TTY가 없어도 되어 스크립트에 씁니다. |
claude attach <id> |
그 세션을 이 터미널에서 엽니다. |
claude logs <id> |
최근 출력만 찍어 봅니다. |
claude stop <id> |
중지합니다. 대화는 남으므로 나중에 claude attach로 이어갑니다. |
claude respawn <id> · --all |
대화를 유지한 채 프로세스만 다시 띄웁니다. 클로드 코드를 업데이트한 뒤 새 바이너리로 옮길 때 씁니다. |
claude rm <id> |
목록에서 지웁니다. 이미 끝난 세션에도 됩니다(stop과 다른 점). |
claude daemon status |
백그라운드 세션을 돌리는 감독(supervisor) 프로세스 상태를 봅니다. |
백그라운드 세션을 한 번도 띄우지 않은 상태에서 감독 프로세스를 확인하면 이렇게 나옵니다.
$ claude daemon status
not running
bg sessions:
sock dir: /tmp/cc-daemon-501/xxxxxxxx
control.sock: unreachable (connect ENOENT ...)
bg workers: 0 in roster.json (control unreachable)
roster.json: absent
daemon.log: absentnot running은 고장이 아니라 아직 띄울 세션이 없다는 뜻입니다. claude agents나 claude --bg를 처음 실행하면 감독 프로세스가 새로 뜹니다.
5. --json 출력 읽기
실제로 claude agents --json을 돌리면 이런 모양의 배열이 나옵니다(경로·ID는 예시로 바꿨습니다).
[
{
"pid": 2750,
"cwd": "/Users/me/projects/my-app",
"kind": "interactive",
"name": "my-app-3f",
"sessionId": "0f2b...-uuid",
"startedAt": 1785500000000
}
]| 필드 | 설명 |
|---|---|
cwd · kind · startedAt |
항상 있습니다. kind는 interactive 또는 background, startedAt은 유닉스 밀리초입니다. |
id · state |
백그라운드 세션에만 붙습니다. state는 working·blocked·done·failed·stopped 중 하나입니다. |
sessionId · name |
sessionId는 전체 UUID로 claude --resume에 씁니다. 이름을 안 지은 세션은 my-app-3f처럼 디렉터리명 + 두 글자가 붙습니다. |
실제로 돌려 보면 대화형 세션만 있는 상태에서는 id·state 키가 아예 없습니다. 스크립트에서 이 값을 읽을 때는 키가 없을 수 있다는 전제로 다뤄야 합니다. 완료된 세션까지 보려면 --all을 붙입니다. 세션을 나중에 다시 여는 방법은 클로드 코드 이어서 하기 글에서 --continue·--resume와 함께 정리했습니다.
6. 파일이 겹치지 않게 — 워크트리 격리
여러 세션이 같은 저장소를 동시에 고치면 서로의 변경을 덮어씁니다. 에이전트 뷰는 이걸 막으려고 보낸 세션을 각자의 git 워크트리로 옮겨 작업하게 합니다.
7. 시작 전에 알아야 할 한계
- 쿼터는 세션 수만큼 나갑니다. 열 개를 동시에 돌리면 사용량도 대략 열 배로 빠집니다. 한도 확인은 클로드 코드 사용량 확인 글을 참고하세요.
- 세션은 내 컴퓨터에서 돕니다. 절전(sleep)은 견디지만 종료하면 멈춥니다. 클라우드에서 도는 게 아닙니다.
- 권한 질문은 그대로 옵니다. 백그라운드 세션이 승인을 기다리면
Needs input으로 올라옵니다. 승인 정책은 클로드 코드 권한 설정에서 미리 잡아 두면 덜 멈춥니다. - 리서치 프리뷰라 화면과 단축키가 바뀔 수 있습니다.
자주 묻는 질문 (FAQ)
Q. 터미널을 닫으면 백그라운드 세션도 죽나요?
아닙니다. 감독(supervisor) 프로세스가 따로 세션을 들고 있어서 에이전트 뷰를 닫아도, 셸을 닫아도 계속 돌아갑니다. 컴퓨터를 끄면 멈춥니다.
Q. 서브에이전트와 뭐가 다른가요?
서브에이전트는 한 대화 안에서 곁가지 작업을 대신 하고 요약만 돌려주는 일꾼입니다. 백그라운드 세션은 독립된 대화라서 내가 직접 열어 답하고, 각자 결과를 냅니다. 서브에이전트 쪽은 클로드 서브에이전트 사용법에서 다뤘습니다.
Q. 중지한 세션을 되살릴 수 있나요?
claude stop은 대화를 지우지 않습니다. claude attach <id>로 다시 열면 이어서 진행합니다. 목록에서 지웠더라도 대화 기록 자체는 로컬에 남아 claude --resume으로 찾을 수 있습니다.
Q. 세션 ID는 어디서 보나요?claude --bg가 출력해 주고, claude agents --json의 id 필드에도 있습니다. ~/.claude/jobs/ 아래 디렉터리 이름과 같습니다(백그라운드 세션을 한 번도 안 띄웠으면 이 폴더 자체가 없습니다).
마무리
정리하면 던지기는 claude --bg, 보기는 claude agents, 다시 들어가기는 claude attach 세 개면 시작할 수 있습니다. 처음에는 오래 걸리는 작업 하나(테스트 조사, 리팩터링, PR 리뷰)만 백그라운드로 넘겨 보고, 익숙해지면 개수를 늘리는 편이 안전합니다. 쿼터가 세션 수만큼 나가는 점과 세션 삭제 시 워크트리가 함께 지워지는 점만 기억하면 됩니다. 리서치 프리뷰라 세부 동작은 버전에 따라 달라질 수 있으니, 막히면 claude agents --help와 공식 문서를 함께 확인하세요.
📚 참고 출처 (2026년 7월 29일 확인 · Claude Code 2.1.202 기준)
· Claude Code — Manage multiple agents with agent view
· Claude Code — Run agents in parallel
COMMENTS