diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..e2974e3 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,71 @@ +# AGENTS.md + +## Purpose + +CC-Web is a minimal Node.js web shell for running local Claude Code and Codex CLI sessions from a browser. The backend serves static files, exposes a small attachment API, manages detached agent subprocesses, persists session state on disk, and streams runtime events over WebSocket. + +## Key Entry Points + +- `server.js`: main server, auth, WebSocket protocol, attachment API, session persistence, process recovery, notifications. +- `lib/agent-runtime.js`: Claude/Codex spawn specs and runtime event parsing. +- `lib/codex-rollouts.js`: imports local Codex rollout history into cc-web sessions. +- `public/index.html`: UI shell. +- `public/app.js`: frontend behavior and WebSocket client. +- `public/style.css`: UI themes/styles. +- `scripts/regression.js`: isolated end-to-end regression harness using mock Claude/Codex CLIs. +- `scripts/mock-claude.js`, `scripts/mock-codex.js`: fake CLIs used only by regression tests. + +## Run And Check + +```bash +npm start # starts node server.js +node server.js # direct start, default 127.0.0.1:8002 +npm run regression # isolated regression test with mock CLIs +node --check server.js +node --check public/app.js +``` + +Notes: + +- `package.json` only defines `start` and `regression`. +- There is no frontend build step. +- In this workspace, `.env.example` and `.gitignore` are not present even though README mentions them. + +## Runtime Files And Config + +- `.env`: optional local overrides; parsed manually by `server.js`. +- `config/`: runtime config such as `auth.json`, `notify.json`, `model.json`, `codex.json`, `banned_ips.json`, plus Codex runtime-home data. +- `sessions/*.json`: persisted chat sessions. +- `sessions/*-run/`: active run directories with pid/output files; these may survive server restarts. +- `sessions/_attachments/`: uploaded image attachments, cleaned by TTL. +- `logs/process.log`: JSONL lifecycle log with simple rotation. + +Useful env vars from code: + +- `PORT` +- `CLAUDE_PATH` +- `CODEX_PATH` +- `CC_WEB_CONFIG_DIR` +- `CC_WEB_SESSIONS_DIR` +- `CC_WEB_PUBLIC_DIR` +- `CC_WEB_LOGS_DIR` +- `CC_WEB_IP_WHITELIST` + +## Important Workflows + +- Startup binds only to `127.0.0.1`. Reverse proxy/Tailscale exposure is external to this repo. +- Auth is password-or-token over WebSocket. Failed auth bans non-whitelisted IPs after 3 attempts in 5 minutes. +- New messages spawn detached Claude or Codex subprocesses. Output is written to `sessions/-run/output.jsonl` and tailed back to the UI. +- `recoverProcesses()` reattaches to still-running detached processes on server restart and finalizes completed runs from leftover run directories. +- Claude sessions resume via stored `claudeSessionId`; Codex resumes via stored runtime/thread state. +- Attachments are uploaded over `POST /api/attachments`; only PNG/JPEG/WEBP/GIF are accepted, max 10 MB each, max 4 per message. +- Native history import exists for both Claude and Codex. Codex import/delete paths depend on local Codex rollout files and sqlite state. + +## Repo-Specific Safety Constraints + +- Treat `config/`, `sessions/`, `logs/`, `.env`, and any tokens/passwords as sensitive local state. Do not commit secrets or runtime artifacts. +- Be careful with detached child processes. Avoid deleting `sessions/*-run/`, PID files, or killing agent processes unless the task explicitly requires it. +- Prefer facts from code over README. The README is broader and partially out of sync with the checked-out workspace. +- When changing WebSocket message types or session JSON shape, verify both `server.js` and `public/app.js`. +- When changing Claude/Codex spawn behavior, verify `lib/agent-runtime.js` and run `npm run regression`. +- Codex cleanup/import code assumes local `sqlite3` is available in some flows; do not add features that silently require more tooling without documenting it. diff --git a/CHANGELOG.md b/CHANGELOG.md index b5bf088..acde438 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,11 @@ # 更新记录 +## v1.2.10 + +### 改进 + +- 实现与原生 claude code / codex cli 一致的 `/init` 功能 + ## v1.2.9 ### 新功能 diff --git a/README.en.md b/README.en.md index 509072e..1c77bbb 100644 --- a/README.en.md +++ b/README.en.md @@ -244,6 +244,9 @@ node server.js ## Release Notes +- **v1.2.10** + - Implemented `/init` behavior aligned with native Claude Code and Codex CLI + - **v1.2.8** - **Dual-agent (Codex)**: create Claude or Codex sessions on the same backend; agent-isolated sidebar, settings, and import - **Image upload**: drag, paste, or attach images in both Claude and Codex sessions; client-side WebP compression, 7-day server cache, up to 4 images per message diff --git a/package.json b/package.json index 276baf9..06437b8 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "cc-web", - "version": "1.2.8", + "version": "1.2.10", "private": true, "scripts": { "start": "node server.js",