Agent Office 3D

把你的 AI Coding Agent 變成一間 3D 辦公室裡的員工：誰在工作、誰閒著、誰卡在權限確認，一眼就看得到。閒著的員工會去倒咖啡、上跑步機、摸貓，或是偷玩 Minecraft。

Turn your AI coding agents into staff in a little 3D office. See at a glance who is working, who is idle and who is stuck on a permission prompt. Idle staff grab coffee, hit the treadmill, pet the cat, or sneak in a round of Minecraft.

English ・ Built with Claude Code ・ Made by SparCode studio

畫面都是示範模式（demo），員工、任務、專案和金額全部是虛構的。

用 AI Agent 安裝

下載這個 repo 後，在資料夾裡打開你的 AI Coding Agent（Claude Code、Codex、Cursor…），直接貼上這句話：

請讀這個 repo 的 AGENTS.md，幫我把 Agent Office 裝好並打開麥塊示範。

Agent 會照 AGENTS.md 先跑 npm run doctor 檢查環境，再幫你安裝、啟動示範，並詢問要不要接 Herdr、怎麼客製公司名稱和員工。安裝 Node.js、Java 這類系統軟體前，它會先問你；Minecraft EULA 一定要你自己輸入 yes，Agent 不會代為同意。Claude Code 使用者也可以直接輸入 /setup-office。

快速看麥塊

不用接自己的 Agent，兩個指令就能看到示範員工偷玩 Minecraft（需要 Node.js 20 以上、Java 21 以上）：

npm ci
npm run demo:minecraft

第一次執行會先跑 minecraft:setup：檢查 Java、請你同意 Minecraft EULA、從 Mojang 官方下載伺服器並驗證。產生世界約 1～2 分鐘，機器人進世界後自動打開瀏覽器，幾秒內就會有員工開始玩。按 Ctrl+C 停止，世界會先存檔。

為什麼要你自己輸入 yes？ Minecraft 伺服器軟體屬於 Mojang，執行前必須由使用者本人同意 Minecraft EULA。這個 repo 不能也不會替你同意，所以不附任何 Mojang 檔案，也不會跳過這一步；你不同意的話，就不會下載任何東西。

只想看辦公室（不需要 Java）：npm start。

⭐ 覺得有趣的話，歡迎幫這個 repo 點個星星，讓更多人看到！ ⭐ If you find this fun, a star on the repo would mean a lot!

功能

• 員工即時狀態：每位 Agent 一個座位，狀態燈與名牌顯示「工作中／閒置／完成待命／需要確認」。需要確認時名牌變紅、頭上冒驚嘆號。
• 看終端畫面：點員工可以看他最近的終端輸出（只讀，不能從這裡下指令）。
• 閒置時的小動作：倒咖啡、喝水、跑步機、伸懶腰、打瞌睡、偷玩內建小遊戲；有開 Minecraft 的話，螢幕上是他自己的 Minecraft 機器人第一人稱畫面。
• 布告欄：年度目標、KPI、本週重點、現金流、待辦清單。點布告欄會飛過去打開全螢幕介面，待辦可以直接勾選。
• 書架＝專案資料庫：每本書是一個專案資料夾，點了可以看裡面的 Markdown 文件和截圖（只讀）。
• 任務清單：右側列出任務資料夾裡的檔案，點了看全文。
• 一隻貓：在走道散步、趴睡、跳上空桌。

布告欄	書架專案介面

需求

• Node.js 20 以上（必要）
• Java 21 以上＋ Minecraft Java 版伺服器（選用，只有想讓員工玩 Minecraft 才需要）
• 一個支援 WebGL 的瀏覽器（Chrome、Edge、Safari、Firefox）

支援平台：macOS、Linux。Windows 為實驗性支援：CI 會在 Windows 上跑安裝、語法檢查與示範模式測試，但作者沒有 Windows 實機驗證過，Minecraft 在 Windows 上也還沒實測。

安裝與啟動

macOS／Linux

git clone https://github.com/jefferysha0627/agent-office-3d.git agent-office-3d
cd agent-office-3d
npm ci
npm start

Windows（PowerShell）

git clone https://github.com/jefferysha0627/agent-office-3d.git agent-office-3d
cd agent-office-3d
npm ci
npm start

啟動後會自動打開 http://127.0.0.1:4870/ 。預設是示範模式：不需要任何 Agent，員工狀態會自動輪播，讓你先看到效果。按 Ctrl+C 停止。

