Skip to main content

gtm-pilot

A guided terminal interface for gputaskman.

Python 3.11 or newer MIT License Built with Textual Backend: gputaskman

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 gputaskman or gtm on PATH.
  • 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:

  1. The path passed with --gputaskman.
  2. GTM_PILOT_GPUTASKMAN.
  3. gputaskman on PATH.
  4. gtm on PATH.
  5. The default ~/.local/bin tool 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.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for gtm-pilot 1.0.0
File Size Uploaded Provenance Actions
gtm_pilot-1.0.0.tar.gz 29.6 kB Without provenance Details for gtm_pilot-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for gtm-pilot 1.0.0
File Interpreter ABI Platform Actions
gtm_pilot-1.0.0-py3-none-any.whl Python 3 none any Details for gtm_pilot-1.0.0-py3-none-any.whl

Total release size: 62.0 kB

Release files / gtm_pilot-1.0.0.tar.gz

Download URL gtm_pilot-1.0.0.tar.gz
Size 29.6 kB
Tags Source
SHA-256 checksum
How to use checksums
21d10c2b130f96b23145a5b1af952171d91078023659ba7fe0a37228e9e72069
BLAKE2b-256 checksum
How to use checksums
8b21143f07ac24930c43414b8dbc12af09e47e19902733fe572211e6fe259016
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.0-py3-none-any.whl

Download URL gtm_pilot-1.0.0-py3-none-any.whl
Size 32.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5cdbd30360a53e324fbc49c3f33fda617b1b902056692056c3e0b22c06c5897c
BLAKE2b-256 checksum
How to use checksums
a530ce5c3b101b4e8e0f49cfcc5897b76e7dab45573f5c03c550ab5ec7f5f48b
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.0

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page