gtm-pilot brings live GPU monitoring, snapshots, recordings, summaries, replays, and
before-and-after comparisons into one focused menu. It runs the gputaskman executable
already installed on your machine and presents its output without changing measurements,
labels, process names, or n/a values.
gtm-pilot is an unofficial companion. It is not part of or affiliated with gputaskman.
Contents
Features
- GPU selection from a detected adapter list.
- Live View with configurable refresh intervals.
- One-shot GPU snapshots.
- Time-based or manually stopped recording sessions.
- Live recording sample counts and progress.
- Recording summaries and offline replays.
- Before-and-after measurements for model loads and scripts.
- Comparisons between saved JSON snapshots.
- Recent-file browsing with path autocomplete.
- Cross-platform sessions-folder opening.
- Keyboard shortcuts and a built-in key reference.
- Compatibility detection for older gputaskman installations.
- Explicit error messages when gputaskman is missing or a command fails.
Requirements
- Python 3.11 or newer.
- gputaskman, available as
gputaskmanorgtmonPATH. - A terminal that supports Textual applications.
gtm-pilot does not install gputaskman automatically. It uses the executable you provide or the first compatible executable it discovers.
Installation
Install gputaskman
Install a released version with uv:
uv tool install gputaskman
For the newest commands, install from source:
uv tool install --force git+https://github.com/shanselman/gputaskman
gtm-pilot uses the summary and replay commands. Run the following to check the
commands provided by your installation:
gputaskman --help
Install gtm-pilot
Install the published tool:
uv tool install gtm-pilot
Or install the current checkout:
git clone https://github.com/Madhur-Prakash/gtm-pilot
cd gtm-pilot
pip install -e .
The editable install keeps source changes available immediately during development.
Usage
Start the application:
gtm-pilot
You can also start the package module directly:
python -m gtm_pilot
Menu actions
| Key | Action | Description |
|---|---|---|
l |
Live View | Opens gputaskman's full-screen monitor. |
s |
Snapshot | Captures one reading for a selected GPU. |
n |
Record Session | Records GPU usage to a JSONL file. |
u |
Summarize Recording | Summarizes a saved recording. |
p |
Replay Recording | Replays a recording offline. |
m |
Measure a Change | Captures before and after snapshots, then runs a diff. |
c |
Compare Snapshots | Diffs two saved snapshots. |
g |
List GPUs | Displays GPU indexes and adapter details. |
o |
Open Sessions Folder | Opens the folder containing saved data. |
r |
Refresh GPUs | Refreshes the detected GPU list. |
? |
Show Keys | Opens the complete keyboard reference. |
q |
Quit | Exits gtm-pilot. |
Keyboard reference
| Context | Keys | Action |
|---|---|---|
| Menu | Arrow keys, Enter |
Navigate and select |
| Forms | Tab, Shift+Tab, Enter, Esc |
Move, submit, or cancel |
| File picker | Tab or Right Arrow |
Complete the current path |
| File picker | Down Arrow |
Move from the path field to the list |
| File picker | Enter |
Open a file or enter a folder |
| Recording | s or Esc |
Stop recording |
| Output | Arrow keys, Page Up, Page Down |
Scroll output |
| Output | Esc, q, Enter |
Return to the menu |
| Anywhere | Ctrl+P |
Open Textual's command palette |
| Anywhere | Ctrl+Q |
Quit |
Configuration
| Command-line option | Environment variable | Default |
|---|---|---|
--sessions DIR |
GTM_PILOT_SESSIONS |
~/gpu-sessions |
--gputaskman PATH |
GTM_PILOT_GPUTASKMAN |
gputaskman, then gtm on PATH |
Examples:
gtm-pilot --sessions D:\gpu-runs
gtm-pilot --gputaskman D:\tools\gputaskman.exe
Command-line options take precedence over environment variables. Additional options:
gtm-pilot --help
gtm-pilot --version
Data files
Saved data defaults to:
~/gpu-sessions
On Windows, this typically resolves to:
C:\Users\<username>\gpu-sessions
Recordings use .jsonl files:
session_2026-11-13_21-18.jsonl
Measurements use paired .json files:
llama3.1-8b_2026-11-13_21-10_before.json
llama3.1-8b_2026-11-13_21-10_after.json
File behavior:
- Existing recordings are appended to by gputaskman.
- Snapshots are never overwritten.
- Repeated measurements receive
-2,-3, and later suffixes. - Measurement labels are made filesystem-safe and limited to 40 characters.
- File pickers show recent files first, with folders before matching files.
- Path matching is case-insensitive and preserves the separator style being typed.
- Hidden files are shown only when the typed name begins with a dot.
Review recordings and snapshots before sharing them. They may contain process names, paths, command lines, and model names from gputaskman's JSON output.
Compatibility and error handling
gtm-pilot discovers gputaskman in this order:
- The path passed with
--gputaskman. GTM_PILOT_GPUTASKMAN.gputaskmanonPATH.gtmonPATH.- The default
~/.local/bintool location.
The application checks gputaskman --help for the diff, record, summary, and
replay commands. Actions unavailable in the installed version are disabled with an
explanation.
If gputaskman cannot be found, gtm-pilot shows installation guidance. Press r after
installing it to search again. If a command fails, its error output is displayed instead
of being silently discarded.
How it works
- gtm-pilot does not read GPU data directly or add monitoring probes.
- Every measurement comes from the installed gputaskman executable.
- Text-producing commands run away from the UI thread and appear in scrollable output pages.
- Live View and Replay hand the terminal to gputaskman's own full-screen interface.
- Record Session counts complete samples as they are written.
- On Linux and macOS, stopping a recording sends
SIGINT. - On Windows, stopping a background recording terminates its process after finished samples have been preserved.
- Windows captured commands run without opening an extra console window.
Development
The package uses a root-level gtm_pilot/ layout and Hatchling as its build backend.
pip install -e .
python -m unittest discover -s tests
uv build
Project layout:
gtm_pilot/
cli.py command-line entry point
app.py Textual application and action dispatch
gputaskman.py executable discovery and command execution
commands.py gputaskman argument builders
sessions.py session paths and filenames
pathcomplete.py file-picker autocomplete
pilot.tcss Textual styles
screens/ application screens and dialogs
tests/ unit and UI tests using a fake gputaskman
License
gtm-pilot is released under the MIT License.
gputaskman is a separate project by Scott Hanselman and remains under its own license.
Metadata
Release files for gtm-pilot 1.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| gtm_pilot-1.0.1.tar.gz | 30.0 kB | Without provenance | Details for gtm_pilot-1.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| gtm_pilot-1.0.1-py3-none-any.whl | Python 3 | none | any | Details for gtm_pilot-1.0.1-py3-none-any.whl |
Total release size: 62.7 kB
Release files / gtm_pilot-1.0.1.tar.gz
| Download URL | gtm_pilot-1.0.1.tar.gz |
|---|---|
| Size | 30.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f6bf1e0aa35bbddb18924f91371b0d422e2533633e4975408d18f18dd5518f78
|
|
BLAKE2b-256 checksum How to use checksums |
3c0f6f7f8c3e4069db9c041bd30e2d9a67afd31302714a35351ea2e36bb2830c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.8
|
Release files / gtm_pilot-1.0.1-py3-none-any.whl
| Download URL | gtm_pilot-1.0.1-py3-none-any.whl |
|---|---|
| Size | 32.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8975390007a1866f3081d1915f13ba4d08ced08689ddf7627a9d10a7682f5aba
|
|
BLAKE2b-256 checksum How to use checksums |
4ae9d48469b87e4586c13838b0dd391f926d3a75d5c6660d766efb5d02139153
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.8
|
Security for gtm-pilot 1.0.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.