# CorePilot (CLI prototype)

This is a working prototype that runs a live single-thread vs. multi-thread
CPU benchmark (trial-division primality checking as the CPU-bound workload)
and reports the resulting ops/sec for each phase plus the scaling factor
between them, alongside a snapshot of Go runtime memory stats. Be aware: the
memory numbers (Sys, HeapAlloc, NumGC) reported by this tool are the
CorePilot PROCESS's OWN Go runtime memory usage only - they are NOT total
system RAM and NOT other processes' memory usage. The full CorePilot product
concept also covers CPU/case temperatures, fan curves, CPU affinity pinning,
and per-app performance profiles; none of those are implemented here because
they require OS-privileged, vendor-specific hardware APIs that a portable,
dependency-free Go CLI cannot reach. See ../plan.md for the full product plan
and roadmap.

## Build from source

Requires Go 1.24+, no external dependencies.

    go build -o corepilot .

Cross-compile for another platform:

    GOOS=windows GOARCH=amd64 go build -o corepilot.exe .
    GOOS=darwin  GOARCH=arm64 go build -o corepilot .

## Usage

    corepilot bench [--duration 500ms] [--json]

Runs a two-phase benchmark:

  1. Single-thread phase: one goroutine runs trial-division primality
     checks over a range of odd numbers for --duration, counting total
     checks performed (ops) and computing ops/sec.
  2. Multi-thread phase: runtime.NumCPU() goroutines run the SAME workload
     simultaneously, each independently checking its own interleaved slice
     of the same number range (no shared state, no locks, no contention)
     for the same --duration. Their ops are summed and combined ops/sec is
     computed.

CorePilot then reports:

  - runtime.NumCPU() (logical core count) and runtime.GOMAXPROCS(0)
  - Single-thread ops and ops/sec
  - Multi-thread ops (summed across workers) and combined ops/sec
  - Scaling factor = multi-thread ops/sec / single-thread ops/sec
    (reported plainly - on an embarrassingly-parallel workload like this,
    a healthy multi-core machine with light other load will show a factor
    approaching NumCPU(), but no editorializing is done about what counts
    as "good": real hardware, virtualization, and system load all affect it)
  - Go runtime memory stats: Sys (total memory obtained from the OS by the
    Go runtime), HeapAlloc (currently allocated heap), NumGC (garbage
    collections so far) - all for the CorePilot process itself, not the
    whole system

Flags:

  --duration duration   How long to run each phase (single-thread, then
                         multi-thread) for. Accepts Go duration syntax,
                         e.g. 500ms, 2s, 1m. (default 500ms)
  --json                Emit structured JSON instead of a text report.
  -h, --help             Show help.

Total wall-clock time for a run is roughly 2x --duration, since the two
phases run one after another, not concurrently.

Example:

    $ corepilot bench --duration 300ms

    CorePilot bench - logical cores: 4, GOMAXPROCS: 4, phase duration: 300ms

    === CorePilot bench report ===
    Logical cores (NumCPU):     4
    GOMAXPROCS:                 4
    Phase duration:             300ms

    Single-thread ops:          999424
    Single-thread ops/sec:      3331413

    Multi-thread workers:       4
    Multi-thread total ops:     2996224
    Multi-thread ops/sec:       9987413

    Scaling factor (multi/single ops-per-sec): 3.00x

    Go runtime memory - Sys:       6642704 bytes (6.33 MB)
    Go runtime memory - HeapAlloc: 85728 bytes (0.08 MB)
    Go runtime GC cycles so far:   0

## Prebuilt binaries

See ../downloads/ for prebuilt binaries (Windows/macOS/Linux) and
CHECKSUMS.txt for their SHA-256 hashes. These are unsigned indie builds -
Windows SmartScreen and macOS Gatekeeper will warn on first run, which is
expected until a code-signing certificate is in place.