Session Office for Claude Code

Claude Code 세션을 픽셀 사무실로 보여 주는 VS Code 확장입니다. 세션 하나가 책상 하나이고, 지금 어느 세션이 일하는지, 입력이나 승인을 기다리는지 한눈에 보입니다. 책상을 누르면 그 세션이 열립니다.

이 확장은 Anthropic이 만든 것이 아닌 개인 확장입니다. Claude와 Claude Code는 Anthropic의 상표입니다.

시작하기 전에

• Claude Code VS Code 확장이 설치되어 있어야 합니다.
• 화면 글은 한국어입니다.
• 세션을 여는 데 Claude Code 확장의 공개되지 않은 명령(claude-vscode.editor.open)을 씁니다. Claude Code 업데이트로 이 명령이 바뀌면 세션 열기가 URI, 터미널 순으로 대신 열리거나 동작하지 않을 수 있습니다.
• 세션 상태는 Claude Code가 ~/.claude/projects에 남기는 세션 기록 파일을 읽어서 알아냅니다. 기록 파일 형식은 공개된 규격이 아니라 Claude Code 업데이트로 바뀔 수 있습니다. 이 확장은 기록 파일을 읽기만 하고 바꾸지 않습니다.
• 처음 쓰신다면 명령 팔레트에서 Session Office: 훅 설치를 한 번 실행하세요. 승인 대기를 정확히 알 수 있습니다(아래 「승인 대기를 정확히 보려면」).
• 이전 이름은 Claude Office입니다. 설정 키와 명령 ID(claudeOffice.*)는 그대로입니다.

기능

• 현재 워크스페이스의 세션을 책상으로 표시합니다. 책상 위 말풍선이 상태를 알려 줍니다.
  • 점 세 개(초록): 작업 중
  • 하트(분홍): 끝났고 사용자가 할 일이 없음
  • 느낌표(노랑): 질문이 있어 사용자의 답을 기다림
  • 느낌표(주황)와 손 흔들기: 도구 실행 승인을 기다림
  • 말풍선 없음, 의자에 겉옷: 자리 비움. 마지막 턴 기록에서 입력 대기가 6시간, 작업 중이 30분 이어진 세션입니다. 기준은 파일 수정 시각이 아니라 마지막 턴 기록의 시각입니다(제목 · 모드 같은 부가 기록이 찍혀도 쉬던 세션이 되살아나지 않습니다). 쉬던 세션에 메시지가 들어와 대기열에서 꺼내지면 첫 응답 전에도 작업 중으로 바뀝니다.
• 책상을 끌어서 순서를 바꿀 수 있습니다. 끌면 직접 정렬로 바뀌어 순서가 고정되고, 아래의 "직접 정렬 중 · 자동으로"를 누르면 최근 활동 순으로 돌아갑니다. 직접 정렬한 뒤 생긴 새 세션은 맨 뒤에 붙습니다.
• 책상을 누르면 해당 세션을 에디터 탭으로 이어 엽니다. 이미 열려 있으면 그 탭으로 이동합니다.
• 우클릭 메뉴: 열기, 탭 닫기, 책상 숨기기, 세션 ID 복사, 제목 복사, 터미널에서 이어 열기, 메시지 흐름 보기(주고받은 메시지가 있을 때)
• 숨긴 세션은 다시 작업을 시작하면 책상이 되살아납니다. "숨김 N개 보기"로 직접 되돌릴 수도 있습니다.
• 마지막 빈 책상을 누르면 새 세션을 시작합니다.
• 지금 보고 있는 세션은 책상 자리를 옮기지 않고 파란 테두리와 스탠드 조명으로 표시하며, 상태 줄 앞에 "현재 세션"이 붙습니다. 하위 에이전트가 있으면 그 묶음 띠도 조금 진해집니다.
  • 에디터 탭으로 열었으면 활성 탭의 세션입니다(정확합니다).
  • 오른쪽 Claude Code 패널은 어느 세션을 띄웠는지 다른 확장이 알 수 없어서, 오피스에서 마지막으로 연 세션 · 마지막으로 활성화된 Claude 탭 · 마지막으로 메시지를 보낸 세션 중 가장 최근 것으로 봅니다. 패널 안에서 직접 세션을 바꾸고 아직 메시지를 보내지 않았으면 표시가 이전 세션에 남을 수 있습니다.
