Manage software work as tickets, with AI handling requirements, code changes, and checks.
The execution plane for ICODE-SKILL: contract-driven, fail-closed, resumable, and designed to produce independently verifiable evidence.
简体中文 · Website source · Architecture · Roadmap · Security
Describe a requirement as a ticket and follow its progress, results, and check records. Actions that need your decision request approval. Interrupted work keeps its checkpoint, and recovery checks earlier actions before repeating them.
This remains a software-development tool. The bilingual interface presents tickets and their status, with code changes, execution records, and verification results available on demand. See the capability table below for the current autonomous-workflow status.
These are two independent repositories with different responsibilities.
| Component | Responsibility | Relationship |
|---|---|---|
| ICODE-SKILL | Workflow contracts, gates, state machine, and event ledger | Pinned and read-only; a development submodule, with required runtime resources included in the package |
| 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.
Running an installation package requires Python 3.12+. The pinned core workflow resources are bundled; no separate ICODE-SKILL installation or path setting is needed. Offline checks do not require a model key.
The source-development example below requires Git and the initialized submodule; Linux source builds also need a C compiler. These are not requirements for users installing a wheel.
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 (state and execution-event semantics when contract snapshots are present) |
| 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.