hpcpilot 0.1.0

██╗  ██╗██████╗  ██████╗     █████╗  ██████╗ ███████╗███╗   ██╗████████╗
██║  ██║██╔══██╗██╔════╝    ██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝
███████║██████╔╝██║         ███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║   
██╔══██║██╔═══╝ ██║         ██╔══██║██║   ██║██╔══╝  ██║╚██╗██║   ██║   
██║  ██║██║     ╚██████╗    ██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║   
╚═╝  ╚═╝╚═╝      ╚═════╝    ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝   

See it

Diagnose a pending job, mirror the cluster's docs straight from their URL, then get an answer cited from them. The agent streams markdown, shows each tool as it runs, and asks before anything that changes state. Type / any time for commands.

Why hpcpilot

• 🗣️ Plain-English ops — "show my pending jobs", "who's hogging node midway3-0042", "extend job 1837465 by 2 hours".
• 📚 Knows your cluster — point it at your docs folder or a docs-site URL and it mirrors the whole user guide locally, then cites the right page.
• 🛟 Safe by default — mutating actions (chmod, chgrp, scontrol update) show a preview and need confirmation; secrets are stored 0600, session-only unless you opt in.
• 🔌 Bring any model — it auto-detects an installed claude/codex, or use any API provider; switch and search models live with /model.
• 🎨 A real TUI — gradient banner, streaming answers, live tool status, searchable menus, persistent history.

Quickstart

pip install "hpcpilot[full]"

hpcpilot          # first run walks you through setup

That's it. On first launch a short wizard helps you pick a model, point at your docs, and start asking questions. If you already have the claude or codex CLI installed, hpcpilot uses it automatically — zero config, no API key needed.

Living in the TUI

Type / to open the command menu (arrow keys to choose, Enter to run):

Don't know a model's exact name? Just open /model and type fast, reasoning, gemini, or part of a name — the picker filters as you type.

Teach it your cluster's docs

Point hpcpilot at a local folder of markdown, or at a docs-site URL — a whole user guide with many pages. A URL is crawled once (sitemap, then the site's own nav links) into a local cache, so the agent reads it instantly and offline:

# A local folder…
hpcpilot --docs-base-path /path/to/cluster-docs

# …or mirror an online user guide (the whole site, not one page)
hpcpilot --docs-url https://docs.rcc.uchicago.edu/

You can also paste a path or URL in the wizard's Docs step. Inside the TUI, /docs shows what's loaded, /docs add adds a source, and /docs sync re-crawls when the docs change. Then ask "how do I request a GPU node?" and the agent reads the relevant page and answers with specifics. (URL mirroring uses the full extra.)

🎬 Regenerate the demo

The GIF above is built with vhs from assets/demo.tape, which runs scripts/demo.py — a self-animating session that uses hpcpilot's real banner, streaming renderer, and tool-status output, so it looks exactly like the app while staying fully reproducible (no live LLM or cluster).

conda install -c conda-forge vhs ttyd ffmpeg   # one-time
vhs assets/demo.tape                            # re-renders assets/demo.gif

Edit the questions or timing in scripts/demo.py and re-run to taste.

Install from source

git clone https://github.com/PursuitOfDataScience/hpcpilot.git
cd hpcpilot
pip install -e ".[full]"
hpcpilot

Status

Beta. The portable SLURM tools (squeue/sinfo/scontrol) work on any SLURM cluster; site-specific account/quota commands are configurable. Issues and PRs welcome.

License

MIT — see LICENSE.