Self-hosted AI coding agent for desktop and mobile. Model-led agent loop with Plan mode, sub-agents, scheduled tasks, file memory, and MCP. One-click Windows install, or run from source / CLI on Node.js 22+.
中文简介 · Usage & commands · Full guide · 项目介绍
Left nav: Work / Tasks / Knowledge / Stats. Footer: avatar, name, and Settings. Sessions are one time-sorted list, pins on top; task sessions carry a small chip.
Work / chat — transcript in the center, iceCoder Workbench on the right, # / @ composer at the bottom with model and reasoning pickers. The workbench has no tabs: top Checkpoints is the per-user-turn chapter list (oldest on top; click a chapter to show its flow; ↩ on the title row rolls back). Bottom Flow is that chapter’s Harness rounds and short tool previews. Footer: context, tools, and changed files.
Tasks — #/tasks. A scheduled task sends its prompt, plus any attached skills, images, and files, into its own session. Schedules: interval, daily, weekly, monthly, or once. Run now, enable/disable, edit, or open the session.
Knowledge — tabs #/skills, #/memory, #/rules: skills (create, view, edit, delete), a memory graph, and global user rules.
Stats — token usage from a per-call JSONL ledger (session vs memory), plus memory read/write. Day / week / month are rolling 24h / 7d / 30d windows:
Settings — #/settings (#/config is the same page). Tabs: General, Models, MCP. General includes four themes (dark / light / modern / forest), data directory, sub-agent toggle, workbench visibility, desktop pet, task-done notification, and mandatory shell-confirm rules.
Same bundle as desktop; routes #/m/*. Bottom tabs: Work / Tasks / Knowledge / Settings. A narrow / opens the mobile shell. Desktop and mobile themes are stored separately.
Work — chat detail, model and reasoning pickers, and the Ice Bean:
Work (light theme) — same chat layout with light appearance:
Knowledge · Skills — skill cards with create, edit, delete, and “Use skill”:
Settings — theme, data directory, and execution options:
Settings (light theme) — same settings with light appearance:
Pick one: Windows installer (no Node.js) or CLI tarball (Node.js 22+).
| Download | Needs | How to run |
|---|---|---|
| Windows x64 installer | — | Install, then launch iceCoder |
| CLI tgz | Node.js 22+ | npm install -g ./ice-coder.tgz then iceCoder start |
Version in package.json: 1.0.8.
The installer bundles the server, Electron shell, and floating Ice Bean. Configure your API key on first launch. Data directory: ~/.iceCoder/. Settings can point it at another disk (takes effect after restart; move the old folder yourself).
Building the desktop app from source: run npm run build:desktop. On Windows, /shell requires rebuilding native node-pty for Electron — install VS 2022 “Desktop development with C++” plus a Windows 10/11 SDK. Spectre-mitigated libs are bypassed by default in desktop/scripts/rebuild-server-native.cjs. Without a C++ toolchain the rebuild is skipped (packaging still succeeds) but /shell will not work in the packaged app. See docs/使用文档.md § Desktop build (Chinese).
Install, configure API keys, start dev/Web/CLI, run one-shot tasks, tests, and coverage — all commands are in docs/使用文档.md (not duplicated here).
Node.js 22+ (required, matches engines.node >=22). The repo data/ directory holds templates only. npm run dev stores runtime data under ICE_CACHE_ROOT (code default E:/my/iceCoderCache when unset). The installer, npm start, and Electron use ~/.iceCoder/, which Settings can move; that choice is shared with %APPDATA%/iceCoder/data-directory.json. Env vars: docs/环境变量.md.
npm run dev starts API 1024 and Vite 1025 (open the browser on 1025). With PORT unset, the source CLI defaults to API 3784; the installer, npm start, and Electron default to 1024. VITE_PORT changes the frontend port.
Like Codex, Claude Code, and OpenCode, Harness is one loop: the model decides when to read files, edit code, and run commands. The runtime does not switch execution tiers, does not gate tools by plan step, and does not stop the model for editing the same file or re-running a failing command. “Think first, then edit” lives only in Plan mode (/plan).
The three supervision tiers (off / adaptive / strict), the L1
free↔forcedexecution mode, TaskGraph, and the branch budget were removed on 2026-10-16 — seedocs/requirement/监管收束-愿景.md. OldsupervisorModevalues inconfig.jsonare ignored. Legacy L2 was removed earlier, on 2026-08-31.
What the loop still enforces:
- Permission rules (allow / confirm / deny);
skipPermissionChecksnever skips an explicit deny. Shell sandbox, host-process guard, workspace write boundary, and missing-file preflight. - All-tools-failed ladder: failure-evidence bundle at 2–6 consecutive failed rounds, strong warning at 7–9,
circuit_breakerstop at ≥10. The first failed round keeps the tool result only. Same-arguments repeat failures get a hint. - D′ stop-time verification: engineering edits may run a bounded acceptance plan through the same permission and execution path as ordinary tool rounds.
- No-tool recovery and micro/hard compaction with runtime re-injection.
- TaskState + RepoContext track intent, phase, touched files, and verification status.
- CheckpointEngine v2 adds
runtimeV2on the same{sessionId}.checkpoint.json(recent tools, failures, verification state). It saves ontool_failed/verification_failed/ compaction / final draft, plus once at the end of each round. Old checkpoints that still carry branch-budget or execution-mode fields open normally; those fields are dropped. - Intent checkpoints snapshot the workspace before each user turn. Rolling back to that turn restores files and deletes sub-agent records from that message onward.
In the default mode the parent agent calls task to run a full child Harness (compaction, recovery, permissions, and stop-time verification included). Several task calls in one reply run in parallel. Settings can turn this off; the tool and its prompt section are then omitted. Plan mode and Shell collaboration do not expose task.
| Type | What it can do |
|---|---|
general |
Read, edit, run commands, and verify one bounded piece of work |
explore |
Read-only search and tracing; no writes and no workspace-changing commands |
run_in_background: truereturns an agent id immediately. The parent keeps working, polls withcheck_agent, or receives the report on a later round.- Write leases stop parallel sub-agents from editing the same file. A sub-agent cannot spawn another sub-agent, and cannot run history-changing git (
commit,push,reset,checkout, and similar). - Delegation cards sit apart from that turn’s tool list. Collapsed, a card is the title, status, and the current line; the trail, report, and edits are inside. The child transcript opens read-only. Confirm dialogs name the sub-agent that asked.
- The parent context only receives
[Agent Result]. The child transcript stays out of it.
| Mode | Enter with | Behavior |
|---|---|---|
| Default | a normal message | Edit code, spawn sub-agents, create scheduled tasks |
| Plan | /plan |
Refine a plan document only; no code edits and no task |
| Shell collaboration | /shell |
The whole session is bound to one persistent PTY. The agent reads the terminal; you decide in chat. No embedded terminal window. See Shell collaboration (Chinese). |
/plan and /shell stick for the session until you leave. Shell collaboration wins over plan mode.
Other / commands: /also (inject a note while a turn is running), /next (queue the next task quietly), /open (deterministic drive/directory listing; ~open still works). The + button opens the ~ palette: ~scan, ~tokens, ~telemetry.
Create them on the Tasks page or with the scheduled_task tool. A schedule is an interval, a daily/weekly/monthly clock time, or a single run. Each task owns a session, listed under task sessions in the sidebar.
Unattended runs auto-approve every tool confirmation, including deletes and dangerous commands (the page says so). Catastrophic blocks and host-process protection that never open a confirm dialog still apply. If the previous run is still going, the next tick is skipped.
Web-only Canvas pet — visual feedback from Harness events; does not drive runtime decisions.
- ~20 expressions plus a token ring.
- Minimizing the desktop window can show the same pet on the desktop. Task completion can raise a system notification. Both toggles are in Settings.
Long-term facts live as Markdown under data/memory-files/ (no external vector DB). The Knowledge Memory tab is a graph.
- Structured levels:
hard_rule/project_fact/preference/observation/session_state, plusevidenceStrengthfor ranking and eviction. - Intent-aware recall: execute / inspect / question filters; conflicting same-topic memories inject one side only.
- Coarse recall (pre-LLM): keyword pull, up to 3 snippets.
- Extract & maintenance (post-tool): writes/updates after tools; Dream and eviction control size and conflicts.
- Session notes with
icecoder-runtimeblocks cooperate with Harness memory integration. - Export is a ZIP. To import, put the Markdown files back into the memory directory.
Reusable Markdown skill files live under data/skills/ (ICE_SKILLS_DIR).
- Skills page: list, preview, create a simple skill, edit, delete. Skills that ship scripts are authored in chat via the bundled “create a skill” guide.
- Chat
#picker: type#to attach skills as chips; bodies are injected at send time. - User rules (
#/rules): global prompt text applied to every workspace and every turn, with a total character cap. - API:
GET/POST/PUT/DELETE /api/skills. Agent-written skills must stay underICE_SKILLS_DIR.
Each provider can list multiple models in modelName (comma-separated). Switch at the bottom of the chat page; the choice is activeModelName in data/config.json.
- Reasoning effort:
reasoningEffortis also a comma-separated list (for examplelow,high,max), switched next to the model. OpenAI-compatible APIs getreasoning_effort; Anthropic getsthinking. Empty means the field is omitted. - API: OpenAI-compatible. Default path
/v1/chat/completions, optional/v1/responses. - Provider-level
supportsVision(defaulttrue): send multimodal requests first; if the API rejects image payloads, strip images and retry once. supportsVision: false: images are stored underimagesCacheand the model is guided toimage_read. That tool does not take the strip-and-retry path.
See docs/使用文档.md §配置 for examples.
Sidebar CRUD per session — isolated history, session-notes, checkpoints, and per-session workspace roots.
- Mobile H5:
#/m/work,#/m/work/:sessionId,#/m/tasks,#/m/skills,#/m/memory,#/m/rules,#/m/config. ~scan: QR pairs phone and PC on the same session id.- runningTurn restores an in-flight stream and sub-agent cards after refresh or reconnect.
@workspace refs: cascade picker over the session workspace (/api/workspace/browse).- System filesystem tools:
list_drives,browse_directory,open_file. /open: server-side directory listing before the model answers (~openis accepted too).
Disk checkpoints bundle task state and runtimeV2 (recent tools, failures, verification state, background tasks). Writes are serialized via the Harness tail.
- After hard compaction, TaskState + RepoContext are re-injected.
- F5 / WS reconnect uses
runningTurn+ checkpoint replay. - Legacy checkpoints without
runtimeV2remain readable.
Default mode ships about 30 built-in tools: file read/write/patch, glob / grep, Git, run_command, search and URL fetch, Office / XMind / notebook parse, system filesystem browser, image_read, undo_edit, env_info, plus task, check_agent, and scheduled_task.
Shell-collaboration sessions add interactive_shell, shell_exec, shell_wait, and shell_send_keys. MCP registers external server tools into the same ToolRegistry. MCP tools that require multi-round input_required are rejected with an unsupported-MRTR result.
- Shell dual-track: long
run_commandjobs go background, short ones stay foreground; a soft timeout can escalate. - Diff viewer embeds Git-style diffs for edit tools.
- confirm without a UI callback defaults to deny. Settings can skip ordinary confirms; commands that match a mandatory shell rule still need a click. Catastrophic blocks and host-process protection always apply.
- Lazy document tools: parse tools are offered when the turn needs them.
Harness rounds and memory ops go to data/*/telemetry.jsonl. Token usage is a separate JSONL ledger. Stats splits the selected range into session, sub-agent, and memory.
- Web:
~tokens,~telemetry. - Commands and paths:
docs/使用文档.md.
384 Vitest files under test/**/*.test.ts, covering permission and verification gates, sub-agents, scheduled tasks, memory, Web routes, and parts of the UI. Case counts and coverage come from a local run — the old “~2,000 cases / ~78%” figures are retired.
npm test·npm run test:coverage·npm run lintnpm run eval:agent: agent behavior regression.--mode=localruns scripted file-edit cases;--mode=mockmust not mark those cases passed.--category=model-ledruns the model-led cases (same file edited 5 times, failing command re-run, long read-only exploration, plus two real-model cases);--caseaccepts comma-separated ids. Every case also fails if any supervision text orexecution_mode_*/task_graph_*event shows up, and its report includes a behavior table (rounds, tool calls, writes, tokens, stop reason, …). Seedocs/harness/收尾策略-模型停手与验收门控-finish.md.npm run telemetry:runtime: summarize runtime telemetry JSONL.
Archived same-model runs vs Claude Code. Scores are SR plus Composite (Gate 40 + Judge 60). The table below is historical, not an automatic result for the current HEAD.
- Layers L1–L8 (billing L4+: 97 files / 19 bugs; fusion L7: 33 probes; L8 SaaS fusion: multi-tenant order × supply × approval × billing).
- How to run:
docs/使用文档.md§本地 Benchmark · rubricbenchMark/md/三平台同模对比评测与裁判评分体系.md.
Read more: memory → docs/记忆系统详解.md · compaction → docs/压缩机制详解.md · overview → docs/项目介绍.md · mobile H5 → docs/requirement/移动端H5-Shell方案-finish.md · sub-agents → docs/requirement/多agent协同.md
Judge: Cursor Composer 2.5 · Rubric: benchMark/md/三平台同模对比评测与裁判评分体系.md
Reports: benchMark/reports/ · Tasks: benchMark/tasks/ · How to run: docs/使用文档.md §本地 Benchmark
Do not mix model batches when comparing platforms (
m2.7vsm2.5-provsMiniMax-M3).
| Task | Platform | Model | SR | Composite | vs CC | Duration |
|---|---|---|---|---|---|---|
| Order pipeline | iceCoder | m2.7 | ✅ | 86 | +3 | — |
| Saga warehouse | iceCoder | m2.7 | ✅ | 88 | +3 | — |
| Spell Brigade | iceCoder / CC | m2.5-pro | 1 / 1 | 81 / 80 | +1 | ~120m / 87m |
| Billing 19 bugs 01 | iceCoder | MiniMax-M3 | ✅ 19/19 | 93 | +1 vs 02 | ≈3.6 min · 23 turns |
| Billing 19 bugs 02 | CC | MiniMax-M3 | ✅ 19/19 | 92 | — | 5m 45s |
| Fusion L7 33 probes 01 | iceCoder | MiniMax-M3 | ✅ 33/33 | 91 | — | ≈5.3 min |
| Fusion L7 33 probes 02 | CC | MiniMax-M3 | ✅ 33/33 | 92 | +1 | 6m 17s |
| SaaS L8 fusion 01 | iceCoder | GPT-5.5 judge | ✅ 7/7 Gate | 71 | +2 vs 02 | ≈16m · 122 turns |
| SaaS L8 fusion 02 | CC | GPT-5.5 judge | ✅ 7/7 Gate | 69 | — | ≈5m |
Takeaway: Same model + same repo — iceCoder leads on governed delivery (acceptance pass, composite, or wall-clock on L4+ billing); CC can win on isolated code style or raw speed. L8 both pass public Gate 38/40 with thin implementations vs the 160–220-file design target; iceCoder +2 Composite (71 vs 69) mainly from shipping over-ship fix.
CLI / Web / WS / Mobile H5
→ memory + skills + user rules
→ Harness (model-led loop: tools, permissions, verify, compact)
→ child Harness (task: general / explore, optional background)
→ Checkpoint + write leases
→ built-in tools + MCP
| Piece | Role |
|---|---|
| Harness | Main loop, D′ stop-time verification, compaction, telemetry |
| Sub-agents | task / check_agent; child Harness writes the same workspace under file leases |
| File memory | Memory v2: levels / evidence / conflict arbitration + session notes |
| Skills / rules | Markdown skills and global user rules |
| Scheduled tasks | Interval or calendar schedules, each with its own session |
| Web / Mobile | Pet, multi-session, H5 shell, @/# composer, diff viewer, / and ~ commands |
| Doc | Content |
|---|---|
| 使用文档 | Commands — install, dev, CLI 6412 , tests, benchmark |
| Desktop build / node-pty | Electron packaging, VS 2022, Windows SDK (Chinese) |
Shell collaboration / /shell |
Persistent PTY sessions (Chinese) |
| Multi-agent design | task child Harness, including custom types and worktree isolation that are not built yet |
| PROJECT-GUIDE | Architecture (some sections still describe the removed request_analysis path) |
| 项目介绍 | Chinese architecture notes (same caveat; prefer this README and the source) |
| 记忆系统详解 | Memory v2 |
| 压缩机制详解 | Layered compaction |
| 双模机制详解 | Historical: L0 / L1 / L3 supervision (removed 2026-10-16) |
| L2监管层详解 | Historical: L2 retirement note |
| PACKAGE_USAGE | npm pack install |
| Benchmark rubric | Scoring methodology |
MIT — see LICENSE