에이전트 뷰

에이전트 뷰(agent view)는 claude agents 명령으로 여는 관제 화면으로, 여러 Claude Code 세션을 한 표에 올려놓고 돌아가는 모양을 지켜보다가 손이 필요한 세션에만 끼어들게 해 줍니다. 버그 수정·PR 리뷰·플래키 테스트 조사를 각각 한 줄(row)로 던져놓고 다른 일을 하다가, 어느 줄이 입력을 기다리거나 결과를 내놓았을 때만 돌아오면 되는 식입니다.

배경 참조

이 문서는 MoAI-ADK가 올라타 있는 플랫폼인 Claude Code 자체를 다루는 배경 자료입니다. MoAI-ADK 자체 기능은 사이드바 위쪽 섹션에서 다룹니다.

정보

한 줄 요약: 트랜스크립트를 일일이 스크롤하는 대신, 실행 중·대기 중·완료된 모든 백그라운드 세션을 하나의 표로 보고 필요한 순간에만 끼어듭니다.

에이전트 뷰는 터미널 한 곳에 묶이지 않고 계속 도는 백그라운드 세션 (background session)을 한 화면에서 관리하는 인터페이스입니다. 각 백그라운드 세션은 그 자체로 완전한 Claude Code 대화이며, 터미널을 닫아도 별도의 감독 프로세스가 실행을 이어받아 줍니다. 그래서 서로 무관한 일거리를 여러 개 던져놓고 다른 작업을 하다가, 어느 세션이 입력을 기다리거나 결과를 내놓았을 때 돌아오면 됩니다.

에이전트 뷰는 리서치 프리뷰 (research preview) 단계이며 Claude Code v2.1.139 이상에서 동작합니다. claude --version으로 버전을 확인하세요. 인터페이스와 단축키는 기능이 발전하면서 바뀔 수 있습니다.

Claude Code에는 작업을 병렬로 벌리는 수단이 여럿 있는데, 에이전트 뷰는 그 가운데 “서로 무관한 풀 세션을 여럿 띄워놓고 결과만 회수"하는 자리를 차지합니다.

에이전트 뷰가 존재하는 이유는, Claude Code v2.1.198부터 백그라운드 실행이 기본값이 되었기 때문입니다. 런타임은 결과를 당장 이어 쓰지 않아도 되는 세션을 백그라운드로 돌리고, 결과가 필요해지는 순간에만 포어그라운드로 끌어올립니다. 에이전트 뷰는 바로 이 백그라운드 세션들을 한곳에서 지켜보는 관제창입니다.

백그라운드 세션이 권한이 필요한 도구(예: Bash, WebFetch)를 만나면, 그 프롬프트는 메인 세션 화면에 표시됩니다. v2.1.186부터는 프롬프트에 어느 서브에이전트가 물어보는 건지 이름까지 함께 뜨며, Esc로 해당 호출 하나만 거부할 수 있습니다. 긴 백그라운드 작업을 시작하기 전에 자주 쓰는 도구를 settings.json 허용 목록에 미리 넣어두면 프롬프트 빈도를 크게 줄일 수 있습니다.

에이전트 뷰를 열면 터미널 전체를 차지하면서 모든 세션을 상태별 그룹으로 나열합니다. 입력을 기다리는 세션과 고정(pin)한 세션이 맨 위로 올라오고, 각 줄은 세션 이름·현재 활동·마지막 변경 경과 시간을 보여줍니다.

Needs input
  ✻ power-up design     needs input: double jump or wall climb?     1m

Working
  ✽ collision detection Edit src/physics/CollisionSystem.ts          2m
  ✢ playtest level 3    run 12 · all checkpoints cleared          in 4m

Completed
  ✻ title screen        result: menu, options, and credits done      9m
  ∙ sound effects       result: 14 SFX exported to assets/audio       4h

각 줄의 맨 앞 아이콘은 색과 애니메이션으로 세션 상태를 나타냅니다.