設定

把 office.config.example.json 複製成 office.config.json 再修改（office.config.json 不進版控）。沒有 office.config.json 時會直接用範例設定。

cp office.config.example.json office.config.json        # macOS／Linux
Copy-Item office.config.example.json office.config.json  # Windows PowerShell

布告欄與書架的資料格式見 docs/board-format.md。

接上真的 Agent：Herdr 模式

Herdr 是給 Coding Agent 用的終端機多工工具。用 Herdr 開好你的 Agent 之後：

1. office.config.json 的 source.type 改成 "herdr"。
2. staff[].id 改成你在 Herdr 裡的 Agent 名稱。
3. npm start。

辦公室只會呼叫 Herdr 的唯讀指令（herdr agent list、herdr agent read），程式裡有白名單擋住其他指令，不會送鍵、不會替你按確認。Herdr 在 Windows 上目前是 beta；Herdr 模式在 Windows 上未經實測。

想接其他工具？在 lib/sources.js 加一個 adapter，回傳同樣格式的員工清單（名稱、狀態、終端最後幾行）即可。

Minecraft（選用）

員工閒置時會進同一個 Minecraft 世界：挖礦、砍樹、蓋小屋。每位員工一個 Mineflayer 機器人，畫面用 prismarine-viewer 串到他桌上的螢幕。

npm run minecraft:setup

這個指令會依序：

1. 檢查 Java 21 以上；沒有的話，顯示 macOS、Windows、Linux 的安裝方式。
2. 顯示 Minecraft EULA 連結，你自己讀完並輸入 yes 才會寫入 eula=true。輸入其他內容就取消，不會下載任何東西。
3. 從 Mojang 官方版本清單下載 1.21.4 伺服器 jar，並驗證 sha1。
4. 寫入只綁 127.0.0.1 的 server.properties（白名單只有辦公室的機器人）。

完成後把 office.config.json 的 minecraft.enabled 改成 true，再 npm start。第一次產生世界約需 1～2 分鐘。只想先看示範的話，用 npm run demo:minecraft 就好（示範員工＋Minecraft，不用改設定檔）。

• 開了 Minecraft 時，偷玩遊戲一律是 Minecraft，不會換成內建小遊戲；機器人還沒連上時螢幕先顯示載入中。
• 機器人只在員工閒置、而且有人開著辦公室畫面時才會動；員工一回去工作，機器人就停下來。
• 示範模式會讓閒置的員工先去玩 Minecraft、也比較常玩；接真的 Agent 時維持原本的機率（約 12%）。
• 資源用量參考（macOS、5 個機器人、有人在看）：Minecraft 伺服器約 450 MB 記憶體，機器人程序與辦公室伺服器各約 170 MB，CPU 合計約一顆核心的 15%。

從遊戲裡看你的員工

有 Minecraft Java 版的話，可以自己進同一個世界，飛到員工旁邊看他們挖礦、砍樹、蓋房子。

1. 把你的 Minecraft 玩家名稱（3～16 個英數字或底線，下面用 YourName 舉例）加進設定：office.config.json 的 "minecraft": { "guests": ["YourName"] }，或是啟動時用環境變數：

   MC_GUESTS=YourName npm run demo:minecraft                    # macOS／Linux
   $env:MC_GUESTS="YourName"; npm run demo:minecraft            # Windows PowerShell
   

2. 終端機會印出連線方式。在同一台電腦打開 Minecraft Java 版，版本選 1.21.4，多人遊戲 → 直接連線 → localhost:25570。

3. 進來後會自動變成觀察者模式：可以飛、穿牆，不會碰到世界。按數字鍵 1（或滑鼠中鍵打開觀察者選單）選員工，就能跳到他身上看。

4. 想拍影片時，可以加上 DEMO_ALL_IDLE=1（只在示範模式有效），讓所有示範員工一直閒置、持續在 Minecraft 裡活動。

設定的名稱會跟機器人一起放進白名單，不在名單上的人連不進來。

提醒：這個伺服器是離線模式（機器人不需要正版帳號），而且只綁 127.0.0.1，只能在這台電腦上使用。不要改綁定位址或開放對外連線。

• 這個 repo 不包含任何 Mojang 的檔案；伺服器 jar、EULA、世界存檔都在本機的 minecraft/，不進版控。
• 在 npm start 的終端機輸入文字會轉給 Minecraft 主控台（例如 time set day、list）。
• 關閉時會先讓機器人離線，再請伺服器存檔關閉。