• 세션이 Agent 도구로 부른 하위 에이전트(sub)는 부모 책상 바로 뒤에 작은 이름표(↳ 종류)가 붙은 책상으로 앉고, 부모와 점선으로 이어집니다. 일하는 중이면 작업 중, 끝나면 하트(끝남)입니다. 하위 에이전트는 사용자에게 물을 수 없어서 질문 · 승인 대기는 없습니다.
  • 하위 책상을 누르면 기록을 읽기 전용 문서로 엽니다(맡긴 일, 도구 호출 목록, 마지막 응답). 원본 기록 파일은 바꾸지 않습니다. 우클릭하면 부른 세션 열기도 있습니다.
  • 마지막 기록 뒤 30분이 지나면 책상이 사라집니다. 한 세션 밑에는 최근 6개까지만 앉습니다. 하위 책상은 끌거나 숨길 수 없고, 부모를 끌면 함께 움직입니다.
  • 읽는 곳: <세션 폴더>/<세션 ID>/subagents/agent-<id>.jsonl과 .meta.json
  • 하위 책상은 메인보다 작고(좁은 책상, 소품 없음), 몬스터 모드에서는 부모와 같은 종의 아기 모습으로 앉습니다. 이름표는 파란색이고, 부모와 하위 뒤에는 옅은 파란 띠가 깔립니다.
• 세션끼리 SendMessage로 주고받은 메시지를 보여 줍니다. 자세한 내용은 아래 「세션끼리 주고받은 메시지」를 보세요.
• 몬스터 종류는 같은 화면 안에서 겹치지 않게 나눕니다(6종이라 책상이 7개 이상이면 겹칩니다). 한 번 정한 종류는 기억해 두어 순서가 바뀌어도 그대로입니다.
• 상태 표시줄에 "내 차례"(승인 대기와 질문이 있는 세션의 합)와 작업 중인 세션 수가 나옵니다. 하트 세션은 세지 않습니다. 오피스 패널이 닫혀 있어도 갱신됩니다.
• 승인을 기다리는 세션이 생기면 알림창을 띄웁니다.

승인 대기를 정확히 보려면

세션 파일만으로는 승인 대기를 정확히 알 수 없어서 Claude Code의 훅을 씁니다.

1. 명령 팔레트에서 Session Office: 훅 설치를 실행하고 확인합니다. ~/.claude/settings.json에 훅 9개를 추가하며, 기존 항목은 바꾸지 않고 변경 전에 백업 파일을 남깁니다.
2. 훅은 세션이 시작될 때 읽힙니다. 이미 열려 있던 세션은 탭을 닫고 오피스에서 다시 열면 적용됩니다. 그 전까지는 파일 기록으로 추정한 상태가 표시됩니다. 파일 기록만으로는 "승인을 기다리는 중"과 "명령이 오래 걸리는 중"을 구분할 수 없어서, 훅이 없는 세션은 승인 대기를 표시하지 않고 작업 중으로 보입니다.
3. 제거는 Session Office: 훅 제거입니다. 우리 항목만 지웁니다.

설정

알아 둘 것

• 오피스 화면은 하단 패널(터미널 쪽)에 열립니다. 책상을 누르면 그 세션이 오른쪽 Claude Code 패널에 바로 뜹니다. 오른쪽 패널은 한 번에 한 세션만 보여 주므로, 책상을 누를 때마다 보이는 세션이 바뀝니다.

• 세션을 여는 위치는 설정 claudeOffice.openIn으로 바꿉니다. sidebar(기본)는 오른쪽 Claude Code 패널이고, editor는 에디터 탭입니다. 에디터 탭은 세션 여러 개를 나란히 볼 수 있습니다.

• sidebar가 동작하려면 Claude Code의 기본 위치 설정(claudeCode.preferredLocation)이 sidebar여야 합니다. 다르면 처음 누를 때 바꿀지 묻고, 묻지 않고는 이 설정을 바꾸지 않습니다.

• "탭 닫기"는 에디터 탭으로 연 세션에만 해당합니다. 오른쪽 패널에 열린 세션은 닫을 탭이 없습니다.

• 탭 닫기는 오피스에서 연 탭은 정확히 닫고, 그 밖의 탭은 이름이 세션 제목과 일치하는 후보가 하나일 때만 닫습니다.

