Codeman 詳細教學

對應 repo: https://github.com/Ark0N/Codeman（402 stars / 49 forks / v0.6.11 / MIT / 4 個月生命週期，截至 2026-05-22）

1. 專案定位

1.1 它是什麼

arkon 開源的 Claude Code + OpenCode control plane — 一個 Web 控制面板，把 N 個 tmux session 內跑的 AI coding agent 統一管理：

看：哪個 agent stalled / idle / 跑得正歡
控：手機點按就能下命令 / 中斷 / 換 prompt
救：agent crash 自動 respawn（含 health metrics + adaptive timing）
群跑：1 個 session 開 sub-agent 群（team-watcher）
手機操作：Mobile-first UI；通勤路上盯著 agent 跑

1.2 它解決什麼問題

「我同時開 5 個 Claude Code session 在做不同事，但 terminal 切來切去」：Codeman 一個 web UI 全部看
「agent 跑到一半 crash 了，要重啟 + reattach 麻煩」：Respawn Controller 自動處理
「想出門但 agent 還在跑」：Cloudflare Tunnel 一行公網存取
「在手機上看 agent 進度卡頓 / 無法輸入」：mobile-first UI + zero-lag input overlay
「想跑 ralph-loop autonomous，但要看狀態」：自帶 ralph-loop integration + status parser + plan tracker
「subagent 在跑什麼看不到」：Live agent visualization（GIF demo in README）

1.3 與其他 agent control plane 差異

工具	多 session	mobile	respawn	遠端	對應 agent
Codeman	✅ web tabs	✅ first-class	✅ controller	✅ Cloudflare	Claude Code + OpenCode
`tmux` 本身	✅	❌	❌	SSH only	任何
Claude Code 自己 desktop app	多 session 限制	❌	❌	❌	Claude Code only
Aider / Cline	單 IDE 內	❌	❌	❌	自家
`goose` (AAIF)	desktop app	❌	部分	❌	goose 自家

Codeman 獨特：跨 agent（Claude + OpenCode）+ 手機優先 + 自動 respawn + 公網存取一條龍。

1.4 適合誰用

每天同時跑多個 agent 的 power user：通勤 / 開會時也能盯著看
autonomous loop 跑 24/7 的人：ralph-loop + respawn = 真的能放著跑
想做「agent farm」測試：1435 tests 加持，穩定度 OK
小工作室 / 個人 developer：mobile-first 對 solo 工作者尤其方便
企業 DevX 內部 tooling：fork 加自家 auth → 內部 agent dashboard

2. 安裝指南

2.1 一鍵裝（最簡單）

1curl -fsSL https://raw.githubusercontent.com/Ark0N/Codeman/master/install.sh | bash

install.sh 行為：

偵測 OS（macOS / Linux / WSL）
缺什麼裝什麼：Node.js 22+（依 .nvmrc）/ tmux
clone repo 到 ~/.codeman/app
npm install && npm run build
給 PATH 加 codeman shortcut（或 aicodeman）
可選：互動式問是否要設 systemd / launchd

環境變數可控：

1CODEMAN_NONINTERACTIVE=1     # CI 用
2CODEMAN_INSTALL_DIR=...      # 自訂安裝目錄
3CODEMAN_SKIP_SYSTEMD=1
4CODEMAN_NODE_VERSION=22
5CODEMAN_REPO_URL=...         # 用 fork
6CODEMAN_BRANCH=master

2.2 從 source build（contributor）

1git clone https://github.com/Ark0N/Codeman ~/.codeman/app
2cd ~/.codeman/app
3npm install
4npm run build               # 編 TypeScript → dist/
5npm run dev                 # tsx watch（開發用）
6npm test                    # vitest（1435 tests）
7npm run typecheck
8npm run lint

2.3 至少裝一個 AI CLI

1# Claude Code
2npm install -g @anthropic-ai/claude-code
3
4# OpenCode
5npm install -g @opencode/opencode

2.4 啟動 web server

1codeman web
2# → http://localhost:3000
3# → Ctrl+Enter 開新 session

2.5 後台跑（systemd / launchd / WSL）

README 有完整三段 yaml 範本。重點：

Linux：systemctl --user enable --now codeman-web + loginctl enable-linger $USER
macOS：launchd plist 放 ~/Library/LaunchAgents/
Windows：用 WSL bash 跑


