Warning
togi is pre-1.0. It writes Curve Optimizer offsets to your CPU through ryzen_smu, and mapping where each CCD fails 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.
Moves a Zen 5 desktop CPU towards deeper per-CCD Curve Optimizer offsets, as far as its own test evidence supports: nights test, days observe. A night runs until you end it (Ctrl-C, F10 in the dashboard, or a reboot); a crash reboot continues it, and the next run after you end it opens the next night.
- Nights map each CCD's failure edge alone, derive each CCD's cap from the measured failure rate, run CO-0 controls and qualify the exact next day profile across the whole coverage matrix.
- Days step the profile towards the cap only after a hold, and a CPU-suspect daily event, including your answer about an unclean end, vetoes the profile and retreats the step.
- 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.
- BIOS stays at CO 0, and a nonzero starting baseline is refused. The day service will apply the day profile at each normal boot (#1218); togi never asks you to enter offsets 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 Ruleset 13 lifecycle: per-CCD mapping of the edge, the cap from the measured slope, CO-0 controls, exact-profile qualification, reproduction, day steps with holds, vetoes and retreats, crash resume and reset;
- a fresh session after a ruleset update, which maps from scratch and keeps the raw day observations (Transitions); a BIOS change stays in the session, which re-qualifies its profile;
- a conclusive failure at all-zero stops tuning with
platform unstable at stock(Dead ends); - reading a session's activity, each CCD's D, S and U with its slope and coverage, the night's queues and shares, qualification progress and the day policy (hold, latest step and its blockers, freeze, firmware validity, events and vetoes) with
status,eventsand the livewatchdashboard (Commands); - console-compatible dashboard rendering and a rich truecolour profile using the same colours with Unicode gauges and text;
- normal-boot observation with
togi day: checkpointed hours per offset profile, clean/unclean ends with the evidence around them, and a question per unclean end that you answer without root. Answers and evidence classify daily events, which veto profiles and retreat day steps.
Built for real hardware, a Granite Ridge desktop running NixOS, and tested piece by piece on one with GRUB:
- 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 unattended tuning boot support GRUB and systemd-boot, with two service restart-limit retry boots before returning to the normal system and durable leave reasons; VM checks cover switching between day and night without tuning hardware.
Not yet:
- applying the day profile in normal boots: the day service will do it (#1218);
- a full night-and-day cycle on real hardware.
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 tonight; Ctrl-C ends the night, the next run opens the next
sudo togi night # GRUB or systemd-boot: confirm, remember the day's selection and reboot into tuning
sudo togi day # observe daily use after a session exists; stop before run/reset
togi day answer <boot> frozen # answer what an unclean end was: frozen, graphics, power-off or unsure
sudo togi day record # journal a crash togi did not observe, with the offsets it ran; stop the day service first
togi status # activity, each CCD's D, S and U, night queues, day policy and observations
togi watch # full-width dashboard: current trial, 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 and run 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 the stage line, one table per CCD with its D, S and U, and the night and day panels beside recent decisions; ? explains the gauges and l opens the journal. Outcome lines come from the tuner itself. Commands describes when the screen redraws.
status adds a Day section after observations exist: observed boots, checkpointed hours per read-back offset profile, clean and unclean ends, and the latest unclean boot's reset reason. Each unclean end becomes a question that status and watch show, with what togi saw, until you answer it with togi day answer <boot> <frozen|graphics|power-off|unsure>; no root shell is needed. The answer counts: frozen makes the end CPU-suspect, which vetoes that profile and retreats the day step, and a later answer can reclassify it (Daily events). togi day notify raises a desktop notification through the installed notify-send, with answer buttons on KDE Plasma. Observation itself writes no offsets. See day observation for service setup and answering.
The NixOS tuning specialisation supports exactly one of GRUB or systemd-boot. sudo togi night selects it persistently, so crash reboots stay in the night; F10 on its dashboard or the power button restores the previous boot selection. See Night and day for saved defaults and menu-started nights.
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 policy in brief: nights and days, D, S and U, 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, and writing a run's retro |
| docs/benchmarking.md | Comparing tuner changes across simulated machines |
| CHANGELOG.md | What changed, newest first |
| GLOSSARY.md | The vocabulary: offsets, profiles, nights and days, D, S and U |
| docs/spec/tuner.md | The Ruleset 13 rules: evidence, caps, night scheduling and day steps |
| 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 or gh stop with that hint outside it. just test is the tight loop. just gate checks formatting, lint, the other supported platform through clippy, the NixOS module's evaluation, changelog fragments, nextest, doc tests, cargo-deny's bans, licenses and sources, cargo-shear, and the board and SQL fixtures. On Linux it also builds the VM tests and every simulator shard, rebuilding only changed inputs; without writable /dev/kvm it skips VMs but runs the shards, and off Linux it skips both, explaining why. just push-fix also builds those heavy checks after its review-fix checks. Pull request CI gates landing on main; the release dispatches every Linux flake check, including VMs and simulator shards (ADR 0074). just check-main dispatches and follows that full run by hand; just check builds every flake check available locally, including package and cargo-deny's advisory audit. Run just to list recipes; Development has the check ladder.
The coordination board (just board) is Nushell. just board-test runs its fixed-fixture assertions without GitHub access, in just gate and the board-test flake check as well as on board changes in just push-fix.
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.