cc-windows: Instructions file for Codex

AGENTS.md

This file provides guidance to coding agents (Codex, etc.) when working with code in this repository.

注意:cc-window 监控/管理的目标产品是 Claude Code(它的 claude CLI、~/.claude 目录、agents --json 等都是真实事实,请勿改写成你自己所属的 agent 名)。本文件只是「写给在本仓库干活的 agent」看的说明。

项目本质

cc-window 是一个本地网页版 Claude Code 多会话管理台:一屏监控全机所有 Claude Code 会话状态、网页里新建会话、操作每个会话的交互式终端。仅监听 127.0.0.1:4317。

奠基事实(动手前务必理解):Claude Code 没有对外的 socket / 端口 / HTTP 查询接口。本项目的全部可观测性来自三件事的叠加,改任何状态/会话逻辑都绕不开这三个源:

1. 轮询 claude agents --json(源 A,全量会话真相 + busy/idle/waiting)
2. tail ~/.claude/monitor/events.jsonl(源 B,hooks 写的秒级事件流,给出精确等待原因)
3. 自管 PTY(用 node-pty 启动会话并桥接到浏览器 xterm.js)

详尽且已核实的事实在 docs/02-claude-code-observability.md——它是本仓库的基石文档,涉及 Claude Code 行为时先读它,不要凭记忆推断。

除实时管理外,还有一块历史用量统计(看板顶栏「📊 统计」入口):解析 ~/.claude/projects/**/*.jsonl 历史记录,出活跃热力图 / token 趋势 / 日报等。它复用同一批 transcript 文件,但做的是「回看历史用量」,与上面三源「看实时状态」是不同维度。承接独立工具 cc-journal,合并设计见 docs/11-merge-cc-journal.md。

常用命令

npm install            # postinstall 自动 chmod +x node-pty 的 spawn-helper(见下方坑)
npm run dev            # 开发:vite(5173,HMR)+ 后端(4317),浏览器开 http://127.0.0.1:5173
npm run build && npm start   # 生产:构建后由后端单端口托管,开 http://127.0.0.1:4317
npm run typecheck      # tsc --noEmit —— strict + noUncheckedIndexedAccess,覆盖 server/web 含 *.test.ts
npx tsx web/terminalResize.test.ts  # 跑单个单元测试(无 npm test / 无 runner,逐个 tsx 跑)
npm run install-hooks  # = bash scripts/install-hooks.sh,装监控 hooks 到 ~/.claude/settings.json

• 没有 linter、没有测试 runner(无 npm test),但有单元测试:核心纯逻辑被抽到无副作用的小模块(web/terminalResize.ts、server/tmux-handoff.ts 等),每个配一个同名 *.test.ts,用 node:assert/strict 断言、末尾 console.log("... passed"),逐个 npx tsx <file>.test.ts 跑。改这类逻辑前先看有没有对应 .test.ts,改完把它跑绿。
• 完整校验仪式(见 docs/10):跑齐全部 8 个 *.test.ts + npm run typecheck + npm run build。tsconfig 开了 strict + noUncheckedIndexedAccess。
• hooks 安装器支持 --dry-run(只看 diff)与 --uninstall(只移除本工具的 8 个 hook,保留其它);写入前自动备份 settings.json。需要 jq。
• UI 改动按项目惯例用浏览器实机截图验证(mcp__claude-in-chrome)。