flowchart TD
    A[使用者裝完] --> B[codeman web]
    B --> C[Fastify server :3000]
    C --> D[WebSocket bridge]
    D --> E[tmux session 1
claude code]
    D --> F[tmux session 2
opencode]
    D --> G[tmux session N
...]
    C --> H[Browser :3000
xterm.js + WebGL renderer]
    H -.mobile.- M[手機 / 平板]
    C -->|optional| T[Cloudflare Tunnel
公網存取]
    E & F & G -.被監看.- W[respawn-controller
ai-idle-checker
subagent-watcher]
    W --> S[state-store
+ push notifications]

3. 核心架構解析

3.1 三層架構


graph TB
    subgraph "Browser (Mobile / Desktop)"
        FE[xterm.js + WebGL renderer]
        OV[zero-lag input overlay]
        UI[Mobile-first UI
session tabs + plan view + push]
    end
    subgraph "Codeman Server (Fastify :3000)"
        WS[WebSocket bridge]
        REST[REST routes]
        SM[Session Manager]
        SS[State Store]
        PS[Push Store]
        FS[File Stream Manager]
        IM[Image Watcher / paste-image-gc]
        TM[Tunnel Manager]
    end
    subgraph "Watchers / Loops"
        IDLE[ai-idle-checker]
        SUB[subagent-watcher]
        TEAM[team-watcher]
        TR[transcript-watcher]
        RC[respawn-controller
+ adaptive timing
+ health metrics
+ patterns]
        ORC[orchestrator-loop
planner + verifier]
        RAL[ralph-loop
+ stall detector
+ plan tracker
+ status parser]
    end
    subgraph "tmux Sessions"
        T1[tmux: claude code @ /repo-a]
        T2[tmux: opencode @ /repo-b]
        TN[tmux: ... @ /repo-N]
    end
    FE --> WS
    OV --> FE
    UI --> REST
    REST --> SM
    WS --> SM
    SM --> T1 & T2 & TN
    T1 & T2 & TN --> IDLE & SUB & TEAM & TR
    IDLE & SUB --> RC
    RAL --> SM
    ORC --> SM
    RC --> SM
    SM --> SS
    SM --> PS
    PS -.iOS/Android push.- UI
    TM -.optional.- WS

3.2 一個 session 從建立到 stalled 自救的生命週期


sequenceDiagram
    participant U as 使用者
    participant B as Browser
    participant S as Codeman Server
    participant TM as tmux-manager
    participant T as tmux session
    participant A as Claude/OpenCode
    participant RC as respawn-controller

    U->>B: Ctrl+Enter 開新 session
    B->>S: POST /sessions { workdir, agent: claude }
    S->>TM: 建 tmux new-session
    TM->>T: 啟動 tmux
    S->>S: session-cli-builder 組命令
    T->>A: 啟動 claude code（傳 args）
    A-->>T: 開始輸出
    T-->>S: PTY stream
    S->>B: WebSocket 推 stream
    B->>B: xterm.js + WebGL render
    Note over A,RC: agent 跑著
    A->>A: 卡住（infinite loop / API timeout）
    RC->>RC: ai-idle-checker 偵測 idle > N 秒
    RC->>RC: 套用 adaptive timing 規則
    RC->>TM: send-keys C-c → kill agent
    RC->>T: 重啟 agent 進程
    T->>A: agent v2 啟動
    A-->>T: 從上次 transcript 恢復
    Note over U,RC: 自動 respawn 完成，session ID 不變

3.3 Respawn Controller 內部組件

1respawn-controller.ts
2├── respawn-adaptive-timing.ts  # 動態決定「等多久判定 stall」（依歷史）
3├── respawn-health.ts            # session 健康評分
4├── respawn-metrics.ts           # 收集 metrics
5└── respawn-patterns.ts          # 識別 crash pattern（用以決定 strategy）

對應 docs/respawn-state-machine.md 是設計文件 — 看那份能完全理解狀態機。

3.4 Ralph-loop integration

Ralph 是 @ralph-loop skill：autonomous 自迴圈 agent。Codeman 整合：

ralph-config.ts — Ralph 設定
ralph-tracker.ts — 追蹤 Ralph state
ralph-stall-detector.ts — 偵測停滯
ralph-status-parser.ts — 解析狀態
ralph-plan-tracker.ts — plan 進度
ralph-fix-plan-watcher.ts — 自動修 plan
ralph-loop.ts — main loop

Doc：docs/ralph-wiggum-guide.md

3.5 Plan Orchestrator（planner + verifier + loop）

plan-orchestrator.ts + 三個子組件：

orchestrator-planner.ts — 把 task 拆 plan
orchestrator-verifier.ts — 驗證 plan 正確性
orchestrator-loop.ts — 執行 + 監看

設計文件：docs/orchestrator-loop-{architecture,plan,research}.md

3.6 Subagent Visualization