常見問題

玩 Minecraft 會耗 Token 嗎？ 不會。Minecraft 裡的員工是照規則跑的 Mineflayer 機器人（找樹、挖礦、蓋東西），不會呼叫任何 AI 模型。只有你的 Agent 真的在工作時才會用到 Token，而且那跟這個辦公室無關。

辦公室會替我的 Agent 下指令嗎？ 不會。辦公室只讀狀態和終端畫面；唯一的寫入是在布告欄勾選待辦（寫進 data/board.json）。

不用接自己的 Agent 也看得到嗎？ 看得到。npm start 是示範辦公室，npm run demo:minecraft 是示範員工加上 Minecraft，都不需要任何 Agent。之後想接真的 Agent，再看下面的「Herdr 模式」。

為什麼我的員工都「不在線」？ Herdr 模式下，staff[].id 要和 herdr agent list 裡的名稱完全一樣。

安全提醒

• 這個辦公室會讀取你的 Agent 終端畫面，裡面可能有程式碼、路徑或其他敏感內容。
• 伺服器只綁 127.0.0.1，並檢查 Host 標頭（防 DNS rebinding）。不要改成對外開放，也不要用反向代理或通道把它公開到網路上。
• 唯一的寫入 API（勾選待辦）要求同源、JSON 與自訂標頭。
• 書架只讀你設定的資料夾，擋路徑穿越與跳出去的符號連結；疑似含金鑰的檔案不會列出。即使如此，也不要把密碼或 token 放在專案資料夾裡。
• Minecraft 伺服器只綁 127.0.0.1，並開啟白名單。

開發

npm run doctor  # 唯讀環境檢查（結束碼 0 全部就緒、2 Minecraft 未就緒、1 辦公室不能跑；加 -- --json 輸出 JSON）
npm run check   # 所有 JS 語法檢查＋ JSON 格式檢查
npm run smoke   # 示範模式冒煙測試（啟動伺服器、打 API、關閉）

網址參數（開發用）：?fast（動作加速）、?idle=coffee（閒置員工都做某個動作，名稱見 public/behavior.js）、?cat=nap（貓的行程）。

server.js              本機伺服器（只綁 127.0.0.1）
lib/config.js          讀設定檔
lib/sources.js         狀態來源 adapter（demo、herdr）
lib/board-store.js     布告欄資料
lib/projects-store.js  書架專案資料庫（只讀）
public/                前端（Three.js）
mc/                    Minecraft 機器人與畫面串流
scripts/               doctor、minecraft:setup、demo:minecraft、語法檢查、冒煙測試
AGENTS.md              給 AI Agent 的安裝流程與硬性界線（CLAUDE.md、.claude/commands/setup-office.md 指向它）
data/                  範例資料（全部虛構）

第三方套件與授權

本專案以 MIT License 授權，著作權人 Jeffery Sha。

其他間接相依套件以 MIT、BSD、ISC、Apache-2.0 為主，完整清單見 package-lock.json，各套件授權見 node_modules/<套件>/LICENSE。prismarine-viewer 套件內附的方塊材質屬於 Mojang，受 Minecraft 使用條款約束；本 repo 本身不包含任何 Mojang 檔案。

本專案與 Mojang、Microsoft 無關，也未獲其認可。Minecraft 是 Mojang Synergies AB 的商標。

English

Agent Office 3D renders your AI coding agents as staff in a small low-poly 3D office running on your own machine.

Install with an AI agent

Clone the repo, open your AI coding agent (Claude Code, Codex, Cursor, …) in the folder and paste:

Read this repo's AGENTS.md and set up Agent Office for me, then open the Minecraft demo.

The agent follows AGENTS.md: it runs npm run doctor, installs and starts the demo, then asks whether to connect Herdr and how to customize the company name and staff. It asks before installing system software such as Node.js or Java, and it will never accept the Minecraft EULA for you: you type yes yourself. Claude Code users can also type /setup-office.

Features

• Live status for each agent: working / idle / done / needs confirmation (red name tag and a "!" bubble).
• Read-only terminal view: click a staff member to see their recent terminal output. You cannot send commands from the office.
• Idle animations: coffee, water, treadmill, stretching, napping, built-in mini games, or Minecraft (each agent gets a Mineflayer bot whose first-person view shows up on their monitor).
• Bulletin board: yearly goal, KPIs, weekly focus, cash flow and a to-do list you can tick off.
• Bookshelf project library: