Quick start¶
Install¶
SSL error on pip install?
If pip install fails with an SSL / "ssl module is not available" error,
your default python3 was built without OpenSSL. Use Homebrew's instead:
/opt/homebrew/bin/python3 -m venv .venv && source .venv/bin/activate.
??? note "Run from source instead (for contributors)"
git clone git@github.com:Dafidofff/cluster-job-monitor.git
cd cluster-job-monitor
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
python run.py … is a thin shim equivalent to the
cluster-jobs … command used below.
Try it with no clusters (demo)¶
The fastest way to see the dashboard is the synthetic --demo data — no SSH,
no config, no cluster access needed.
cluster-jobs --demo # live TUI with synthetic data
cluster-jobs --once --demo # print one synthetic snapshot and exit
Want the agent capacity overview?¶
The overview also works against the demo data, so you can see the JSON shape without a cluster:
cluster-jobs --overview --demo # human-readable capacity table
cluster-jobs --overview --demo --json # machine-readable JSON (for agents)
See Agent overview for the full field-by-field breakdown.
Optional: the MCP wrapper¶
To expose the overview to a coding agent over MCP, install the extra SDK:
The core collector and TUI do not depend on this — it's only needed to run the MCP server. See the MCP page for how to register it with Claude Code.
Run it for real¶
Once the demo looks right, point the tool at your own clusters. That means
making each cluster a non-interactive SSH alias and writing a small
clusters.json in your working directory:
Full instructions — including the clusters.json schema — are on the
Configuration page.