Warning
togi is pre-1.0. It writes Curve Optimizer offsets to your CPU through ryzen_smu, and finding each core's solo limit means running it until it fails: expect crashes, reboots and lost work in anything else running. A new version can refuse to continue a session written by an older one. Run it at your own risk.
Finds the deepest per-core Curve Optimizer offsets a Zen 5 desktop CPU sustains, then keeps testing them through full checking cycles. Choose how long to keep testing with run --cycles N, stop at the first confirmed profile with run --first-result, or let checking continue indefinitely.
- Searches each core alone, makes multi-core R7 cores self-sufficient, hunts unattributed failures outside multi-core R7 and on the idle cores of a failed multi-core R7 load, starts checking one count shallower than each solo limit, takes that margin back in a bounded phase 2 and confirms it before continuing checking.
- Tests with self-checking workloads (mprime, y-cruncher) across light, heavy, load-step, medium, SMT, idle and all-core regimes.
- Survives crashes: the next run reads its journal, attributes the crash and continues.
- Records every action in a plain-text journal you can read to see what it did and why.
- Reports the offsets; you enter them in BIOS.
togi (研ぎ) is Japanese for polishing a blade: coarse stones first, then fine ones, until the edge shows.
Works today, on a simulated 16-core machine:
- the full simulated tuning lifecycle: per-core search, failure hunts, combinations, the two tuning phases, full checking cycles, crash resume and reset;
- a seeded session after a ruleset update or BIOS change, carrying what Transitions and Fact eligibility allow;
- evidence-based hunt duration and singleton-probe scheduling (Hunt);
- R7 full parts and partial chains (Together trial sequence), with voltage-targeted backoff of multi-core R7 failures and located hunts of unattributed ones;
- an all-zero rerun before a failure at CO 0 stops tuning (Dead ends);
- reading a session's phase, BIOS profile with its unconfirmed marker, phase 2's remaining work, hunt, combinations, clean cycles, top requesters, per-workload self-sufficiency, valid trials and Tctl peak with
status,eventsand the livewatchdashboard (Commands).
Built for real hardware, a Granite Ridge desktop running NixOS with GRUB, and tested piece by piece on one:
- the
ryzen_smudriver on full 8-core CCDs only; CCDs with fused-off slots are not yet supported; - mprime and y-cruncher trials, each confined to its cores in a systemd scope;
- machine-check detection from the kernel log;
- the NixOS module and the unattended tuning boot, with two service restart-limit retry boots before returning to the normal system and durable leave reasons; a stubbed NixOS VM check covers the normal-boot fallback.
Not yet:
- a full tuning session on real hardware, from search through a clean cycle.
just sim runs a simulated session from a source checkout, for development; see docs/simulating.md.
togi --version # version and git revision of this build
sudo togi doctor # check this machine is ready for a run, without starting a session or writing the journal
sudo togi run # tune this machine; Ctrl-C stops, the next run resumes
sudo togi run --cycles 3 # stop after three clean cycles, counted from phase 2's confirmation
sudo togi run --first-result # stop at the first confirmed BIOS profile, after phase 1's passed cycle
togi status # phase, BIOS profile, failure points and combinations, per-core offsets and evidence
togi watch # full-width dashboard: current trial, tuner forecasts, every core
togi --state-dir <dir> status # inspect a copied journal
togi --state-dir <dir> events --core 3 # everything that happened to core 3
source <(togi completion bash) # shell completions; the Nix package installs bash, zsh, fish and nushell onesdoctor, run and reset read JSON configuration from /etc/togi/config.json; --config FILE selects another file. The NixOS module generates it from services.togi.settings. See Configuration for keys, defaults and a hand-written example.
The dashboard adapts to wide and compact terminals. It shows checking's cycle checklist, hunt parts and member probes, or search turns beside recent decisions; ? explains the gauges and l opens the journal. Outcome lines come from the tuner itself. Commands describes when the screen redraws.
docs/howto.md walks through installing the NixOS module, a first in-session run and an overnight tuning boot. togi --help lists every command, and togi <command> --help gives its description, examples and flags. Commands describes each one in full.
| Document | Read it for |
|---|---|
| docs/howto.md | Installing togi and running a tuning session |
| docs/how-togi-tunes.md | The tuning sequence, phase costs and ruleset history |
| docs/releasing.md | Versioning, the release workflow and tags |
| docs/simulating.md | Running a simulated session for development |
| docs/reviewing.md | Reviewing current and archived runs with just stats, scoring a run against its forecast, and writing a run's retro |
| docs/benchmarking.md | Comparing tuner changes across simulated machines, and forecasting a real run |
| CHANGELOG.md | What changed, newest first |
| GLOSSARY.md | The vocabulary: offsets, phases, regimes, clean cycles |
| docs/spec/tuner.md | How offsets are searched, hunted and checked, in two phases |
| docs/spec/workloads.md | The workload regimes and how failures are detected |
| docs/spec/journal.md | The journal, its events and the state file |
| docs/spec/runtime.md | Commands, configuration, the tuning boot and the NixOS module |
| docs/adr/ | Why each major decision was made |
| docs/prior-art.md | What was taken from, and left out of, earlier tools |
| Issues | The plan, ideas and bugs; the 1.0 milestone holds what ships in 1.0 |
| CONTRIBUTING.md | Why togi takes no contributions |
| AGENTS.md | Working on togi: workflow, commands and conventions |
togi takes no contributions: issues, comments and pull requests are limited to collaborators. CONTRIBUTING.md has the details.
Copyright (C) 2026 Hleb Shauchenka. togi is free software under the GNU General Public License, version 3 or any later version (GPL-3.0-or-later). Releases up to and including 0.9.0 were published under the MIT license and remain available under it (ADR 0035).
Enter the dev shell with nix develop, or run direnv allow once if you use direnv; recipes that run cargo, the retained Go tools or gh stop with that hint outside it. just test is the tight loop, and just gate runs every non-VM flake check but the sim-suite-* simulator suite shards, which CI and just check on Linux run (just sim-suite or just check-one sim-suite-<i> reproduces them), and cargo-deny's advisory audit, which only the deny flake check runs, sequentially, using a warm cargo cache: formatting, including rustfmt through nix fmt's check, lint, clippy for the host's target and aarch64 macOS, so both platforms from Linux, the NixOS module's evaluation, changelog fragments, the vendored Go modules of the retained tools, their shuffled tests, nextest, doc tests, cargo-deny's bans, licenses and sources, and cargo-shear. just check adds the Linux VM tests and stays CI's definition of green; CI runs every check on every pull request. Run just to list the recipes. AGENTS.md has the agent check ladder and the rest.
CI pushes each check's output to the public Cachix cache togi, and local just check can download those instead of building them. Nix uses the cache only when the machine's own configuration trusts it, so opting in is a choice per machine: either add the cache to the system Nix configuration (/etc/nix/nix.conf, /etc/nix/nix.custom.conf under Determinate Nix, or the same two settings under nix.settings on NixOS or nix-darwin),
extra-substituters = https://togi.cachix.org
extra-trusted-public-keys = togi.cachix.org-1:1EZ2zQlDkNhHZmROZzR0n0/CcYGLPfAmPs+VaGL72LU=
or run cachix use togi as a user listed in trusted-users. After changing the system configuration file, by hand or by running cachix use togi as root outside NixOS, restart the Nix daemon, because it reads that file only when it starts. Local just check then downloads every check whose inputs are unchanged and builds only the rest. Trusting the key makes Nix on that machine accept any store path the cache serves, for any build and not only togi's checks, including outputs pushed by pull request runs that hold the push token (ADR 0021). The flake configures no cache (ADR 0042).
Hardware tests share the host lock with run and reset. Delegated users need lock access as well as SMU and cpuset-controller permissions; see host-lock provisioning. After upgrading from a public-readable lock, quiesce old lock openers or reboot before relying on the new permissions.
togi runs on NixOS. Development works on Linux and on macOS (aarch64-darwin). On macOS, the dev shell, the tests, just sim, every flake check except the VM tests and the trial scope tests, and status, events and reset against a copied state directory work; CI runs only on Linux and builds nothing on macOS (ADR 0061), and togi run exits with an error.