Tachyon MCP server
Commit Nov 9, 2026Lets an AI client monitor NVIDIA GPU metrics, diagnose crashes, forecast VRAM usage, and analyze render job performance.
Also known as formray/tachyon, tachyon
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 1.2.0
- Last commit
- Nov 9, 2026
- License
- Apache-2.0
What is Tachyon MCP?
Tachyon lets an AI client monitor NVIDIA GPU metrics, diagnose crashes, forecast VRAM usage, and analyze render job performance.
Summary generated from the project's README
About Tachyon MCP server
Monitoring NVIDIA GPU performance and diagnosing hardware issues from inside an AI client is what Tachyon GPU monitor enables. This local MCP server provides twelve read-only tools that allow assistants like Claude Desktop or Cursor to inspect real-time metrics, including temperature, power, VRAM, and clock limiters. It is designed for developers and creators who need to understand why a render is slow or why a system crashed.
Users interact with the server via a local pipe setup, requiring no network connection or cloud dependency. The server uses NVIDIA NVML to gather data without affecting GPU clocks or power limits. It features specialized tools such as preflight for checking if a job will fit in memory, diagnose_crash for analyzing unexpected restarts using a 15-minute flight recorder, and get_job_reports to compare current render performance against historical data.
What you can do with it
- 1Diagnose unexpected system crashesHave the AI analyze recent Windows event logs and GPU telemetry to find the probable cause of a driver reset or power failure.
- 2Analyze render job efficiencyRequest a comparison between the current render job and previous runs to identify performance regressions.
- 3Identify VRAM bottlenecksAsk the assistant to determine which specific processes are consuming the most video memory over a set period.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableformray/tachyon is public and reachablegithub.com/formray/tachyon ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-09github.com/formray/tachyon ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubTachyon
The lightest real-time GPU monitor for NVIDIA cards, and the one that explains itself: what is holding your work back, when VRAM will run out, why the PC went down, and how this render compares with the last one. It only reads: it never touches clocks, fans, power limits or the network.
By Formray.
Tachyon 1.0 is the first release. The 5.0 to 5.1.1 builds were previews before 1.0; see the changelog.
Features
New in 1.3:
- Tachy v5, a redrawn Hex. A cleaner hexagon with calm, shape-driven eyes and ambient motion around him: sparkles while rendering, heat waves when hot, a sweat drop when VRAM is full, z's when sleepy. Two built-in skins, Velvet (default) and Aurora flat, switched in Settings > General > Companion skin and applied at once.
- Two new states. VRAM full (92 % or more for about 3 s, off below 85 %) and alarm (a new crash report, a GPU driver reset or the red temperature; at least 10 s, after a crash until you click Hex or the next render starts). Priority: alarm > hot > VRAM full > render > sleepy > idle.
- Preview flags.
tachyon.exe --hex-democycles through the six states;tachyon.exe --hex-state=alarmholds one. Nothing is recorded in preview mode.
New in 1.2:
- 100 ms fast sampling. A small thread reads the clocks, power against the limit,
temperature, load, the clock-limit reasons and the PCIe link ten times a second into a
second fixed-size ring next to the flight recorder (15 minutes, about 352 KB). After a
crash,
diagnose_crashshows the last 30 s at that resolution (last_seconds): a +200 W step within 100 ms, power brake or a hardware slowdown just before the stop are named as hints. Measured on an RTX 5080: no extra CPU above the run-to-run noise (the whole Tachyon stays at 1-1.7% of one core, as 1.1.0), one extra thread. - PCIe link history. The link against the best the GPU and slot can do. Dropping to
Gen1/Gen2 at idle is normal and only counted; a narrower link (x8 in an x16 slot) or a
lower generation under load is logged as degraded, with the recovery. In the status,
the bottleneck evidence and the
get_pcie_linktool. - VRAM per process over time. Every 5 s, from the same per-process counters Task
Manager uses (NVML has no per-process VRAM under Windows' WDDM), logged when it changes.
get_process_vramanswers "who held VRAM between 18:00 and 18:30?" with peak, average and a timeline per process. - Render job markers. A render script calls
tachyon mark start --job "shot 12"andtachyon mark end --job "shot 12"; Tachyon reports the job: duration, average and peak GPU load, peak VRAM, average and peak power, energy (and cost), time clock-limited by power or heat, the PCIe link and the processes holding the most VRAM. In the status and theget_job_reportstool.
New in 1.1:
- Pre-render check: "will this job fit?". When a render job starts, Tachyon looks
for earlier runs of the same job (then the same project, then a similar name) at the
same resolution, read from the job name, the log path or the log's first 16 KB (
4k,2160p,uhd,3840x2160, ffmpegscale=). From the VRAM those runs' own processes needed and what other apps hold right now it says should fit, tight or likely out of memory ("At 4K this job needs ~15.2 GB of VRAM; 14.0 GB is free. Likely out of memory, or very slow."), names idle apps whose memory closing would free, and gives the expected duration. With one loose match or runs that differ a lot it gives no verdict rather than a false alarm. Hex says it once per job when it is confident; the panel shows it under the bottleneck; agents get thepreflighttool. - Crash diagnosis. The crash report now ranks the probable causes with a rough
percentage: unstable RAM or EXPO/XMP, GPU core/memory overclock, power or PSU,
overheating, a driver timeout (TDR) or an application bug. Rules weigh the bug check
code (0x1A, 0x124, 0x116...), NVIDIA driver resets (nvlddmkm 153/13/14), GPU timeout
reports (LiveKernelEvent 141/117), WHEA errors, Kernel-Power 41, application crashes,
the temperatures, power and load before the stop, the GPU's clock offsets and power
limit (saved before the crash) and the RAM speed against its rated speed (SMBIOS). Each
cause lists its evidence and one piece of advice; it says likely or possibly, never
certain, and changes no settings. In the report view (Evidence ›), in Hex's
announcement and in the
diagnose_crashtool, which can also diagnose an older crash straight from the Event Log and the flight recorder (around: "2026-10-22"or"2026-10-26 18:09", matched against the moment the PC actually stopped). A power-off while the GPU was idle points to a power cut or a manual power-off rather than the GPU's power draw; RAM running below its standard speed, a clock that jumped at the restart and a slow BIOS start are reported as signs that the BIOS settings were reset. Times Windows wrote before the stop that are older than the flight recorder's last sample (EventLog 6008's "last sign of life", the last log entry) are marked as stale, never given as the moment the PC stopped.
New in 1.0, all worked out on the PC from the readings Tachyon already takes (no extra polling, no cloud, no AI model):
- Flight recorder. The last 15 minutes of readings (load, temperature, power, VRAM, clocks, limiters, top processes) go into two small fixed-size files on disk, about 170 KB each. If Windows restarts or Tachyon is killed, the next start shows a crash report: what happened in the last minutes, the peaks, which process held the most VRAM and the matching Windows events (Kernel-Power, bug checks, WHEA hardware errors, NVIDIA driver resets), in plain words. Hex mentions it once, with Open report. Export flight recorder in the menu writes CSV and JSON.
- "Why is it slow?" A one-sentence answer to what is holding the work back: the GPU itself, the power cap, heat, the video decoder or encoder, one CPU thread, all CPU cores, VRAM or PCIe, with sure, likely or possibly and the readings behind it. It only changes after the new answer has held for a few seconds, so it does not flicker. In the panel, and in Hex's bubble.
- VRAM forecast. A robust trend of video memory (median slope, so one spike does not count) for the card and each process. It warns only when the trend is steady and the card would be full within 15 minutes ("At this rate VRAM will be full in ~6 min (python.exe is growing by 25 MB/s)"), and points out background apps holding VRAM without using the GPU.
- Job history. Each finished render job, or each GPU-busy stretch of a minute or more,
is saved as one line: duration, average and peak load, fps, energy in Wh (from the
driver's energy counter), peak VRAM and temperature, time spent throttled and the main
limit. The next run of the same job is compared with it ("14% slower than last time; GPU
spent 6 min power-throttled"). Set
price_per_kwhto see what each job cost. - For AI agents:
tachyon.exe mcp. A local MCP server with twelve read-only tools (nine before 1.2), so an assistant like Claude Desktop or Cursor can ask what the GPU is doing and why. Off until you turn it on in Settings (or setagent_api = true); it runs on pipes, not the network. - Settings page. Right-click the island, Hex or the panel and pick Settings…, or use the gear in the panel. Mode, refresh rate, project folders, alert thresholds, the flight recorder, the job history, the energy price and the agent API, with a Copy MCP config button. Changes are saved as you make them and apply at once; only the flight recorder needs a restart.
Carried over from the previews:
- One portable exe, under 3 MB. No installer, no runtime, no OpenGL, no GPU context of its own: it does not wake the GPU it is measuring.
- Aurora glass: frosted glass with a soft live colour field. Its hue follows the GPU load (blue to violet) and an ember warms up with the temperature; it only moves when the values change. Truly borderless: per-pixel alpha, rounded shape, soft shadow, and clicks on the empty area around it go through to the desktop.
- Three modes, switched from the right-click menu (and remembered):
- Island: a capsule at the top of the screen, always on top, with load, temperature, VRAM and power. While a render runs the glow fills it like a progress bar, with the job, the frames and the ETA.
- Companion (Hex): a small hexagon with eyes that sits on your desktop, in two skins (Velvet or Aurora flat). It breathes and blinks now and then, draws a glowing progress line round its edge with sparkles during a render, gets warm (with heat waves) when the card is hot, sweats when VRAM is full, raises the alarm after a crash, a driver reset or at the red temperature, and falls asleep after ten quiet minutes. Click it for a speech bubble: render progress, load and temperature, the biggest VRAM user, four key numbers and Open panel.
- Panel: the full window, sized to its content.
- Everything NVML knows, live: load, temperature, VRAM, power against the limit, core and memory clock, fan, NVENC/NVDEC, PCIe RX/TX, 60 s load and heat traces, and the clock limiters in plain words (power cap, thermal, power brake, …).
- GPU process attribution: each process with a category chip (Game,
Creative app, Script/Python, Browser, AI/agent, System, Other), the program
that launched it (
python.exeviaComfyUI.exe) and its own SM / ENC / DEC % and VRAM. Idle desktop processes are hidden until you click show all. The categories are rules in a toml file. - Optional render tracking: point it at folders of render logs (ffmpeg, tqdm, progress.json, batch and chunk logs) for progress, fps and ETA.
- Light by design: one thread; no constant animation timer (Hex arms one one-shot timer per frame it actually draws); nothing drawn while hidden or behind a fullscreen app; the working set is trimmed after start-up. The 1.0 analysis runs on the samples already taken, and the recorder writes every 5 s and flushes every 30 s.
What is here
| Path | What it does |
|---|---|
src/gui.rs |
Island and panel: Win32 layered windows, layout, input, the right-click menu and the mode switch |
src/gui/companion.rs |
Hex and its bubble: windows, hit testing, frame scheduling, dragging |
src/present.rs |
The layered presenter: premultiplied BGRA DIB pushed with UpdateLayeredWindow(ULW_ALPHA) |
src/aurora.rs, src/glass.rs |
The live colour field and the software glass (tint, sheen, hairline, shadow) |
src/hex.rs, src/png.rs, res/hex/ |
Hex: the embedded sprite atlas, a tiny inflate/PNG reader, the animator, the edge glow and the compositor |
src/gui/views.rs |
The insights block, and the Crash report and History views |
src/voice.rs |
What Hex says in its bubble |
src/explain.rs |
"Why is it slow?": rules with hysteresis over the last 10 s of samples |
src/forecast.rs |
VRAM trend (Theil-Sen slope) per card and process, idle VRAM hogs |
src/recorder.rs, src/report.rs, src/events.rs |
Flight recorder ring files, the crash report and its export, Windows events through EvtQuery |
src/history.rs |
Job detection, energy, jobs.jsonl and the comparison with the last run |
src/insight.rs |
Ties the four together, once per tick, on the samples the monitor already has |
src/mcp.rs, src/agent.rs |
tachyon.exe mcp and the read-only status Tachyon publishes in shared memory |
src/dw.rs |
DirectWrite text through raw COM, glyph runs cached as coverage textures |
src/theme.rs |
Colours, and the WCAG contrast checks every text colour must pass |
src/nvml.rs |
NVML loaded at run time; unsupported calls remembered per device |
src/procinfo.rs, src/monitor.rs |
Launcher chains, category rules, the process filter, the island rules, the sampler |
src/scan.rs, src/parse.rs |
Render log discovery and parsers |
src/config.rs |
tachyon.toml: defaults, thresholds, saving positions and mode without losing your comments |
tests/ |
Parser, discovery, config and synthetic-scenario tests; a fake nvml.dll, a scripted MCP client and wine helpers for screenshots and measurements |
Usage
Download tachyon.exe (or the zip) from the
releases and double-click it.
The exe is not code-signed, so SmartScreen may ask: More info, then
Run anyway. Or build it:
git clone https://github.com/formray/tachyon.git
cd tachyon
# on Windows (MSVC): no icon unless MinGW windres is on PATH
cargo build --release
# from Linux/macOS, as the releases are built:
rustup target add x86_64-pc-windows-gnu # plus mingw-w64 for the linker and windres
cargo build --release --target x86_64-pc-windows-gnu
Click the island to open the panel; the island button (or a double-click on the top band) goes back. Click Hex for its bubble, drag any of them to move it. Right-click anywhere for the menu: GPU, pin, show all processes, Mode (island / companion / panel), Crash report, Job history, Export flight recorder and quit. Tachyon has no taskbar button.
To preview Hex's states without waiting for them: tachyon.exe --hex-demo cycles
through idle, render, hot, VRAM full, alarm and sleepy (8 s each), and
tachyon.exe --hex-state=NAME holds one (idle, render, hot, vram, alarm,
sleepy); a click on Hex goes to the next one. Preview mode uses made-up readings,
records nothing and does not change how Tachyon starts next time.
tachyon.exe --version prints the version.
In the panel, Why? › next to the bottleneck explains it, Open report › opens the crash report and History › the job list. In Hex's bubble, Why is it slow? › swaps the bubble for the answer.
Settings
Settings… in the right-click menu (island, Hex or panel), or the gear at the top of the panel. Five tabs:
| Tab | What you can change |
|---|---|
| General | Display mode (island, Hex, panel); Hex's skin (Velvet or Aurora flat, applies at once); whether Hex announces crash reports; how long Hex's bubble stays open (5–30 s or until clicked); refresh rate (0.25–2 s); Start with Windows; which GPU to show, when there is more than one |
| Projects | Render folders to watch (up to 12): add with a folder picker, remove with × |
| Alerts | Temperature amber and red; VRAM amber and red (GB); how far ahead the VRAM forecast warns (5–60 min, or off) |
| Data | Flight recorder on/off and how many minutes it keeps; job history on/off; energy price and currency; Reset settings; where the data lives and how to remove Tachyon |
| AI agents | Agent API on/off with its live state, Copy MCP config, and what agents can and cannot do |
Use the − and + buttons or the mouse wheel over a value. Each change is
checked against those limits, saved straight away and applied while Tachyon
runs; the flight recorder is the one setting that says restart to apply.
The file is written to a temporary file first and then renamed, so a crash
mid-save cannot leave half a file; the first change of each visit keeps the
previous file as tachyon.toml.bak. Comments, unknown keys and anything the
page does not show are kept. Apart from tachyon.toml, the page changes one
thing only when you ask: Start with Windows (off by default) puts a
shortcut to this tachyon.exe in your Startup folder (shell:startup), and
turning it off removes that shortcut. No registry keys, no admin rights, no
scheduled tasks. Reset settings asks for a second click, keeps the old file
as tachyon.toml.bak and keeps the window positions.
The page works from the keyboard: Tab and Shift+Tab move a focus
ring between controls, Space or Enter presses, ← and → change
a value, a tab or a segment, Ctrl+Tab switches tabs and Esc goes back.
Ctrl+, opens Settings, and Shift+F10 or the menu key opens the
right-click menu. Text colours keep at least 4.5:1 contrast on the glass
(checked by cargo test).
On first start tachyon.toml is written next to the exe with the defaults
and the panel opens with a short hint; there are no personal paths in it and
no render folders until you add one. If the exe sits in a folder you cannot
write to, the file goes to %LOCALAPPDATA%\Tachyon\tachyon.toml instead.
Leave anything out and the default is used; positions and the mode are saved
on exit without touching your comments. If the file cannot be read (a typo,
a wrong type, not UTF-8, larger than 1 MB), Tachyon keeps it as
tachyon.toml.corrupt-<date>-<time>, starts with the defaults and says so in
the panel. Starting tachyon.exe a second time with the same settings file
brings the running one to the front instead of opening another.
TACHYON_CONFIG=<file> and TACHYON_DATA_DIR=<folder> point a copy at its
own settings and data, so two can run side by side.
mode = "island" # "island", "companion" (Hex) or "panel"; unset = from [window] compact
glass = "auto" # "tint" (works everywhere), "blur" (experimental) or "auto"
poll_ms = 1000 # 250-2000
gpu_index = 0 # which GPU, when there is more than one (Settings > General)
pcie = true # PCIe RX/TX (about 20 ms of NVML wait per tick)
fast_sampling = true # 1.2: clocks, power, limits, PCIe link every fast_ms on a thread
fast_ms = 100 # 50-1000
fast_minutes = 15 # 1-60, the fast ring's length (about 352 KB at 15 min / 100 ms)
proc_vram_secs = 5 # 1.2: VRAM per process every N s; 0 = off
process_refresh_secs = 4
process_cmdline = false # true = also show command lines (off for privacy)
process_hide = ["dwm.exe", "explorer.exe", "…"] # hidden unless "show all"
render_roots = [] # folders with render logs; empty = no render tracking
blackbox = true # flight recorder (about 460 KB on disk in total)
blackbox_minutes = 15 # 1-60
history = true # job history
# price_per_kwh = 0.30 # optional: show the energy cost of each job
currency = "EUR"
agent_api = false # true = let `tachyon.exe mcp` answer AI agents
hex_announce = true # Hex opens its bubble once after an unexpected stop
bubble_close_secs = 8 # Hex's bubble closes after this; 0 = only when clicked
hex_skin = "velvet" # 1.3: "velvet" or "flat" (Aurora flat); unknown values = velvet
vram_forecast_minutes = 15 # warn when VRAM would be full this soon; 0 = off
[gpu]
# util_band_low = 77 # optional: cyan inside the band, amber above it
# util_band_high = 82
temp_amber_c = 80.0 # also when Hex gets warm
temp_red_c = 83.0
vram_amber_mb = 14500.0
vram_red_mb = 15600.0
[window] # written for you on exit
always_on_top = true
show_all_processes = false
# island_cx, island_y, x, y, hex_x, hex_y: remembered positions
[[process_rules]] # first match wins; * wildcards; replaces the built-in list
category = "Game"
color = "#FF5C7A"
names = ["*-win64-shipping.exe"]
parents = ["steam.exe", "epicgameslauncher.exe"]
A render machine example is in examples/tachyon_render.toml.
glass = true/false from 4.x files still loads (auto/tint), and a
rig_monitor.toml from the earlier name is read when there is no
tachyon.toml.
Your data and privacy
Tachyon has no network code: no telemetry, no update check, no crash upload, no accounts. It reads the NVIDIA driver, the process list, the render logs in the folders you add and (for the crash report) the Windows event log, and it writes only these:
| Where | What |
|---|---|
tachyon.toml next to the exe (or in %LOCALAPPDATA%\Tachyon) |
your settings, with .bak and any .corrupt-… copies beside it |
%LOCALAPPDATA%\Tachyon\blackbox\ |
flight recorder: two fixed-size files of readings (about 460 KB) |
%LOCALAPPDATA%\Tachyon\history\jobs.jsonl |
finished jobs (rotated at 2 MB, one older file kept) |
%LOCALAPPDATA%\Tachyon\blackbox\fast_a.bin, fast_b.bin |
1.2: 100 ms readings, two fixed-size files (about 352 KB each at the defaults) |
%LOCALAPPDATA%\Tachyon\history\pcie_link.jsonl, proc_vram.jsonl, marked_jobs.jsonl |
1.2: PCIe link changes (1 MB), VRAM per process name (4 MB), marked job reports (4 MB); one older file kept each |
%LOCALAPPDATA%\Tachyon\markers\markers.jsonl |
1.2: written only by tachyon mark, one line per marker |
%LOCALAPPDATA%\Tachyon\exports\ |
only when you choose Export flight recorder |
%LOCALAPPDATA%\Tachyon\logs\ |
a short text file if Tachyon itself crashes: version, time, where in its code it stopped and the error message; no readings |
| your Startup folder | Tachyon.lnk, only while Start with Windows is on |
shared memory Local\TachyonAgentSnapshot |
live status for tachyon.exe mcp, only while the agent API is on; readable by your user account only |
The recorder keeps process names (up to 24 characters), never paths or
command lines (process_cmdline = true shows command lines in the panel,
never stored); the history keeps job names as they appear in your render
logs. Turn either off with blackbox = false or history = false.
To remove Tachyon: turn off Start with Windows (or delete Tachyon.lnk
from shell:startup), quit it, then delete tachyon.exe, its tachyon.toml
and the %LOCALAPPDATA%\Tachyon folder. Nothing else is left behind.
Security model and how to report a problem: SECURITY.md.
Tachyon MCP questions
Can Tachyon change my GPU settings?
No, it is a read-only monitor that never touches clocks, fans, power limits, or the network.
How does it help with GPU crashes?
It provides a crash report that ranks probable causes like unstable RAM, overheating, or driver timeouts using evidence from the flight recorder.