An auditable AI coding agent that must prove the work it claims.
The execution plane for ICODE-SKILL: contract-driven, fail-closed, resumable, and designed to produce independently verifiable evidence.
简体中文 · Website source · Architecture · Roadmap · Security
Most workflow tools audit what an agent submits. ICODE Agent is built to make the execution process itself auditable: tool decisions, side effects, workflow transitions, artifacts, and verification receipts are recorded while the work happens.
The goal is not to claim that a model never makes mistakes. The goal is narrower and testable:
If the runtime cannot prove completion, it must not report completion.
These are two independent repositories with different responsibilities.
| Component | Responsibility | Relationship |
|---|---|---|
| ICODE-SKILL | Workflow contracts, gates, state machine, and event ledger | Pinned, read-only control plane in vendor/icode-skill |
| ICODE Agent (this repository) | Model loop, tools, approvals, isolation, recovery, and evidence packaging | Autonomous execution plane |
User / CI / local workbench
│
▼
┌──────────────────────────────────────────┐
│ ICODE Agent: model loop · guard · tools │
│ approvals · isolation · recovery │
└──────────────────┬───────────────────────┘
│ explicit JSON/CLI contract
▼
┌──────────────────────────────────────────┐
│ ICODE-SKILL: gates · state · event ledger│
└──────────────────┬───────────────────────┘
▼
verifiable evidence package
The agent never calls /icode plan or another host agent to do its job. It reads the pinned workflow contracts and uses icode_control.py as the only state-writing interface.
Requirements: Git, Python 3.11+, and an initialized ICODE-SKILL submodule. The offline checks do not require a model key.
git clone --recurse-submodules https://github.com/ayukyo/icode.git
cd icode
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e .
icode doctor
icode stepsRun an offline contract handshake in a disposable workspace:
mkdir -p /tmp/icode-handshake
icode handshake --workspace /tmp/icode-handshakeFor repository development, installation is optional:
PYTHONPATH=src python -m icode.cli doctor
python -m unittest
python scripts/preflight.py| Capability | Status | Evidence path |
|---|---|---|
| Dynamic workflow contracts and offline handshake | Ready | icode doctor, icode handshake |
| Model tool loop with bounded file/command tools | Ready | icode step-run, icode task |
| Default-deny guard and human approval protocol | Ready | terminal approver and loopback-only WebUI |
| Side-effect receipts and ambiguous-action stop | Ready | operation start/finish records |
| Evidence package with standalone verifier | Ready | icode evidence, icode verify-pack |
| Checkpoints and evidence-led recovery | Ready | icode recover |
| Local approval console and bilingual project workbench | Ready | icode webui, icode workbench |
| Full six-stage autonomous chain | In progress | plan is proven; later-stage closure remains on the roadmap |
icode task --fixture pycalc --backend openai-compatibleThe fixture is copied to a temporary workspace. The model may edit only that copy, and ICODE runs the acceptance tests again independently instead of trusting the model's claim. An empty test suite is not a pass; the independent run uses python -B -m unittest so verification itself does not create .pyc files that change the tested tree.
For a POSIX Git repository root, --result-commit FULL_COMMIT_SHA optionally compares the stable tested worktree projection with the selected commit tree using read-only Git object queries. This is content equality only; it does not authenticate the commit, its source, or when it was created.
icode task --workspace /path/to/repo --result-commit FULL_COMMIT_SHA \
--backend openai-compatibleTo keep the verification result, explicitly choose a new JSON file; its parent directory must already exist. The receipt stores the exit code, verification metadata (including the command), digests, and workspace/tree/commit bindings, not the full test output. A failed verification still produces a failure receipt when evidence is available; if the receipt cannot be written safely, the command exits with a separate error code.
icode task --fixture pycalc --receipt-out task-verification.json \
--backend openai-compatibleThe receipt can later be included in a standalone-verifiable ticket evidence pack:
icode evidence --ticket /path/to/ticket --dest /path/to/evidence-pack \
--receipt task-verification.jsonicode step-run \
--workspace /tmp/my-project \
--step plan \
--backend openai-compatibleThis creates a ticket, rechecks boundaries, registers the artifact hash, records a reasoning trace, and asks the control plane to advance the state. A blocked transition stays blocked and remains visible.
icode workbench --workspace /path/to/projectThe workbench binds to loopback only. It presents real control-plane ticket state in Chinese or English and keeps technical detail available without making it the default view.
Autonomous execution is an explicit server-side capability. Without
--enable-autonomous, an autonomous ticket remains pending and no executor is
constructed. Even when enabled, creating a ticket does not start model work;
the user must select Start autonomous work in the ticket detail.
icode workbench \
--workspace /path/to/project \
--enable-autonomous \
--backend openai-compatible \
--key-file /path/outside/repository/model-key.txt \
--max-turns 20 \
--isolation autoModel, endpoint, credential, budget, and isolation settings stay inside the
server process. The browser sends only an opaque ticket ID, one of
start/pause/resume/cancel/takeover, and an idempotency ID. Ticket state and
events are still written exclusively through the pinned ICODE-SKILL control
plane.
Pause, cancellation, and takeover take effect at ICODE contract-step
boundaries; an in-flight model call or tool action is not killed midway.
Shutdown records interrupted within a bounded wait, and restart never silently
resumes stale work. A process-local lease prevents duplicate workers inside one
Workbench process, but multiple independent Workbench processes must not point
at the same workspace: the lease is not a cross-process or distributed lock.
Gate, approval, budget, and environment failures remain visible as
blocked, failed, or interrupted rather than being reported as success.
| Command | Purpose | Network |
|---|---|---|
icode doctor |
Inspect contracts, guard, isolation, and local capability | No |
icode steps / brief / outline |
Inspect the workflow contract progressively | No |
icode handshake --workspace <dir> |
Exercise a full offline contract handshake | No |
icode step-run --workspace <dir> --step plan |
Run one contract-governed model step | Yes |
icode task --fixture pycalc |
Run a model task in an isolated fixture copy; Git repositories can optionally compare a result commit tree | Yes |
icode chain --workspace <dir> --requirement "..." |
Attempt the state-derived six-stage chain | Yes |
icode evidence --ticket <dir> --dest <dir> |
Export an independently checkable evidence package | No |
icode verify-pack <dir> |
Verify an exported evidence package | No |
icode recover --ticket <dir> --step <step> |
Analyze or explicitly resume interrupted work | No / resume only |
icode webui |
Start the local approval console on 127.0.0.1 |
No |
icode workbench --workspace <dir> |
Start the single-project ticket workbench | No / Yes in autonomous mode |
Use icode <command> --help for current arguments and defaults.
ICODE is intentionally explicit about what its evidence does—and does not—prove.
- A valid evidence package proves internal consistency and detected tampering; it does not prove that the code is defect-free.
- A package digest needs an external trusted anchor for non-repudiation. A holder of the entire unanchored package can replace and re-sign it.
- The guard is an application-level policy. When no real kernel/container isolation backend is available, ICODE reports that fact and does not call the guard a sandbox.
- Host behavior, model behavior, deployment state, and physical-device results require their own evidence. A generated report is not a device test.
- The public website is static: no login, analytics, trackers, ticket access, or uploads.
Read the security policy before using ICODE with sensitive repositories or credentials.
- Product architecture (Chinese source document) — execution/control-plane boundary and end-to-end data flow
- Design decisions — decisions, rejected alternatives, and invariants
- Roadmap — completed phases and remaining gaps
- Upstream contract — the exact read/write interface to ICODE-SKILL
- Living agent landscape — source-anchored open-source comparisons and adoption decisions
- Brand assets — reused icon source, license, and content hashes
Issues and pull requests are welcome. Start with CONTRIBUTING.md; security-sensitive reports belong in the private path described by SECURITY.md, not in a public issue.
MIT. The reused ICODE icon is copied unchanged from ICODE-SKILL and retains its upstream MIT attribution; see brand assets.