subagent-watcher.ts + team-watcher.ts 偵測 Claude Code 內 spawn 的 subagent，在 UI 視覺化（README GIF 顯示）。

3.7 Zero-lag input overlay（自家 xterm addon）

1packages/xterm-zerolag-input/

是本 repo 子套件。設計目的：遠端 tunnel / SSH 場景時 xterm.js 本身有輸入延遲；overlay 在前端先 echo 字元，再等 PTY 真實 echo 校正 — UX 上「打字 0 延遲」。

設計文件：docs/local-echo-overlay-plan.md + docs/terminal-anti-flicker.md

4. Helper Scripts 詳細用法

4.1 codeman CLI 動詞

命令	用途
`codeman web`	起 Fastify server :3000（最常用）
`codeman web --port 8080`	換 port
`codeman tunnel`	起一次性 Cloudflare tunnel
`codeman tunnel --name <n>`	named tunnel（保留 URL）
`codeman sc`	SSH 替代品（自家 self-contained connection）
`codeman --help`	全部命令

4.2 npm scripts

 1npm run build              # tsc → dist/
 2npm run dev                # tsx watch
 3npm run start              # production（含 NODE_COMPILE_CACHE）
 4npm test                   # vitest 1435 tests
 5npm run test:coverage      # 覆蓋率
 6npm run typecheck          # tsc --noEmit
 7npm run lint / lint:fix    # eslint
 8npm run format             # prettier
 9npm run capture:subagents  # 截 subagent 展示圖
10npm run knip               # dead code analysis
11npm run changeset          # 新 changeset
12npm run version-packages   # apply changesets
13npm run release            # changeset publish

4.3 一鍵 install.sh 細節

46KB script — 包含：

OS / arch 偵測
Node version check（>= 18，target 22）
用 nvm（若已有）或 fnm（fallback）裝 Node
tmux check（macOS brew / Linux apt|dnf|pacman）
Git clone（含 fork override）
npm install
npm run build
寫 PATH wrapper
可選的 systemd / launchd 自動設定
全 set -euo pipefail，安全

4.4 部署為背景服務（README “Run as a background service”）

 1# Linux（systemctl）
 2mkdir -p ~/.config/systemd/user
 3cat > ~/.config/systemd/user/codeman-web.service << EOF
 4[Unit]
 5Description=Codeman Web Server
 6[Service]
 7Type=simple
 8ExecStart=$(which node) $HOME/.codeman/app/dist/index.js web
 9Restart=always
10[Install]
11WantedBy=default.target
12EOF
13systemctl --user enable --now codeman-web
14loginctl enable-linger $USER     # 讓 user session 在登出後仍跑
15
16# macOS（launchd）
17# 看 README 抄 plist

4.5 Cloudflare Tunnel（遠端存取）

1codeman tunnel
2# → 立即發 URL（trycloudflare.com domain）
3# → 適合短暫 demo
4
5# 命名 tunnel（保留 URL）
6codeman tunnel --name my-codeman
7# → 需先 `cloudflared tunnel login` + 設 DNS

文件：README “Remote Access — Cloudflare Tunnel” 段（很長一段）

4.6 SSH 替代 sc

1codeman sc
2# → 從本機 codeman 直連到另一台 codeman；走 WebSocket，不用 SSH key

文件：README “SSH Alternative (sc)” 段。

5. 應用場景

場景	怎麼用
個人多 repo 平行寫 code	開 5 個 session 各自 cd 不同 repo
手機 / 平板上 monitor agent	mobile-first UI，通勤時看進度
agent 在跑長 task，怕掛	啟用 respawn-controller 自動重啟
想跑 autonomous loop 24/7	用 ralph-loop integration + 開 systemd
客戶 demo agent 工作	Cloudflare tunnel 給臨時 URL
小工作室分工	各個成員透過 tunnel 連同一個 Codeman server
想看 subagent 在做什麼	subagent visualization GIF 那個展示
想自家做企業內部 agent dashboard	fork → 加 auth → 內部部署

6. 資安掃描報告

掃描範圍：src/、scripts/、install.sh、packages/xterm-zerolag-input/、docs/、tests/auth-security.test.ts。

