Ultimate Tool is a hardware-in-the-loop development platform for the Commodore 64. It connects existing build tools, VICE, C64 Ultimate hardware, tests, and evidence through one deterministic development core.

Its goal is to make ambitious C64 projects easier to attempt, understand, test, and finish. One build artifact can be executed on a deterministic fake target, in VICE, and on an explicitly identified C64 Ultimate, and every attempt is preserved as an immutable, checksummed run record. The artifact and its evidence are shared across those targets rather than re-created per interface.

What exists today #

A Rust development core used by a CLI, a loopback service with an embedded dashboard, and a stdio MCP adapter; none of them reimplements core behavior.
Manifest-driven builds, artifact validation, and versioned mailbox events, with optional cooperative crash, stopped-heartbeat, and timeout classification.
Screen-observation onboarding for existing projects, optional symbol and budget analysis, and read-only diagnostic reports over recorded runs.
A reusable no_std Rust-MOS diagnostic SDK and the C64/host wire protocol.

This page stays short on purpose. The detailed verified history behind these claims lives in acceptance history.

Architecture at a glance #

        +-----------------------------------------------------------+
        |                    ultimate-tool-core                     |
        |  manifest (c64dev.toml) -> build -> artifact -> runner    |
        |  runs & evidence   analysis/budgets   reports   doctor    |
        +----------------+------------------------------+-----------+
                         |                              |
              Target trait adapters                 Surfaces
              - fake    (deterministic, no execution)  - CLI    ultimate-tool
              - vice    (x64sc 3.8)                    - serve  loopback dashboard
              - ultimate (C64 Ultimate, gated)         - MCP    stdio adapter

Every surface calls the same versioned core operations. Reports are read from a single run record and are never computed independently by the dashboard. See architecture for the crate and module layout.

Quick start: a local result without hardware or Docker #

Requirements: Rust 1.93 (or a compatible stable toolchain) and Python 3. VICE and a C64 Ultimate are only needed for the emulator and hardware gates below.

cargo build --locked -p ultimate-tool   # build the host binary
make demo                               # run the first-run example

make demo builds the host binary, then runs the Python driver tools/run_demo.py against the packaged first-run example. That example uses verified prebuilt PRG/map/ELF inputs: it does not compile C64 source, and the deterministic fake target does not execute the PRG. It exercises the shared core, failure classification, source resolution, and immutable evidence only.

Inspect one run directly, then open the dashboard:

target/debug/ultimate-tool runs list --manifest examples/first-run/c64dev.toml
target/debug/ultimate-tool runs report RUN_ID --manifest examples/first-run/c64dev.toml
target/debug/ultimate-tool serve --manifest examples/first-run/c64dev.toml

doctor inspects local files and PATH without launching commands or contacting a target; it grants no hardware authorization and never reports a version or runtime behavior as verified. See your first local result and the example for the full sequence.

Diagnostic reports #

runs report explains what a run recorded and whether its recorded evidence verifies, without re-running it or reading the current manifest. It resolves an instrumented crash site and its bounded inline source chain only from that run's verified build analysis, and withholds an ambiguous or uncovered origin instead of guessing. Detail rows are paged. The CLI envelope stays schema 1; the service envelope is schema 13 and the MCP envelope is schema 12, while the inner report is schema 1 on every surface. See diagnostics.

Verifying emulator and physical behavior #

The same built artifact is what a target run executes, so an emulator pass and a physical pass prove the same bytes.

VICE 3.8. make test-vice runs the root fixture in x64sc.
Physical. Hardware runs require a fresh read-only identity probe, explicit confirmation of the reset count, and a C64 Ultimate on a trusted LAN. The current physical evidence is scoped to one identity-pinned device, not any C64 Ultimate.

Emulator evidence is never reported as physical-device proof, and transport success is reported separately from observable program success.

Status #

No public release, verified artifact download, hosted-CI result or reviewed demo video is claimed. The repository is public on Tangled; local Tangled Spindle workflows and explicit publication tooling are being prepared. No mirror is required.
Workspace crates are at the unreleased 0.2.0-preview.1 version. Accepted Rust-MOS fixtures build from explicitly checksummed SDK inputs at their original compiler paths, preserving their accepted PRGs independently of host crate versions. Development packaging is not a published release. Ubuntu runtime/source verification, human license/privacy review, hosted CI and the new physical comparison remain separate readiness checks. See preview readiness.
Add a screenshot only when a real one can be committed; this page carries no placeholder or broken image reference.

Documentation #

License #

Ultimate Tool is free software licensed under the GNU General Public License, version 3 or (at your option) any later version. See LICENSE.

Clone this repository

Ultimate Tool #