CodeMason README

The project's README from github.com/mufengyuan6/CodeMason. As one markdown file: README.md.

编舟 · CodeMason

CodeMason 不保存任何状态——记忆是投影,回滚是重放,审计是回看。因为一切皆事件,所以敢让 AI 写更少:写错了回滚,写对了复用,每一步都有据可查。

CodeMason 是 Claude Code / Cline 同级的自主编码 Agent:理解需求 → 规划 → 改码 → 验证 → 交付,全链路自主完成。与市面上"把状态当真相"的工具相反,它以事件流为唯一真相(状态永不保存、只从事件推导),因此敢让 Agent 写得更少(YAGNI 独立确定性验证 Hook)——写错了可回滚,写对了可复用,每一步都完全透明可审计。

核心特性

核心特性

架构

headless 内核(Python 进程,--mode rpc / run)
    │  Event Queue(core→界面):TurnStarted / MessageDelta / ExecApprovalRequest / ItemCompleted
    │  Op Queue(界面→core):UserTurnStart / ApprovalResponse / UserTurnCancel / Compact
    ▼
协议层(Op/Event 双向契约,schema 版本化 + Op 幂等)
    ├── JSONL 持久化(append-only 事实源 + flock 写锁)
    ├── OTel 导出(prompt / 审批 / 工具 / 沙箱轨迹)
    └── WebSocket 广播(Web 驾驶舱,多标签页共享会话)
Web 驾驶舱(React 18 + Vite)← 唯一界面
Agent Loop(手写状态机 + 事件流)
  ├── Plan 模式:architect 强模型 → 规划 / 反思归因 / 只读
  ├── Act 模式:editor 快模型 → 10 内置工具(Read/Write/Edit/Bash/Glob/Grep/WebSearch/WebFetch/Monitor/AskUser)
  ├── 控制平面:PolicyEngine 策略判定 → LoopScheduler 调度 → LoopBudget 记账 → OpRouter 按 Op 分派
  ├── 变更控制:工具执行 → staging diff → Hook 验证(YAGNI/安全/权限)→ 落盘 → Git Checkpoint
  ├── 执行沙箱:SandboxProvider(默认 Firecracker microVM,L1-L4 可换)——沙箱内无凭据、网络白名单
  ├── 安全分类器:Tier3 动作 → 两阶段判决(allow/block/alternative/escalate)→ 拦截件进审批收件箱
  ├── 记忆:session / project / global 三层 + T1-T5 压缩
  └── 审计:全部事件落盘 + OTel 导出 + AI 贡献报告(Co-Authored-By trailer)

驾驶舱是任务工作台而非仪表盘集合——三区信息架构:

┌─────────────┬─────────────────────────────┬──────────────┐
│  左·会话栏   │   中·事件流主流程             │  右·监控抽屉  │
│ 列表/新建/恢复│ 审批内联可操作 · 交付横幅      │ 文件/成本/    │
│             │ 首次引导卡 · 任务输入          │ YAGNI/上下文/ │
│             │                             │ 健康信号/贡献  │
└─────────────┴─────────────────────────────┴──────────────┘

切换会话 = 换 JSONL 重放(事件溯源兑现),审批阻塞点始终在事件流内即时可见,监控一律抽屉化不稀释主流程。收件箱语义:人类只审被拦截/存疑的动作(分类器放行的照跑)。

技术栈

快速开始

# 1. 克隆
git clone https://github.com/mufengyuan666/CodeMason.git
cd CodeMason

# 2. 环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

# 3. 启动驾驶舱(默认 127.0.0.1:8765)
python -m src.web.server

# 4. headless 模式(自动化 / CI)
python -m src.cli.main run --task "修复 xxx"
python -m src.cli.main rpc --task "读取 README 并总结"   # 结构化事件输出

Docker 部署:

docker compose up --build
docker run -p 8765:8765 codemason

测试与评测

pytest tests/ -v        # 单元测试(Agent Loop / 协议 / 安全 / 工具 / 记忆 / 压缩 / 沙箱 / 分类器 / Team / 投影)
cd frontend && npx playwright test   # E2E(WebSocket 事件推送 / 审批交互 / 收件箱)

评测体系(自建任务集 + 同模型对照):

CodeMason (mufengyuan6/CodeMason)

event-sourcing
Searching Database…

What is this?CodeMason (编舟) is an autonomous coding agent in the same class as Claude Code or Cline: it understands a requirement, plans, edits code, verifies the result and delivers it, running the whole loop on its own. It is built around the idea that state is never saved — everything is derived from an append-only event log, so every change can be replayed, rolled back or audited.
Is this a CLI agent like Claude Code, or something else?It is a self-hosted web application, not a single CLI binary: a Python FastAPI + WebSocket backend drives a React 18 'cockpit' dashboard with panes for the event timeline, approval inbox, YAGNI board, cost/context view and a read-only code viewer.
How do I get it running?The README's Quick Start points to a Docker deployment, so you stand it up with Docker/Compose rather than installing it manually.
Do I need my own LLM API key?Yes — CodeMason defaults to iFlytek (讯飞) as its model provider, but a pluggable Provider abstraction lets you swap in OpenAI or Ollama instead, with separate 'architect' (planning) and 'editor' (execution) model roles.
How reliable is the safety classifier that blocks dangerous actions?On its own 100-command test set it blocks about 89% of dangerous commands and reports a 0% prompt-injection success rate across 720 scenarios, with a false-positive rate under 1% — not perfect, so three consecutive blocks automatically escalate the task to a human approver.
What does the YAGNI engine actually check?After each generation, an independent static-analysis hook runs the staged diff through a seven-level decision ladder (do you really need it, is it in a library, can the stdlib do it, etc.) and reports lines reduced, dependencies avoided, duplicate implementations and a readability score.
What sandbox backends are available for running code?A SandboxProvider abstraction supports four interchangeable backends: Firecracker microVM (default, isolated kernel + KVM), a hardened Docker container, gVisor (runsc) as a middle tier, or E2B's cloud sandbox.
How does CodeMason's performance get measured against Cline?The same model is run in Cline on an identical 30-task benchmark (bug fixes, features, refactors, tests adapted from SWE-bench and real issues), and results are compared using fail-to-pass rate plus TRAJEVAL's tool-level precision/recall breakdown so only the agent implementation varies.
What is the self-evolving engine?A closed loop (Observe→Analyze→Improve→Verify→Persist) that improves memory, skills, planning, tool usage and the harness itself over time, governed by a rate-limiting EvolutionPolicy with staged shadow→canary→full rollout and automatic rollback.
Size
2.1 MB
Stars
176
Updated
CommitAug 21
Age
2mo
Commits · 90 Days