風險面	燈號	說明
Shell injection（tmux 命令）	🟢 低	`tmux-manager.ts:991` 用 batch tmux call + 列表式 args；無 shell expansion
公網存取（Cloudflare Tunnel）	🟡 中	開 tunnel 後 server :3000 直接對網路；無 default auth！README 內提示用 named tunnel + DNS protection；近期 `qr-auth-plan.md` 顯示在做 QR-based auth
paste-image 攻擊面	🟢 低（已強化）	PR #90「security(paste-image): harden against 7 findings from PR #84 review」— 顯示作者 / 社群已做完整安全 review
`image-watcher.ts` 處理使用者貼圖	🟡 中	任意 paste → 解析 → 存檔；要看 MIME 校驗與大小限制（buffer-limits.ts 應有上限）
WebSocket auth	🟡 中	看 `web/middleware/auth` 與 `auth-config.ts`；本機 :3000 預設 open；正式 deploy（含 tunnel）必須開
tmux session 隔離	🟢 低	每個 session 獨立 tmux + 獨立 PTY，互不干擾
respawn 安全	🟢 低	respawn-controller 只重啟既有 session 的 agent，不會跨 user 操作
install.sh 安全	🟢 低	`set -euo pipefail`、所有變數引號、版本格式校驗
`eval()` / shell exec	🟢 低	找不到 `eval` / `shell: true`；child_process 用 spawn list form
依賴鏈	🟡 中	package-lock.json 285KB（典型大型 npm），需要 `npm audit`；@fastify/* / xterm 都是主流
QR auth 規劃中	🟡 中	`docs/qr-auth-plan.md` 顯示在做但尚未完成 — 在正式 production 前自己加 auth
systemd / launchd 服務	🟡 中	預設無 password，跑在使用者 user — 個人安全；服務在 startup 啟動意味著「機器登入即活」
1435 tests	🟢 低	含 `auth-security.test.ts`、`memory-leak-prevention.test.ts`、`edge-cases.test.ts` — 工程品質高
最近社群 PR 帶 security 強化	🟢 低	aakhter 對 paste-image 找出 7 個 finding；表示 active 的 community security review

綜合燈號：🟢 / 🟡（無紅燈；個人本機用安全；公網 tunnel 暴露前要先加 auth）

重點建議：

本機個人用：放心 codeman web
想用 Cloudflare tunnel 開公網：等 QR auth 做完，或自己套 basic auth / OAuth reverse proxy
跑 paste-image 場景注意 buffer-limits.ts 設定
跑 systemd 服務時，確認你 host 機器其他人權限（user-level service）

7. FAQ

Q1：跟 tmux 直接用差別？ A：tmux 是 terminal multiplexer；Codeman 是「tmux 之上的 web 控制面 + agent-specific 監看」。Codeman 加值：

可視化 subagent
自動 respawn
手機 UI
公網 tunnel
ralph-loop integration

Q2：跟 goose 衝突嗎？ A：不衝突，是上下層關係。goose 是 agent；Codeman 是 dashboard。理論上你可以讓 Codeman 管 goose session（如果 goose 用 CLI 跑），但目前 Codeman 預設只認 Claude Code + OpenCode。

Q3：跟 agency-agents 的 manager 角色？ A：agency-agents 提供 persona definition；Codeman 提供 session 管理層。兩者完全不同 layer，互補。

Q4：能跑在 server 上 24/7 嗎？ A：可以。systemd + Cloudflare tunnel + auth → ✅。本知識庫的 /loop autonomous 模式也是個應用案例 — Codeman 是天然容器。

Q5：手機 UI 真的能打字嗎？ A：是。zero-lag input overlay（packages/xterm-zerolag-input）是專為手機 / 慢網路設計。

Q6：作者 arkon 是誰？ A：Ark0N (arkon)；個人 maintainer + 2 個高度活躍的社群 contributor（Tenggan Zhang / aakhter）+ 偶發 PR。

Q7：v0.6.x 還在 pre-1.0，穩嗎？ A：1435 tests 通過 + 每天頻繁釋出 + 多個社群 PR。對個人 / 小團隊 production OK；對大型企業可能還想等 v1.0 stable。

Q8：能用在 Windows native（非 WSL）嗎？ A：tmux 需要 unix-like；Windows native 不行。WSL 必須。

Q9：可以 fork 給內部用嗎？ A：MIT license；可以。注意：

自加 auth（必須）
留 Codeman attribution（MIT 要求）
想合 upstream 改動的話走 PR

Q10：和 claude-mem / agentmemory 怎麼搭？ A：Codeman 不管記憶；它只管 session lifecycle。要持久記憶的話 → claude-mem 或 agentmemory，但這兩個是在 agent 內部跑，Codeman 不會插手。

8. 進階技巧

8.1 自訂 ralph-loop 設定

看 src/ralph-config.ts 與 docs/ralph-wiggum-guide.md。可調：

stall 閾值（秒數）
自動 fix plan 啟用
status parser pattern

8.2 自訂 respawn 策略

看 src/respawn-patterns.ts。可加自家 pattern：例如「看到 X log 就重啟」、「連續 Y 次同錯就 escalate」。

8.3 套自家 auth（公網 deploy 前必做）

看 src/web/middleware/。可加：

Basic auth
API key
OAuth reverse proxy（Cloudflare Access）
等 QR auth feature 完成

8.4 整合 hooks（讓 Codeman 跑 Claude Code hook）

看 docs/claude-code-hooks-reference.md + src/hooks-config.ts。Codeman 可在 PreToolUse / PostToolUse 等 Claude Code lifecycle 加 callback。

8.5 把 Codeman 接到本知識庫 / loop

舉例：

1# 在本知識庫目錄起 5 個 session 各做不同 ai-save / gh-tutorial-qd / paper-search
2codeman web
3# 從 web UI 開 5 個 session，每個指定不同 task
4# 用 Codeman 監看，遇到 stall 自動 respawn
5# 出門用手機看進度

8.6 設計企業內部 agent dashboard

fork → 加 SSO（OAuth proxy）→ 接公司 LDAP → 把 session 對應到 user → 內部 self-service AI dashboard。

8.7 看 subagent demo gif

docs/images/subagent-demo.gif — 一鏡到底展示「主 agent 喚醒 5 個 subagent，各自做事，UI 視覺化」。

9. 整合進其他工作流

既有 skill	整合方式
`ai-gh-save`	已存 standard gh-save md 在 `inbox/2026-05-22-github-Ark0N-Codeman.md`
`gh-tutorial-qd`	本檔產出
`ralph-loop`	天然整合！Codeman 本身就是 ralph-loop 的 dashboard
`goose`	互補：goose 是 agent；Codeman 是 dashboard（理論上可管 goose session）
`agentmemory`	Codeman 不管記憶；agentmemory 在 agent 內部跑 — 並行不衝突
`open-slide`	用 Codeman 開 session 跑 `/create-slide` workflow
`agency-agents`	在 Codeman session 裡喚醒 agency persona
`dari-docs`	把 Codeman 自家 README 餵 dari-docs 測 docs 品質
`meeting-intel`	把 Codeman 開做 meeting prep agent’s dashboard
`paper-tutorial`	用 Codeman 開多個 session 並行處理多篇 paper
本知識庫的 /loop	autonomous loop 的天然 frontend
`patent-creator`	謹慎（patent draft 機密邊界禁止對外暴露；若用 Codeman 必須禁用 tunnel + 本機 only）

10. 重點摘要 Checklist

402 stars / 49 forks / MIT / 4 個月生命週期（2026-01-21）
v0.6.11 latest（每天頻繁釋出）
TypeScript + Fastify + xterm.js + WebSocket
對應 Claude Code + OpenCode（兩者擇一或同時用）
1435 個 vitest tests passing
Respawn Controller：adaptive timing + health + metrics + patterns
Ralph-loop 完整整合（autonomous loop）
Plan Orchestrator：planner + verifier + loop
Subagent / team 即時可視化
Mobile-first UI + zero-lag input overlay（自家 xterm addon）
Cloudflare Tunnel 整合（公網存取）
SSH 替代 sc（self-contained connection）
systemd / launchd 自動服務範本
WSL 支援 Windows
18.6KB CLAUDE.md（給 Claude 進 repo 的守則） + 42KB CHANGELOG
主力 contributor + 2 社群 contributor + 安全 review PR
資安綜合燈號：🟢 / 🟡（公網 deploy 前要自加 auth）

11. 進一步閱讀

設計文件（本 repo docs/）：
- orchestrator-loop-{architecture,plan,research}.md — Plan orchestrator 設計
- respawn-state-machine.md — Respawn Controller 狀態機
- ralph-wiggum-guide.md — Ralph-loop 整合
- terminal-anti-flicker.md + local-echo-overlay-plan.md — zero-lag input 原理
- qr-auth-plan.md — 未來 QR auth 設計
- mobile-testing-report.md — 手機 UI 測試
- claude-code-hooks-reference.md — Claude Code hooks 整合
- opencode-integration.md — OpenCode 整合
對應姊妹專案：
- goose (AAIF)：agent 本體（vs Codeman 是 dashboard）— inbox/2026-05-22-tutorial-goose.md
- agentmemory：跨 session 記憶（vs Codeman 管 session lifecycle）— inbox/2026-05-21-tutorial-agentmemory.md
本知識庫先前 tutorial：inbox/2026-05-22-tutorial-goose.md

Codeman 詳細教學 — Claude Code / OpenCode 跨 tmux session 的 Web 控制面（含 respawn / ralph-loop / 遠端存取）

Contents