• 세션 열기는 Claude Code 확장의 비공개 명령(claude-vscode.editor.open)을 씁니다. 확장 업데이트로 바뀌면 URI, 터미널 순으로 대신 엽니다.

• 로그는 출력 패널의 Session Office에서 볼 수 있습니다.

세션끼리 주고받은 메시지

세션이 SendMessage 도구로 다른 세션에 메시지를 보내면 두 곳에 나타납니다.

• 사무실 바닥: 평소에는 선을 긋지 않습니다.
  • 새 메시지가 오면 보낸 책상에서 받은 책상으로 봉투가 한 번 날아갑니다. 패널이 가려져 있던 동안(다른 탭을 보던 중, 창을 다시 불러오기 전 등) 온 메시지는 패널이 다시 보일 때 최근 30분 안의 것을 최근 5개까지 차례로 날립니다. 이미 날린 봉투는 기억해 두어(창마다) 되풀이하지 않습니다. 보내지 못한 메시지는 날리지 않습니다.
  • 책상 오른쪽 위의 봉투 숫자는 최근 30분에 받은 메시지 수입니다. 숫자에 마우스를 올리면 보낸 세션과 요약이 보이고, 누르면 그 봉투들을 시간 순서대로 다시 날립니다(최근 8개까지).
  • 책상에 마우스를 올리면 최근 30분 동안 그 세션과 주고받은 상대에게만 주황 점선이 그어지고 건수가 붙습니다. 이 선은 책상 위 벽 쪽으로 지나가서, 하위 책상의 파란 선(바닥 쪽)과 겹치지 않습니다.
  • 지금 메시지를 받을 수 있는 세션(프로세스가 떠 있는 세션)은 모니터 위에 초록 안테나가 섭니다. Claude Code가 떠 있는 세션마다 남기는 ~/.claude/sessions/<pid>.json을 읽고, 그 프로세스가 실제로 떠 있는지도 봅니다. 안테나가 없는 세션에 보낸 메시지는 닿지 않습니다. 책상을 누르면 그 세션이 켜집니다(오른쪽 패널은 한 번에 한 세션만 보여 주므로, 다른 책상을 누르면 앞 세션이 얼마 뒤 꺼질 수 있습니다).
  • 보내지 못한 메시지는 봉투가 받을 책상까지 갔다가 빨간 X를 달고 돌아옵니다. 받을 세션이 아직 꺼져 있으면 그 책상 왼쪽 위에 돌아온 봉투가 남고, 누르면 그 세션이 켜집니다. 켜진 뒤에는 보낸 세션에 다시 보내 달라고 하세요(오피스가 대신 보내지는 않습니다). 보내지 못한 메시지는 봉투 숫자와 점선 건수에 넣지 않습니다.
  • 이 창에 책상이 없는 세션(다른 폴더의 세션 등)과 주고받으면 벽 오른쪽 끝에 「다른 폴더」 문이 생기고, 봉투와 점선이 그 문으로 드나듭니다.
• 메시지 흐름 탭: 바닥 오른쪽 아래 「메시지 흐름」, 책상 우클릭 메뉴(그 세션의 마지막 메시지를 골라 엶), 명령 팔레트의 Session Office: 메시지 흐름 보기로 엽니다.
  • 세로줄 하나가 세션 하나이고, 위에서 아래로 시간이 흐릅니다. 화살표 한 줄이 메시지 한 건입니다. 날짜 단추로 최근 며칠(claudeOffice.messageDays, 기본 3일)을 오갑니다.
  • 줄을 누르면 오른쪽에 요약, 보낸 시각, 상태, 본문 전체가 열리고, 보낸 세션이나 받은 세션을 바로 열 수 있습니다. 다른 폴더 세션은 그 폴더를 연 창에서 열어야 합니다.
  • 받은 쪽 기록에서 짝을 찾지 못한 메시지는 점선 화살표와 「받은 기록 없음」으로, 받는 세션을 찾지 못해 보내지 못한 메시지는 「보내지 못함」으로 표시합니다.
  • 선 색은 세로줄마다 다르고 이름 밑줄 색과 같습니다(몬스터 색은 겹칠 수 있어서 따로 줍니다).
  • 세로줄 이름 앞의 초록 점은 지금 메시지를 받을 수 있는 세션입니다.
  • 날짜 단추 아래 「짝」 줄에는 그날 메시지를 주고받은 두 세션 묶음이 많은 순으로 놓입니다(링크 ⇄ 오븐영상제작 19건). 하나를 누르면 그 두 세션 사이 메시지만 남고 나머지 세로줄은 흐려집니다. 같은 것을 다시 누르거나 「전체」를 누르면 돌아갑니다. 받는 세션을 모르는 메시지는 짝에 넣지 않습니다.
  • 세로줄 머리(몬스터와 이름)에 마우스를 올리면 그날 그 세션과 주고받은 세션의 밑줄이 주황으로 바뀌고 건수가 붙습니다. 키보드로는 Tab으로 세로줄 머리에 가면 같은 표시가 나옵니다.