아이콘 모양은 내부 프로세스가 살아 있는지를 따로 알려줍니다. ✻(또는 애니메이션 ✽)은 프로세스가 살아 있어 즉시 응답한다는 뜻이고, ∙은 프로세스가 종료된 상태(여전히 들여다보거나 답장·연결할 수 있으며 Claude가 중단 지점부터 이어함), ✢은 /loop 세션이 반복 사이에 대기 중임을 뜻합니다.

각 줄의 한 줄 요약은 Haiku 계열 모델이 생성합니다. 그래서 트랜스크립트를 열지 않고도 세션이 지금 무엇을 하는지·무엇을 원하는지·무엇을 만들었는지 알 수 있습니다. 작업 중인 세션은 최대 15초에 한 번, 그리고 턴이 끝날 때마다 요약을 갱신합니다.

세션이 PR을 열면 줄 오른쪽 끝에 PR #1234 같은 라벨이 붙고, 하이퍼링크를 지원하는 터미널에서는 링크가 됩니다. PR 번호는 상태에 따라 색이 다릅니다.

대부분의 작업에서는 이 열이 결과를 회수하는 지점이 됩니다. PR 번호가 초록색으로 바뀌면 리뷰 후 머지하면 됩니다. ! pytest -x처럼 입력 앞에 !를 붙이면 셸 명령을 백그라운드 작업으로 던질 수도 있습니다. 이때는 모델을 호출하지 않고 명령 한 줄만 실행되며, 최근 출력 라인이 상태로 표시됩니다.

세션이 띄운 서브에이전트나 에이전트 팀 팀원은 따로 줄이 잡히지 않습니다. 산출물과 진행은 부모 세션 줄의 요약과 출력에 합쳐져 보입니다. 세부 내용을 보려면 해당 세션을 들여다보거나 연결해서 전체 대화로 확인합니다.

참고로 v2.1.219부터 서브에이전트 중첩이 다시 기본 활성화되어, 한 백그라운드 세션이 깊이 3까지 중첩 spawn을 벌일 수 있습니다(CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1로 끌 수 있음). 에이전트 뷰는 이 중첩 구조까지 줄마다 펼쳐 보여주지는 않고, 가장 바깥 세션 기준으로 상태를 표시합니다.

에이전트 뷰는 사용자가 매 단계를 지켜보지 않아도 Claude가 알아서 진행할 수 있는, 서로 독립적인 작업이 여러 개일 때 빛을 발합니다.

• 장시간 작업 모니터링: 플래키 테스트 조사처럼 오래 걸리는 작업을 던져놓고 다른 창에서 일하다가, 줄이 입력 필요나 결과 상태로 바뀌면 돌아옵니다. 백그라운드 세션은 터미널이나 셸을 닫아도 감독 프로세스 덕분에 계속 돌아갑니다.
• 병렬 작업 추적: 버그 수정·PR 리뷰·테스트 조사를 세 줄로 동시에 디스패치하고 한눈에 상태를 비교합니다. 파일 편집은 세션마다 .claude/worktrees/ 아래 격리된 워크트리 (worktree)로 갈라지므로, 같은 체크아웃을 읽되 쓰기는 각자 따로 합니다.
• 여러 프로젝트 한 화면 관리: 기본적으로 모든 프로젝트의 백그라운드 세션이 한 표에 나타납니다. 한 프로젝트로 좁히려면 claude agents --cwd ~/projects/my-app처럼 디렉터리를 지정합니다.

각 세션은 구독 사용량을 독립적으로 소모합니다. 즉 에이전트 10개를 병렬로 돌리면 할당량이 약 10배 빠르게 줄어드니, 한꺼번에 많이 디스패치하기 전에 사용량 한도를 염두에 두세요. 병렬화는 시간을 사는 대신 토큰을 지불하는 거래입니다. MoAI-ADK가 병렬 팬아웃을 읽기 전용 조사·리뷰에 먼저 쓰고 쓰기 작업은 순차로 돌리는 것도, 안전과 함께 이 비용 구조를 감안한 선택입니다.

