Agent Office의 기능
Agent Office는 AI 지원 소프트웨어 개발을 함께 사용할 수 있는 만화풍 3D 사무실로 구현합니다. 각 GitHub 저장소는 책상, 코딩 워커, 터미널, 이슈 및 풀 리퀘스트 보드, 작업 대기열, 서비스, 프로젝트별 설정이 있는 별도의 층이 됩니다.
책상에 Claude Code, OpenCode 또는 Codex 워커를 배치하고, 책상 위 노트북에서 워커의 실시간 터미널을 확인하거나 팀원과 같은 터미널을 열 수 있습니다. 워커는 기본 체크아웃 또는 격리된 Git worktree에서 작업할 수 있으므로 작업 디렉터리를 공유하지 않고 여러 작업을 병렬로 실행할 수 있습니다.
또한 멀티플레이어 이동, 음성, 화면 공유, 영구 채팅 및 터미널 기록, 워커 알림, 시스템 모니터링, 프로젝트 탐색, GitHub 이슈 및 풀 리퀘스트 작업 흐름, 구조화된 다중 에이전트 회의를 제공합니다.
핵심 개념
저장소마다 하나의 층
Agent Office를 처음 시작하면 엘리베이터에서 열리며, 인증된 GitHub CLI 계정에서 확인할 수 있는 저장소를 선택하라는 메시지가 표시됩니다. 저장소를 owner/name 형식으로 직접 입력할 수도 있습니다.
저장소는 다음 위치에 복제됩니다:
~/agent-office/<owner>/<repo>각 프로젝트 층에는 독립적인 워커, 책상, 보드, 대기열, 서비스, 사진, 색상이 있습니다. 한 층에 있는 사람들은 같은 층의 다른 사람들만 보고 들을 수 있습니다.
책상에 배치하는 워커
빈 책상에는 Claude Code, OpenCode, Codex 또는 공유 로그인 셸을 배치할 수 있습니다. 사용 중인 책상에는 워커의 실시간 터미널과 상태가 표시됩니다. 에이전트 훅 또는 플러그인은 워커가 작업 중인지, 입력을 기다리는지, 완료되었는지를 알려 줍니다.
GitHub 보드와 작업 자동화
이슈 보드는 이슈를 열림, 진행 중, 닫힘 그룹으로 정리합니다. 풀 리퀘스트 보드에는 초안, 검토, 승인, 병합, 종료, CI 상태 및 변경 내용 크기가 표시됩니다. 작업을 워커에게 직접 전달하거나 영구 대기열에 추가하여 자동으로 실행할 수 있습니다.
사전 요구 사항 및 설치
제공된 README에는 Agent Office 사용 방법이 설명되어 있지만 패키지 관리자 설치 명령은 포함되어 있지 않습니다. 저장소의 배포 또는 빌드 지침에 따라 프로젝트를 설치한 다음, 셸에서 agent-office 실행 파일을 사용할 수 있는지 확인하세요.
시작하기 전에 서버가 사용할 GitHub CLI 계정을 인증하세요:
gh auth status인증이 되어 있지 않다면 다음 GitHub CLI 로그인 절차를 완료하세요:
gh auth login선택한 계정에 따라 Agent Office에서 검색할 수 있는 저장소와 이슈 댓글 게시 같은 GitHub 작업에 사용할 계정이 결정됩니다.
해당 유형의 워커를 고용하려면 컴퓨터에 지원되는 코딩 에이전트 CLI가 하나 이상 설정되어 있어야 합니다. Agent Office는 Claude Code, OpenCode 및 Codex 워커를 지원합니다.
첫 사무실 시작하기
다음 명령으로 애플리케이션을 실행하세요:
agent-office- 애플리케이션에 표시된 주소를 사용하여 브라우저에서 Agent Office 인터페이스를 엽니다.
- 엘리베이터의 프로젝트 선택기를 사용하여
gh를 통해 사용할 수 있는 저장소를 선택하거나 전체owner/name을 입력합니다. - Agent Office가 저장소를
~/agent-office아래에 복제하는 동안 기다립니다. - 캐릭터의 피부색, 헤어스타일, 머리 색상 및 셔츠를 선택합니다.
- 새 프로젝트 층으로 들어갑니다.
나중에 다른 프로젝트를 추가하거나 방문하려면 북쪽 벽의 엘리베이터로 걸어가 E를 누르세요. 왼쪽 위의 프로젝트 이름을 클릭한 다음 다른 층을 선택할 수도 있습니다.
선택적 실행 설정
README에는 몇 가지 유용한 서버 옵션이 설명되어 있습니다. 예를 들면 다음과 같습니다:
agent-office --city Berlin --max-workers 4--city Berlin 옵션을 사용하면 일출, 일몰 및 날씨가 베를린에 맞춰집니다. --max-workers 4 옵션은 모든 층에서 동시에 실행되는 워커 수에 서버 전체 한도를 설정합니다. 공유 셸과 보드 에이전트도 이 한도에 포함됩니다.
팀 알림은 Slack 또는 Discord 수신 웹훅에 연결할 수 있습니다:
agent-office --webhook <incoming-webhook-url>예산 경고와 고용 일시 중지는 --budget 및 --budget-pause를 통해 사용할 수 있습니다. 이러한 제어 기능은 추적된 Claude Code 지출만 사용합니다. OpenCode 또는 Codex의 지출을 직접 제한할 수는 없지만, 추적된 고용 한도에 도달하면 새 워커가 모두 일시 중지됩니다.
기본 조작 익히기
- WASD: 층 안을 이동합니다.
- Space: 점프합니다.
- 마우스 드래그: 카메라를 회전합니다.
- E: 책상, 보드, 엘리베이터, 좌석, 사다리 및 기타 사무실 물체와 상호작용합니다.
- Tab: 기본 메뉴를 엽니다.
- T: 최근 채팅 줄을 읽습니다.
- P: 빈 책상에서 고용하기 전에 작업을 작성합니다.
- B: 빈 책상에서 공유 로그인 셸을 엽니다.
- C: 사용 중인 책상에서 변경 사항을 확인합니다.
- N: 가장 오래 기다린 워커를 방문합니다.
- R: 종료된 지원 워커 세션을 재개합니다.
- /: 채팅 및 워커 터미널 기록을 검색합니다.
기본 메뉴에서는 워커, 사람, 이슈, 풀 리퀘스트, 대기열, 서비스, 검색, 음성, 화면 공유, 설정 및 기타 상태 패널을 위한 창을 열 수 있습니다. 자주 사용하는 항목은 상단 바에 고정할 수 있으며, 브라우저별 레이아웃 선택 사항은 유지됩니다.
첫 코딩 워커 고용하기
- 비어 있는 책상으로 이동합니다.
- E를 누릅니다.
- Claude Code, OpenCode 또는 Codex를 선택합니다.
- 작업자에게 완료하게 할 작업을 입력합니다.
- 필요한 경우 자체 git worktree를 활성화합니다.
- 고용을 확인하고 노트북에 작업자의 터미널이 나타나는지 확인합니다.
작업자를 선택하기 전에 작업을 작성하려면 빈 책상에서 P를 누르면 됩니다. Agent Office는 16개의 책상을 제공합니다. 책상이 모두 사용 중이면 임시 빈백 작업 공간에서 최대 12명의 작업자를 추가로 수용할 수 있습니다.
병렬 작업에는 격리된 worktree 사용
여러 작업자가 동시에 저장소를 편집할 수 있다면 자체 git worktree를 활성화합니다. Agent Office는 office/<name> 브랜치를 만들고 체크아웃을 다음 위치에 배치합니다.
.agent-office/worktrees/이렇게 하면 병렬 작업자들이 같은 체크아웃을 수정하지 않습니다. worktree 작업자를 퇴근시킬 때 브랜치와 worktree를 유지하거나, worktree만 삭제하거나, 둘 다 삭제할 수 있습니다. Agent Office는 커밋되지 않은 변경 사항과 원격 저장소에 아직 전송되지 않은 커밋을 경고합니다.
안전한 시점에 남아 있는 worktree를 정리하려면 다음을 실행합니다.
agent-office prune작업자 터미널 열기 및 협업
사용 중인 책상에서 E를 누르면 WebSocket을 통해 실제 PTY 터미널이 열립니다. 여러 팀원이 세션에 동시에 입력할 수 있으며, 나중에 참여한 사람도 기존 스크롤백을 확인할 수 있습니다.
터미널 헤더에는 현재 터미널을 열어 둔 사람이 표시됩니다. 다른 사람이 텍스트를 입력할 때는 입력 중 알림도 표시되어 협업자들이 서로의 입력을 덮어쓸 가능성을 줄여 줍니다.
작업자 터미널과 마지막 3,000줄이 저장됩니다. Agent 프로세스는 메인 서버와 별도로 실행되므로 서버를 다시 로드하거나 프로세스를 재시작해도 작업을 계속할 수 있습니다. 서버가 다시 실행되면 열려 있던 터미널이 자동으로 재연결됩니다.
실시간 작업자 상태 이해
작업자의 안테나와 애니메이션은 현재 상태를 나타냅니다. 작업자는 작업 중, 입력 필요 또는 완료 상태로 표시될 수 있습니다. 파일 읽기, 코드 편집, 테스트 실행, 웹 검색 또는 반복적인 오류 발생과 같은 작업도 애니메이션에 반영됩니다.
작업자에게 도움이 필요하거나 작업을 완료하면 Agent Office가 알림을 재생하고 대기 중 작업자 수에 해당 작업자를 표시합니다. 가장 오래 기다린 작업자로 이동하려면 N을 누릅니다. N을 반복해서 누르면 대기 중인 작업자들을 차례로 확인할 수 있습니다.
변경 사항 검토 및 풀 리퀘스트 열기
사용 중인 책상에서 C를 누르거나 터미널에서 변경 사항을 선택합니다. 변경 사항 보기에는 수정된 파일과 오피스가 열린 브랜치를 기준으로 계속 새로 고쳐지는 diff가 표시됩니다.
이 보기에서 다음 작업을 할 수 있습니다.
- 변경된 파일과 diff를 확인합니다.
- 작업자의 변경 사항을 커밋합니다.
- 원하지 않는 변경 사항을 폐기합니다.
- 브랜치를 푸시합니다.
- 풀 리퀘스트를 엽니다.
격리된 worktree를 사용하는 작업자의 경우 작업이 준비되면 책상에서 O를 누릅니다. Agent Office가 브랜치를 푸시하고 작업 내용을 바탕으로 작성한 제목과 설명으로 풀 리퀘스트를 엽니다. GitHub 이슈에서 시작된 작업에는 Closes #n 참조가 포함됩니다. 풀 리퀘스트를 보려면 O를 다시 누릅니다.
GitHub 이슈 작업
이슈 보드에는 열림, 진행 중, 닫힘 상태의 이슈가 표시됩니다. 이슈를 선택하면 설명과 댓글을 읽고, 댓글을 작성하고, 작업자에게 보내거나 작업 큐에 추가할 수 있습니다.
이슈 카드를 직접 집어 들 수도 있습니다.
- 이슈 메모를 가리킨 뒤 E를 누르거나 이슈 창에서 집어 들기를 사용합니다.
- 카드를 빈 책상으로 가져가 새 작업자를 고용합니다.
- 카드를 사용 중인 책상으로 가져가 해당 작업자에게 전달합니다.
- 카드를 작업 큐로 가져가 대기열에 추가합니다.
- 카드를 보드로 되돌리려면 Q를 누릅니다.
작업자가 이슈 카드를 받으면 Agent Office가 GitHub를 통해 해당 이슈를 할당하고 진행 중 상태로 변경합니다. 이슈는 선택적 댓글과 함께 완료 또는 계획 없음으로 닫을 수도 있습니다.
풀 리퀘스트 검토 및 병합
PR 보드는 풀 리퀘스트를 초안, 검토 중, 승인됨, 병합됨, 닫힘 상태로 그룹화합니다. CI 상태와 diff 크기도 표시합니다.
풀 리퀘스트를 열고 변경된 파일을 선택하면 diff를 확인할 수 있습니다. 파일은 폴더 트리 또는 단순 목록으로 표시할 수 있습니다. 검토 댓글은 관련 줄 아래에 표시됩니다.
- V를 눌러 파일을 검토 완료로 표시합니다.
- J와 K를 사용해 파일 사이를 이동합니다.
- 검토를 선택해 PR을 작업자에게 맡깁니다.
- 댓글 수정 및 병합을 선택하면 작업자가 피드백을 처리하고 검사를 통과시킨 뒤 병합합니다.
- 브랜치가 기반 브랜치와 충돌하면 충돌 수정 및 병합을 사용합니다.
Agent Office는 풀 리퀘스트를 스쿼시, 병합 또는 리베이스할 수 있습니다. 필요한 검사가 통과한 후 GitHub에 자동 병합을 요청할 수도 있습니다. 풀 리퀘스트가 병합되면 오피스에서 병합 징을 울리고 색종이를 날리며 활동 중인 작업자를 애니메이션으로 축하합니다.
작업 큐로 작업 자동화
작업 큐는 북쪽 벽의 화이트보드 또는 메인 메뉴에서 사용할 수 있습니다. 자유 형식 작업을 추가하거나 이슈를 큐에 넣으면 Agent Office가 자동으로 작업을 할당합니다.
책상을 사용할 수 있고 큐의 동시 실행 설정이 다른 작업자를 허용하면 다음 작업에 격리된 Git worktree를 사용하는 새 작업자가 배정됩니다. 기본 큐 동시 실행 수는 작업자 3명입니다. 동시 작업자 수를 0으로 설정하면 큐가 일시 중지됩니다.
대기열에 등록된 이슈 작업은 GitHub에서 할당되며, 결과 풀 리퀘스트가 생성되면 대기열 보드에 연결됩니다. 작업을 완료한 워커는 대기열에서 다른 작업을 위해 자리가 필요할 때까지 검사를 위해 책상에 남아 있습니다. 대기열 상태는 재시작 후에도 유지됩니다.
전문 보드 에이전트 사용
이슈 보드, PR 보드, 작업 대기열에는 각각 키오스크 에이전트가 있습니다. 키오스크로 가서 E를 누르면 프롬프트를 입력할 수 있습니다.
- 이슈 에이전트:
gh를 통해 이슈를 찾고, 등록하고, 분류하고, 라벨을 지정하고, 종료합니다. - PR 에이전트: 풀 리퀘스트를 요약하고, 검토하고, 댓글을 작성하고, 병합합니다.
- 대기열 에이전트: 요청을 하나 이상의 대기열 작업으로 변환하고, 대기열 상태를 보고하며, 작업을 삭제합니다.
대기열 에이전트는 코드 변경을 직접 구현하지 않습니다. 새 워커가 격리된 워크트리에서 작업을 수행할 수 있도록 대기열 작업을 생성합니다. 키오스크에서 O를 누르면 터미널을 확인할 수 있고, X를 누르면 에이전트를 돌려보낼 수 있습니다.
구조화된 멀티 에이전트 회의 진행
회의실은 2명에서 5명의 워커 그룹을 지원합니다. 회의실, 메인 메뉴, 이슈 또는 풀 리퀘스트에서 회의를 시작할 수 있습니다. 각 참가자에게는 이름을 변경할 수 있는 역할이 지정됩니다.
사용 가능한 패턴은 다음과 같습니다.
- 토론: 워커들이 접근 방식을 제안하고 서로 비판하며 최종 결정을 내립니다.
- 리드 및 팀: 리드가 작업을 나누고 일부를 위임한 뒤 결과를 통합합니다.
- 맵-리듀스: 매퍼들이 별도의 파일, 모듈, 이슈 또는 기타 부분을 처리한 다음 한 워커가 결과를 통합합니다.
- 레드 / 블루: 레드팀 워커가 버그, 보안 위험, 엣지 케이스를 찾고 블루팀 워커가 유효한 문제를 해결합니다.
- 검토 패널: 검토자들이 서로 다른 관점에서 풀 리퀘스트를 살펴본 뒤 리드가 검토 결과를 통합하고 게시합니다.
모든 회의는 출력 파일을 지정하고 자체 브랜치에서 실행됩니다. 출력이 준비되면 Open PR을 사용해 풀 리퀘스트를 생성합니다. 회의에는 라운드 제한과 테이블 전체 토큰 예산이 적용되므로 무기한 계속되지 않습니다.
서비스, 리소스 및 비용 모니터링
개발 서비스
워커가 npm run dev, 프리뷰 빌드 또는 python -m http.server와 같은 웹 서버를 실행하면 몇 초 안에 서비스 보드에 표시됩니다. 각 항목에는 워커, 브랜치, 페이지 제목이 표시됩니다. 항목을 선택하면 자신의 컴퓨터에서 해당 서버를 여는 명령이 복사됩니다.
머신 부하 및 워커 제한
서쪽 벽의 모니터에는 현재 CPU 및 메모리 사용량, 5분간의 사용 기록, 실행 중인 워커 수가 표시됩니다. 메모리 사용량이 90퍼센트에 도달하거나 CPU가 약 30초 동안 90퍼센트 이상 사용되면 Agent Office는 머신에 부하가 걸렸다고 경고합니다.
서버 수준의 --max-workers 값은 하드 한도를 제공합니다. 관리자는 설정에서 활성 한도를 낮출 수 있지만 시작 시 설정된 값보다 높일 수는 없습니다. 수용 인원이 가득 차면 수동 고용은 설명과 함께 거부되고, 대기열 작업은 자리가 날 때까지 기다립니다.
사용량 및 비용 보고
Claude Code 워커는 추적된 세션 비용과 토큰을 보고합니다. OpenCode는 토큰과 모델/제공자 추정치를 보고하며, 가능한 경우 하위 세션도 포함합니다. Codex는 캐시 및 추론 세부 정보를 포함한 기록된 루트 세션 토큰을 보고하지만 비용이나 API 호출 횟수는 보고하지 않습니다.
메뉴에서 Claude limits를 활성화하면 5시간 세션, 주간 허용량 및 모델별 주간 제한에 대한 Claude 요금제 사용량이 표시됩니다. Claude가 요금제가 아닌 API 키를 사용하는 경우 이 패널은 숨겨지며, OpenCode나 Codex는 포함되지 않습니다.
고급 협업 팁
- 동시 코딩에는 기본적으로 워크트리 사용: 워커들이 커밋하지 않은 파일을 공유하거나 서로의 브랜치를 변경하는 일을 방지합니다.
- 계획과 구현 분리: 이슈 및 대기열 에이전트로 작업을 정리한 다음 새 워크트리 워커가 코드 변경을 수행하도록 합니다.
- 대기열 동시 작업 수를 머신 한도보다 낮게 유지: 대화형 워커, 공유 셸, 보드 에이전트를 위한 여유 용량을 남겨 둡니다.
- 데스크톱 알림 사용: 사무실 탭이 백그라운드에 있을 때 입력이 필요하거나 작업을 완료한 워커로 바로 이동할 수 있습니다.
- 팀 웹훅 구성: Slack 또는 Discord 알림을 사용하면 팀이 방치된 워커를 확인하는 데 도움이 됩니다.
- 세션을 다시 열기 전에 검색: /를 눌러 채팅과 보존된 모든 터미널 출력을 검색할 수 있으며, 재시작 전 기록도 포함됩니다.
- 지원 작업에는 공유 셸 사용: AI 워커를 고용하지 않고 테스트, Git 명령 또는 개발 서버를 위한 협업 터미널이 필요할 때 빈 책상에서 B를 누릅니다.
- 워커를 돌려보내기 전에 확인: 터미널 기록과 변경 사항을 검토한 다음 워커의 브랜치와 워크트리를 보존할지 삭제할지 결정합니다.
결론
Agent Office는 AI 코딩 에이전트, Git 워크트리, 공유 터미널, GitHub 보드, 대기열, 알림 및 멀티플레이어 협업을 하나의 공간형 인터페이스로 결합합니다. 하나의 프로젝트 층과 격리된 워커 한 명으로 시작한 다음, 팀이 병렬 AI 지원 개발에 익숙해지면 대기열 작업, 보드 에이전트, 풀 리퀘스트 워크플로 및 구조화된 회의를 도입하세요.