• 읽는 방법: 보낸 쪽 기록에는 SendMessage 호출과 그 결과(성공 여부)가, 받은 쪽 기록에는 <cross-session-message>가 남습니다. 보낸 쪽의 받는 이 칸은 이름 · 세션 ID · 내부 주소(uds:…) 중 하나라 그것만으로는 누가 받았는지 알 수 없어서, 본문이 같고 시각이 가장 가까운 받은 기록과 짝짓습니다.
  • 다른 폴더 세션도 찾아야 해서 ~/.claude/projects 아래 모든 세션 폴더에서 기간 안에 바뀐 기록 파일을 읽습니다. 처음 한 번은 끝에서부터 기간 안쪽만 거슬러 읽고(수백 MB면 1에서 2초), 그 뒤로는 늘어난 부분만 읽습니다. 기록 파일은 바꾸지 않습니다.
  • 세션 이름은 다른 세션이 그 세션을 부른 이름(/rename으로 붙인 이름 등)으로 익힙니다. 사무실에 책상이 있는 세션은 사무실 제목을 씁니다.

진행 막대 ([진행 n/m] 줄)

• 세션이 응답에 [진행 3/5] 현재 단계 한 줄을 적으면, 오피스가 가장 최근의 그 줄을 읽어 책상 아래에 진행 막대와 "3/5"를 보여 줍니다. 마우스를 올리면 현재 단계 글도 보입니다.

• 앞의 숫자는 끝낸 단계 수, 뒤의 숫자는 전체 단계 수입니다. 끝나면 [진행 5/5] 완료처럼 같게 적습니다. 막대는 진행 중에는 파랑, 끝나면 초록입니다.

• 한 응답에 여러 개 있으면 마지막 것을 씁니다. 숫자가 말이 안 되면(0단계, 100단계 이상, 끝낸 수가 전체보다 큼) 무시합니다.

• 진행 줄은 줄의 맨 앞에 있을 때만 읽습니다(앞에 목록 기호나 굵은 글씨 표시는 허용). 설명하면서 문장 속에 인용한 예시, 백틱 안, 따옴표 안, 인용문, 코드 블록 안은 진짜 진행이 아니라 예시로 보고 읽지 않습니다. (지침을 설명하며 예시를 적었더니 그 세션에 가짜 막대가 뜬 일이 있어서 정했습니다.)

• 줄을 적은 지 12시간이 지났거나 자리 비움인 세션에는 막대를 보여 주지 않습니다. 지금 작업과 무관한 낡은 진행으로 오해하지 않게 하려는 것입니다.

• 새 대화가 진행되면 지난 일의 막대는 지웁니다. 기준은 진행 줄 뒤에 사용자가 직접 보낸 새 메시지입니다.

  • 완료된 막대(끝낸 수 = 전체)는 새 메시지가 오면 사라집니다.
  • 진행 중인 막대는 새 메시지 하나까지는 유지합니다(같은 일을 이어 가라는 말일 수 있어서). 그 응답이 새 진행 줄 없이 끝나거나, 새 메시지가 두 번 이상 오면 사라집니다. 새 진행 줄이 나오면 그 값으로 바뀝니다.
  • 슬래시 명령과 그 출력, 도구 결과, 하위 에이전트의 입력, 중단 표시는 새 메시지로 세지 않습니다.
  • 그래서 같은 일을 이어 가는 동안은 응답마다 진행 줄을 적어야 막대가 유지됩니다.