기본 흐름은 디스패치 → 관찰 → 들여다보고 답장 → 연결의 순환입니다.

flowchart TD
    A["claude agents 실행
에이전트 뷰 열기"] --> B["프롬프트 입력 + Enter
백그라운드 세션 디스패치"]
    B --> C["표에서 상태 관찰
Working / Needs input / Completed"]
    C --> D["Space
들여다보기 패널 + 답장"]
    C --> E["Enter 또는 →
전체 대화로 연결"]
    E --> F["← (빈 입력)
분리하고 표로 복귀"]
    F --> C

새 백그라운드 세션은 세 가지 경로로 시작합니다.

# 1) 에이전트 뷰를 열고 하단 입력창에 프롬프트를 입력한 뒤 Enter
claude agents

# 2) 셸에서 곧장 백그라운드로 시작
claude --bg "investigate the flaky SettingsChangeDetector test"

# 3) 특정 서브에이전트를 메인 에이전트로 지정
claude --agent code-reviewer --bg "address review comments on PR 1234"

에이전트 뷰 입력창에 넣는 프롬프트는 매번 새 세션을 시작합니다. 기존 세션에 이어 보내는 것이 아니므로, 진행 중인 대화를 백그라운드로 보내려면 세션 안에서 /background(별칭 /bg)를 실행하거나 빈 입력 상태에서 ←를 누릅니다.

세 번째 방식처럼 서브에이전트 정의를 메인 에이전트로 지정해 디스패치할 때는, 해당 에이전트 파일의 model 필드로 세션마다 모델을 고정할 수 있습니다(기본값 inherit은 메인 세션 모델을 그대로 씁니다). 비용이 민감한 회수 작업은 저렴한 모델로, 추론이 중요한 작업은 상위 모델로 미리 정해두면 디스패치 시점에 모델이 흔들리지 않습니다.

연결은 절대 세션을 멈추지 않습니다. 세션 안에서 완전히 끝내려면 /stop을 실행합니다.

?를 누르면 전체 단축키를 화면에서 볼 수 있습니다. 자주 쓰는 항목만 정리하면 다음과 같습니다.

주의

Claude가 세션을 위해 만든 워크트리는 Ctrl+X 두 번으로 삭제할 때 함께 제거되며, 커밋하지 않은 변경도 사라집니다. 보존하려면 먼저 푸시하거나 커밋하세요.

에이전트 뷰를 열지 않고도 짧은 ID로 세션을 직접 다룰 수 있습니다.

claude agents --json        # 라이브 세션을 JSON 배열로 출력
claude attach <id>          # 이 터미널에서 세션에 연결
claude logs <id>            # 세션의 최근 출력 표시
claude stop <id>            # 세션 중지
claude respawn <id>         # 대화를 유지한 채 세션 재시작

에이전트 뷰와 백그라운드 에이전트를 아예 끄려면 disableAgentView 설정을 true로 두거나 CLAUDE_CODE_DISABLE_AGENT_VIEW 환경 변수를 설정합니다. settings.json에 넣을 수 있습니다.

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

위 worktree.bgIsolation을 "none"으로 두면 백그라운드 세션이 워크트리로 옮겨 가지 않고 작업 사본을 직접 편집합니다(v2.1.143 이상).

• 서브에이전트
• 에이전트 팀
• 워크트리

• Manage multiple agents with agent view (Claude Code Docs)

팁

오래 걸리는 세션의 응답을 빠르게 유지하려면 Ctrl+T로 고정해 두세요. 고정하지 않은 세션은 끝나고 약 1시간 동안 손대지 않으면 감독 프로세스가 자원 확보를 위해 프로세스를 중지하며, 다시 연결할 때 한 박자 늦게 깨어납니다.