Home / codetools
codetools
codetools is Mohamed's code-tools engine. It is a Python package for free-threaded python3.14t, built spec-first and project-agnostic, and it works on any checkout. Its capabilities include:
- byte-exact source snapshots and AST queries;
- a knowledge graph with exact blast radius;
- run-once test selection and gates decided in Prolog;
- refactoring, including a type-resolved rename engine;
- tracing, DAP debugging and coverage;
- requirements traceability (RTM) and source control;
- a deploy engine, Incus and OpenTofu infrastructure;
- a code-to-diagram design pipeline, a model batch workbench and templating.
Its product verb is realize. Mohamed, 2026-10-13: "my vision is we design and generate and the llm implements the logic". realize turns an OpenSpec change into skeletons, branch tests, scenarios and traces, has a model fill the edit regions, and gates the result.
It reaches Claude in three ways:
- as the
codetoolscommand (/opt/codetools/bin/codetools); - as an MCP server with one tool per verb;
- as a Claude Code plugin.
orchestrata depends on it. codetools generated the components of orchestrata's packages/ tree, and the codebase-map hook of every project runs it.
The guide
| Page | What it covers |
|---|---|
| Verbs | every CLI verb and sub-verb with its options |
| MCP server | the generated tool table, approval tokens, the ledger, registration |
| Plugin | the Claude Code plugin: skills, commands, hooks, install record |
| Deploy | the release engine, ct-install, identity, rollback, the relation to orchestrata and the hosting question |
| Architecture | the five layers and every one of the 24 packages, each with a component diagram |
| Reference | the generated per-module reference |
| Decisions | the ADR log as recorded in the wiki, plus the decisions of 2026-10-22 and 2026-10-23 |
| Blockers | open gaps with options |
| Runbooks | install, smoke, identity, rollback, MCP fragment, maps |
Status (measured 2026-10-23)
| Item | Measured |
|---|---|
| Checkout | ~/workspace/orchestrata.codetools, branch master at a5c419f5 (2026-10-23 00:01); git remote -v empty |
| Deployed | /opt/codetools/current is release 58dc55ce7d9ba893, commit a5c419f5; ct-install 75 at 2026-10-23 04:01 UTC: IDENTITY OK, SMOKE-OK |
codetools --version |
codetools 0.1.0 a5c419f5720972267039adaf5efc932b19f835a4 |
| Source | 24 packages, 408 .py files under src/codetools/ |
| Tests | 405 test_*.py files under tests/, 19 feature files under specs/features/; test counts not measured (no test run in this documentation pass) |
| Last full verify | the last two verified baselines in /opt/codetools/audit.log (2026-10-18) are full scope and red: 20 and 28 failed |
| Specs | 27 spec files: SPEC-000 to SPEC-018, SPEC-012-2 and SPEC-018-2 to SPEC-018-8, plus MAPPING.md |
| ADRs | 44 in docs/adr/, indexed in docs/adr/README.md |
| MCP | registered at user scope as codetools; 3 running servers still on release 6b4babfeaac2e008 |
| Plugin | codetools@codetools 0.1.0, scope local for ~/workspace, recorded commit 00b1304c |
The 2026-09-21 status on this page is kept in History. It recorded 486 tests passing and 102 of 102 requirements cited for SPEC-000 to SPEC-017. The project has grown since then: SPEC-012-2, SPEC-018 and the SPEC-109 rename engine were added.
Quick commands (deployed copy)
ct=/opt/codetools/bin/codetools
env -u PYTHONPATH $ct --version
env -u PYTHONPATH $ct ast map ~/workspace/<tree> --with-full --out-dir ~/.cache/codetools/maps/<tree>
env -u PYTHONPATH $ct mcp list
env -u PYTHONPATH $ct deploy verify-identity --prefix /opt/codetools --expect-commit "$(awk '/^commit/{print $2}' /opt/codetools/VERSION)"
~/bin/ct-install <label> # deploy master HEAD; see Deploy
~/bin/ct-smoke <commit> # live smoke of the deployed command
Run from a scratch directory, with env -u PYTHONPATH; see Verbs. Test runs need Mohamed's permission and an agreed time budget.
History (2026-09-21)
The index as it stood on 2026-09-21:
- Current state then: all 18 specs (SPEC-000…017) had real modules, per-spec pytest suites and pytest-bdd bindings, committed per spec.
- Verification then: 486 tests passing, 0 failures, 0 xfails;
scripts/rtm_gate.py --project .exited 0 with 102 requirements / 102 CITED. - Live integrations then: real debugpy DAP sessions, real gdb, real swipl 4-port meta-interpreter, real Incus daemon suites, real dulwich with git removed from PATH, SIGKILL-mid-promote atomicity proof.
- Research report:
~/workspace/orchestrata-notes-2026-09-18/SWARM-RESEARCH-2026-09-18.md. - Demo scripts then:
scripts/batch_demo.py,scripts/design_demo.py,scripts/incus_demo.py, run withuv runin the checkout. ADR-0020 later recorded that these nine*_demo.pyscripts are "not shipped, not traced, and not gated".