• 세션이 이 줄을 적도록 하려면 지침이 필요합니다. 명령 팔레트에서 Session Office: 진행 표시 지침 설치를 한 번 실행하세요. 전역 지침 파일(~/.claude/CLAUDE.md, Windows는 %USERPROFILE%\.claude\CLAUDE.md)에 아래 문단이 추가됩니다.

  • 확인 창을 띄우고, 기존 내용은 한 글자도 바꾸지 않고, 변경 전에 같은 폴더에 백업(CLAUDE.md.office-backup-<시각>)을 남깁니다.
  • Session Office: 진행 표시 지침 제거를 실행하면 Session Office가 넣은 문단만 지웁니다. 설치 전과 바이트까지 같아집니다.
  • 같은 제목의 문단이 이미 있으면(직접 넣으신 경우) 설치도 제거도 아무것도 바꾸지 않습니다.
  • 문단 제목은 확장 이름이 바뀌기 전과 같은 진행 표시 (Claude Office)를 그대로 씁니다. 이미 설치한 지침을 그대로 알아보고 지울 수 있게 하려는 것입니다.
  • 새로 시작하는 세션부터 적용됩니다. 이미 열려 있는 세션에는 "앞으로 진행 줄을 붙여 줘"라고 한 번 말해 주세요.

• 직접 넣으려면 아래 문단을 지침 파일 끝에 붙여 넣으세요. 진행 줄 형식 예시는 백틱 안에 그대로 두어야 합니다. 줄 맨 앞에 쓰면 오피스가 예시를 진짜 진행으로 읽습니다.

  ## 진행 표시 (Claude Office)
  - 3단계 이상으로 나뉘는 작업은, 시작할 때와 단계가 하나 끝날 때마다 응답 끝에 `[진행 3/5] 현재 단계` 한 줄을 붙인다. 앞 숫자는 끝낸 단계 수, 뒤는 전체 단계 수이고, 모두 끝나면 `[진행 5/5] 완료`로 마무리한다.
  - 단계가 끝나면 도구 호출을 이어 가기 전에 이 줄을 먼저 적는다. 한두 단계로 끝나는 짧은 일에는 붙이지 않는다.
  

• Claude Code의 할 일 목록 도구(TodoWrite 등)는 이 환경에서 쓸 수 없는 것으로 확인되어, 도구가 아니라 응답 글의 한 줄로 읽습니다. Claude가 이 줄을 빼먹은 응답에서는 가장 최근 줄이 계속 보입니다.

질문 판정 (하트와 느낌표)

