claude --bg
백그라운드로 돌린 세션을 확인할 때, 짧은 영숫자 ID를 목록에서 가져와 복사하는 수고는 v2.1.290 버전부터 줄어들었습니다. 바로 claude attach와 claude logs가 ID 대신 세션 이름(의 일부)을 받을 수 있게 되었기 때문입니다. 다만, 동일하게 '백그라운드 세션을 다루는 명령어'라 하더라도, claude stop과 claude rm은 여전히 ID만 받습니다. 어떤 명령어에서 이름이 사용 가능하고, 어디서 ID가 필요한지 절차의 흐름에 따라 정리합니다.
대상 독자는 Claude Code를 CLI로 사용하며, 긴 작업을 --bg로 백그라운드에 돌리기 시작했거나(또는 돌리고 싶은) 개발자입니다.
기사 내용은 2가지 종류로 나뉩니다.
| 구분 | 내용 | 근거 |
|---|
| 실기 확인 결과 | v2.1.293의 --help 출력, 존재하지 않는 ID를 전달했을 때의 에러 및 종료 코드, claude agents --json이 빈 배열을 반환하는 것, 비 TTY 환경에서의 claude agents 동작 | |
| 2026-10-08 JST에 npm에서 설치한 v2.1.293으로 실행한 생 출력 | | |
| 공식 문서 기술 | --bg로 시작된 세션에 실제로 attach/logs하는 흐름, detach 작업, 자동 정지 조건 등 | |
| Agent view (공식 문서) | | |
검증 환경은 HOME을 빈 디렉터리로 전환하고 인증되지 않은 상태였으며, 작업 디렉터리 역시 신뢰할 수 없습니다. 따라서 claude --bg는 'Workspace not trusted'로 멈추었기 때문에, 세션을 실제로 시작하여 attach하는 부분은 확인하지 못했습니다. 이 부분은 공식 문서의 기술 내용으로 소개합니다.
이 기사를 읽으면 다음을 할 수 있게 됩니다.
claude --bg로 시작된 세션의 최신 출력을 claude logs "<이름 일부>"로 확인하기 -claude attach "<이름 일부>"로 같은 세션을 로컬 터미널에 열고, 멈추지 않고 빠져나오기 - 정리( claude stop / claude rm )와 스크립트 연동(claude agents --json)에서는 ID를 사용하기
전체적인 흐름은 다음과 같습니다. 이름으로 지정할 수 있는 것은 '보는' 쪽의 2개 명령어에 한정되며, '멈추거나 지우는' 쪽은 여전히 ID를 사용한다는 점이 그림 좌우의 차이점입니다.
이름 지정은 v2.1.290 버전 이후 기능입니다. 2026-10-08 JST 시점의 npm dist-tags는 다음과 같았으며, latest는 2.1.293, stable은 2.1.285였습니다 (npm: @anthropic-ai/claude-code).
$ npm view @anthropic-ai/claude-code dist-tags --json
{ "stable": "2.1.285", "latest": "2.1.293", "next": "2.1.294" }
여기서 놓치기 쉬운 점은, npm의 stable 태그(2026-10-08 JST 시점에서는 2.1.285)가 v2.1.290보다 이전 버전을 가리키고 있다는 것입니다. 이 버전에서는 이름 지정이 미지원했을 것입니다 (stable은 동작하는 태그이므로, 읽는 시점에는 이미 진전되었을 가능성이 있습니다). 로컬의 버전은 claude --version으로 확인할 수 있습니다.
$ npm i @anthropic-ai/[email protected] ; claude --version
added 2 packages, and audited 3 packages in 7s
2.1.293 (Claude Code)
v2.1.293의 claude --help에서 백그라운드 세션 관련 부분만 발췌한 것입니다.
--bg, --background Start the session in the background and
return immediately. Prints the id that
`claude attach`, `logs`, `stop` and `rm`
...
인수 표기법에 차이가 있습니다. attach와 logs
사용법은 <id|name>이며, stop (별칭: kill)과 rm은 <id>를 사용합니다. 개별 도움말 페이지에서도 같은 구분이 나타나며, 이름에 공백을 포함할 때의 작성 방법도 안내되어 있습니다.
$ claude attach --help
Usage: claude attach <id|name>
Open the background session in this terminal. ← returns to agent view, Ctrl+Z drops back to your shell. The session keeps running either way. Part of the session name works in place of the id. Put a name with spaces in quotes.
$ claude logs --help
Usage: claude logs <id|name>
Print the background session's recent terminal output. Part of the session name works in place of the id. Put a name with spaces in quotes.
$ claude stop --help
Usage: claude stop <id>
Stop a background session. Its conversation is kept; resume it later with `claude attach <id>`.
작성자가 v2.1.293의 도움말을 확인한 범위에서는, 이름(부분 일치)이 통하는 것은 표시/연결 관련 2개의 명령어뿐이었습니다. 부분 일치는 여러 세션에 적용될 수 있기 때문에, 취소할 수 없는 작업(정지/삭제)에는 모호함이 없는 ID를 요구하도록 설계된 것으로 보입니다. 다만 이는 도움말 표기에서 추론한 것이며 공식적인 이유가 적혀 있는 것은 아닙니다.
여기부터는 공식 문서의 설명입니다. Agent view 페이지에 따르면, --bg를 사용하면 세션이 즉시 백그라운드로 이동하며, 프롬프트는 위치 인수로 전달합니다. -p / --print와의 병용은 거부됩니다. 문서에 기재된 시작 예시는 다음과 같습니다.
claude --bg "investigate the flaky SettingsChangeDetector test"
claude --bg --name "flaky-test-fix" "..."
claude --resume <id> --bg "..."
...
나중에 이름으로 지정할 계획이라면, --name을 붙여서 시작해 두면 찾기 쉽습니다. 시작 직후에는 다음과 같은 출력이 표시된다고 공식 문서에 예시되어 있습니다 (아래는 문서의 예시이며 작성자 환경의 출력은 아닙니다).
backgrounded · 7c5dcf5d · flaky-test-fix
claude agents list sessions
claude attach 7c5dcf5d open in this terminal
...
7c5dcf5d가 ID이고, flaky-test-fix가 이름입니다. 문서에 따르면, ID는 ~/.claude/jobs/ 아래의 디렉토리 이름에 해당합니다.
신뢰되지 않은 디렉토리에서 --bg를 실행하면 v2.1.293에서는 다음 오류로 멈췄습니다. 한 번 그 디렉토리에서 claude를 시작하여 신뢰 확인을 승인한 후 다시 실행해야 합니다. $ claude --bg "say hi" Workspace not trusted. Run exttt{claude} in <dir> once and accept the trust prompt, then retry.
실행 중인 세션은 claude agents로 목록화할 수 있습니다. 다만 대화형 터미널(interactive terminal)이 필요하며, 출력을 파이프에 흘리는 것과 같은 비 TTY 상황에서는 다음 메시지로 종료됩니다. 종료 코드는 0이었습니다.
$ claude agents
'claude agents' requires an interactive terminal (stdout is not a TTY) — use 'claude agents --json' for a machine-readable listing.
스크립트에서 사용할 경우 --json을 사용합니다. 도움말 설명은 다음과 같으며, TTY가 필요하지 않습니다.
--cwd <path> Show only background sessions started under <path>
--json Print active sessions (interactive and background) as a JSON array and exit (for scripting; does not require a TTY)
--all With --json: also include completed background sessions
세션이 하나도 없는 인증되지 않은 환경에서는 빈 배열이 반환되었습니다.
$ claude agents --json
[]
공식 문서에 따르면, --json의 각 요소는 cwd, kind, startedAt, id, state, pid, status, waitingFor, sessionId, name을 가지며, state는 working, blocked, done, failed, stopped 중 하나입니다. 문서에서는 스크립트의 경우 ~/.claude/jobs/를 직접 파싱하지 말고 claude agents --json을 사용하도록 안내하고 있습니다. 종료된 세션까지 포함하고 싶을 때는 --all을 추가합니다.
claude agents 자체에 --add-dir나 --mcp-config를 전달하는 경우, agents 뒤쪽에 배치해야 합니다. 앞에 배치하면 공식 문서에 주석으로 알려진 바와 같이 unknown option이 됩니다.
claude logs는 세션의 최근 터미널 출력을 보여주는 것만 하는 명령어입니다. attach와 달리 터미널을 점유하지 않기 때문에, "현재 어디까지 진행되었는지"를 확인할 용도에 적합합니다.
v2.1.290 버전 이후부터는 이름의 일부로도 지정할 수 있습니다. 공식 문서의 예시는 다음과 같습니다.
claude logs "auth refactor"
공식 문서에는 주의할 점이 한 가지 있습니다. --exec나 !로 실행한 셸 작업(shell job)의 출력은 메모리에만 유지되며, 명령어 종료 후 약 5분 뒤에 사라집니다. 테스트 결과처럼 나중에 다시 보고 싶은 출력은 파일로 저장하는 것이 더 확실합니다.
claude attach는 백그라운드 세션을 현재 터미널에서 완전 인터랙티브하게 엽니다. 공식 문서에 따르면, 화면은 항상 전체 화면으로 표시되며, 자리를 비운 동안 무슨 일이 일어났는지 요약(recap)이 표시됩니다.
claude attach "flaky-test-fix"
attach 사용 시 헷갈리기 쉬운 부분이 종료(exit) 방법입니다. 공식 문서에서는 다음 작업을 수행해도 세션이 멈추지 않는다고 설명합니다.
- 빈 프롬프트에서
← / /exit / Ctrl+Z
Ctrl+C 또는 Ctrl+D를 2회
v2.1.293의 claude attach --help에는 ←는 agent view로 돌아가고, Ctrl+Z는 셸(shell)로 돌아간다는 차이점도 적혀 있습니다 ("← returns to agent view, Ctrl+Z drops back to your shell. The session keeps running either way."). 어느 방법으로 나가더라도 세션은 계속 실행됩니다. attach 중에 세션 자체를 멈추고 싶을 때는 /stop을 사용합니다.
정리(cleanup) 관련 명령어들은 ID 지정이 필요합니다. 역할의 차이를 도움말과 공식 문서를 통해 정리하면 다음과 같습니다.
| 명령어 | 받을 인자 | 남는 것 |
|---|
claude stop <id> (kill) | ID만 | 대화는 디스크에 남아 claude attach <id>로 재개할 수 있다 |
claude rm <id> | ID만 | 목록에서 사라진다. 트랜스크립트(transcript)는 claude --resume으로 계속 사용할 수 있다 |
claude respawn <id> / --all | ID 또는 --all | 세션을 재시작하고 현재의 Claude Code 바이너리로 다시 실행한다 |
이 표에서 파악할 것은, stop은 일시 정지에 가깝고, rm 역시 대화 자체는 삭제하지 않는다는 점입니다. 완전히 작업을 버리는 작업은 아닙니다.
rm에는 worktree(git의 작업 트리)와 관련된 옵션이 있습니다. 도움말 발췌는 다음과 같습니다 (행 안의 (...)는 조사 메모 시점에서의 생략입니다).
$ claude rm --help
Usage: claude rm <id> [--discard-unpushed <commit>@<worktree-id>] [--force-remove-worktree <worktree-id>]
Delete a background session and its worktree. Unlike `stop`, works on already-exited sessions.
...
공식 문서에 따르면, worktree에 커밋되지 않은 변경 사항이 남아있는 경우 rm은 worktree와 목록의 항목을 남깁니다. 두 옵션 모두 '직전의 claude rm <id>가 보고한 값을 전달하는' 형식이기 때문에, 처음부터 붙여서 실행하는 것이 아니라 한 번 rm을 실행하여 보고를 읽고 난 후에 사용하는 흐름이 됩니다.
Claude Code를 업데이트한 후에는, 실행 중인 세션이 오래된 바이너리 상태로 남아있게 됩니다. claude respawn --all을 사용하여 모든 세션을 최신 버전으로 전환할 수 있습니다.
$ claude respawn --help
Usage: claude respawn <id>|--all
Restart a background session (or all of them) so it picks up the current Claude binary.
v2.1.290에서 추가된 것은 claude attach / claude logs라는 명령어 자체가 아니라, 'ID 대신 이름의 일부를 전달할 수 있게 된 것'입니다. GitHub 릴리스 노트에는 다음과 같이 쓰여 있습니다.
Added
claude attach <name>
and
claude logs <name>
: part of a session name works in place of the id
출처: Release v2.1.290 · anthropics/claude-code
같은 릴리스에는 백그라운드 세션 관련 수정 사항도 포함되어 있습니다.
claude respawn이 저장된 트랜스크립트가 없는 세션에 과거 메시지를 재전송하는 버그 수정 - 유휴 상태로 백그라운드화된 세션이 "no saved transcript"가 되는 버그 수정
claude agents에서 바쁜(busy) 백그라운드 세션으로 보낸 /model, /effort, /rename 등이 즉시 적용되도록 변경
이름 지정은 '이름으로 찾을 수 있다'는 전제가 필요하므로, 시작 시 --name을 붙여두는 운영 방식과 함께 생각하는 것이 자연스럽습니다. 참고로 attach / logs가 처음 도입된 버전은 이번에 확인한 자료로는 특정할 수 없습니다.
존재하지 않는 ID나 이름을 전달하면, v2.1.293에서는 logs도 attach도 동일한 메시지를 출력하며 종료 코드 1로 끝났습니다.
$ claude logs nonexistent
No job matching 'nonexistent'. Run 'claude agents' to list running sessions.
exit=1
...
반면, 비 TTY 환경의 claude agents
종료 코드를 0으로 설정하고 안내 메시지를 출력하며 종료합니다. 셸 스크립트에서 '세션 존재 여부'를 판별하려면 claude agents의 종료 코드는 신뢰할 수 없습니다. 가장 확실한 방법은 claude agents --json의 출력을 이용하는 것입니다 ( --json은 인터랙티브 세션을 포함하므로, 백그라운드 작업만 계산하려면 kind가 background인 항목으로 필터링해야 합니다).
공식 문서에 따르면, 저장된 transcript(대화 기록)가 없는 세션에는 attach 할 수 없습니다. 유휴 상태에서 백그라운드로 전환된 세션이 이 상태가 되는 버그는 v2.1.290에서 수정되었으므로, 그 이전 버전에서 문제가 발생한다면 먼저 업데이트한 후 다시 확인해야 합니다.
공식 문서에서는 agent view의 행에 대해 다음과 같은 메시지가 나타날 수 있다고 설명합니다. 예를 들어, 다른 터미널에서 동일한 대화를 열어둔 상태가 아닌지 확인하는 것입니다.
공식 문서에 따르면, 종료되었거나 입력 대기 상태로 약 1시간 동안 attach되지 않은 세션은 supervisor가 중단됩니다. Ctrl+T으로 고정(pin)된 세션은 대상에서 제외됩니다. 머신을 종료하면 역시 중지되지만, 절전 모드(sleep)에는 견딜 수 있습니다.
공식 문서의 내용을 바탕으로 운영에 영향을 미치는 사항들을 정리했습니다.
| 항목 | 내용 |
|---|
| 실행 위치 | 세션은 자신의 머신에서만 작동합니다 (클라우드에 맡기는 것이 아님) |
| ... | |
| |
사용량 제한 항목은 놓치면 곤란한 부분입니다. --bg는 쉽게 늘릴 수 있는 반면, 공식적으로 10개를 나열하면 소비량이 약 10배가 된다고 명시되어 있습니다. 이름 지정으로 '어떤 것이 무엇인지' 파악하기 쉬워진 만큼, 사용하지 않는 세션은 stop으로 중지하는 습관과 병행하는 것이 안전합니다.
백그라운드에서 작동하는 상주 프로세스(daemon)의 상태는 claude daemon status|logs|stop --any로 확인할 수 있습니다. 세션을 시작하지 않은 v2.1.293 환경에서는 claude daemon stop --any가 no daemon running을 반환했습니다.
본문 초반에 다루었던 '어떤 명령어로 이름 사용이 가능한지'에 대한 답은 v2.1.293의 도움말에 그대로 나와 있습니다.
claude logs / claude attach는 <id|name>을 사용합니다. 이름 일부로 자주 사용하며, 공백을 포함하는 이름은 따옴표로 묶어야 합니다 -
claude stop / claude rm은 <id>만 사용합니다. 중지하거나 삭제하는 작업에서는 ID를 확인한 후 실행해야 합니다.
스크립트의 경우 claude agents --json을 사용하며, ~/.claude/jobs/는 파싱하지 않습니다.
실제 사용 흐름으로 정리하면, 시작 시 --name을 붙이고, 상태 확인은 claude logs "이름", 직접 개입하고 싶을 때는 claude attach "이름"으로 진입하여 ←로 빠져나오고, 정리만 할 때는 claude agents로 ID를 확인한 후 stop 또는 rm을 사용하는 분담 구조가 됩니다. npm의 stable 태그(2026-10-08 JST 기준 2.1.285) 버전을 사용하고 있다면, 이름 지정이 포함되는 v2.1.290 이상 버전으로 올라갈 때까지는 ID 지정 방식이 유지된다는 점에 주의해야 합니다.
- Claude Code Agent View 입문 — 여러 세션을 한 화면에서 관리하는 CLI 대시보드
- Claude Code, Opus 서브 에이전트만 거부하는 deny 규칙을 검증함
- SessionStart 훅(hook)이 무거우면 원격 세션 전체가 끊기던 문제
- Agent view (Claude Code 공식 문서) (절차 3~7・문제 해결・제약 사항에서 인용)
- Release v2.1.290 · anthropics/claude-code (“v2.1.290에서 바뀐 것”에서 인용)
- @anthropic-ai/claude-code (npm) (절차 1의 버전 확인)