• Claude가 끝낸 마지막 응답의 끝 네 문장을 보고, 사용자가 답하거나 할 일이 있으면 느낌표, 없으면 하트로 표시합니다.
• 질문으로 보는 것: 물음표로 끝나는 문장, "~할까요"류의 의사를 묻는 말, "알려 주세요 · 붙여 주세요 · 골라 주세요 · 확인해 주세요"류의 요청, "'진행해' 주시면" · "승인이 오면" 같은 진행 신호 대기, 선택지를 묻는 도구(AskUserQuestion) 사용.
• 끝에서 1500자 안에 "정해 주시면 좋을 것", "(…알려 주세요)"처럼 요청을 담은 제목(# 제목이나 굵은 한 줄)이 있으면, 그 뒤에 마무리 문장이 몇 개 붙어 있어도 질문으로 봅니다.
• 질문으로 보지 않는 것: "원하시면 말씀해 주세요", "이상하면 알려 주세요" 같은 선택적 문구(끝난 세션마다 붙는 인사말), 코드 블록 안의 글.
• 문장 표현을 목록과 대조하는 규칙이라 사람처럼 이해하지는 못합니다. 돌려 말한 요청은 놓칠 수 있고, 물음표로 끝나는 서술은 질문으로 잘못 볼 수 있습니다. 빗나가도 아이콘 하나가 달라질 뿐입니다.
• 훅을 설치하면 응답이 끝나는 순간의 마지막 응답으로 판정합니다. 훅이 없는 세션은 세션 파일의 마지막 응답으로 판정합니다.

직원 이름과 제목 별칭 (오피스 전용)

• 책상을 우클릭하면 "직원 이름 바꾸기"와 "제목 바꾸기"가 있습니다. 입력칸에 값을 쓰고 확인하면 됩니다. 비우면 지워집니다.
• 직원 이름은 책상 앞면의 이름표로 나옵니다(12자까지). 이름을 정하지 않은 직원은 이름표가 없습니다.
• 제목 별칭은 책상 아래 글자로 나옵니다(60자까지). 마우스를 올리면 Claude Code 쪽 원래 제목이 같이 보입니다. 원래 제목과 똑같이 쓰면 별칭이 없는 것으로 봅니다.
• 이 값은 ~/.claude-office/aliases.json에만 저장됩니다. 세션 파일과 Claude Code 설정에는 아무것도 쓰지 않으므로 Claude Code의 기록 목록과 탭 이름은 바뀌지 않습니다. 지우면 별칭이 모두 없어지므로 지우지 마세요(제목 기억 파일 titles.json과 달리 다시 만들어지지 않습니다).
• 알림창과 상태 표시줄 설명에도 "이름(제목)"으로 나옵니다.
• Claude Code의 이름 칸은 하나뿐입니다. /rename(또는 --name)으로 붙인 이름이 세션 제목이면서 세션 간 메시지의 주소가 됩니다. 이름을 붙이면 Claude 쪽에서는 이름, 제목, 주소가 하나로 합쳐지는 것이 정상이고, 오피스가 막을 수 없습니다. 오피스의 직원 이름표와 제목 별칭은 그와 별개로 따로 둘 수 있습니다.
• 이름표와 책상 제목이 같은 글자가 되는 경우(이름표와 /rename 이름이 같을 때)에는, 제목 줄에 같은 글자를 또 보여 주지 않고 Claude가 붙인 설명 제목을 대신 보여 줍니다. 제목은 보통 굵기, 이름표는 굵은 글씨로 눈에 띄게 다릅니다.
• 마우스를 올리면 "직원 / 제목 / Claude 세션 제목 / 진행"이 줄마다 이름을 붙여 나옵니다.

세션 제목

• 제목은 세션 파일에서 읽습니다. 사용자가 바꾼 이름(custom-title)이 가장 우선이고, 그다음이 Claude의 자동 제목(ai-title), 둘 다 없으면 첫 입력 문장입니다. 이름을 바꾸는 것은 Claude Code의 방법을 쓰세요. 오피스는 읽기만 하고 세션 파일에 쓰지 않습니다.
• 한 번 알게 된 제목은 ~/.claude-office/titles.json에 기억해서, 우선순위가 낮은 제목으로 되돌아가지 않습니다. 이 파일은 지워도 세션 파일에서 다시 만들어지는 캐시입니다.
• cd나 git 같은 명령줄을 붙여 넣은 첫 입력은 제목 후보에서 뺍니다. 한글이 섞인 문장은 그대로 씁니다.
• 한계: 이름 기록이 세션 파일의 끝 384KB와 앞 256KB 밖에 있고 기억도 없으면 찾지 못해서, 그 세션은 첫 입력 문장으로 나옵니다. Claude Code는 세션을 이어 열 때 이름 기록을 파일 끝에 다시 쓰므로, 세션을 한 번 열면 찾게 됩니다.

개발

• 시험: npm test (Node만 있으면 됩니다). 시험은 임시 폴더만 쓰고, 사용자의 ~/.claude-office와 ~/.claude/settings.json은 읽지도 쓰지도 않습니다.
• 질문 판정 규칙을 실제 세션으로 재 보려면: node test/measure-ask.js <세션 폴더> (예: ~/.claude/projects/<프로젝트 폴더>)
• 패키징과 설치: 이 폴더에서 vsce package --no-dependencies -o session-office-<버전>.vsix 후 code --install-extension session-office-<버전>.vsix, 그다음 VS Code 창에서 Developer: Reload Window. 설치한 확장은 창을 다시 불러와야 켜집니다.
• 마켓플레이스 게시: vsce login floracho(게시용 토큰 입력) 후 vsce publish.
• 확장 ID는 0.9.0부터 floracho.session-office입니다(그 전은 local.claude-office). 바꾼 뒤 처음 켜질 때 ~/.claude-office/migrate-local.json이 있으면 옛 확장의 숨긴 책상 · 책상 순서 · 캐릭터 기억을 한 번 가져옵니다.
• 현재 버전이 어느 것인지는 상태 표시줄 배지에 마우스를 올리면 첫 줄에 나옵니다.