# pi-server-monitor
[](LICENSE)
[](https://pi.dev)
[](https://www.npmjs.com/package/pi-server-monitor)
A high-performance real-time remote server hardware monitoring extension for Pi Agent.
Specifically designed for deep learning model training and cloud GPU clusters.
[简体中文文档](README.md)
---
## Key Features
- **Zero-Config Seamless Auto-Activation**: Kept completely silent with zero overhead by default. When the AI Agent runs any tool involving SSH (e.g. `bash: ssh user@host ...` or `scp`), the extension automatically intercepts the target host and activates monitoring within milliseconds, requiring no manual commands.
- **Ultra-Compact Single-Line Banner**: Renders exactly one compact line directly above the prompt editor (`aboveEditor`), keeping conversation and input areas unobstructed:
```text
tan@100.111.71.70 │ CPU 0% (12C) │ RAM 2.0 GB/30.6 GB (6%) │ GPU [RTX 3070] 0% │ VRAM 130 MB/8.0 GB (2%) │ 47°C 17W
```
- **Connection Multiplexing (OpenSSH ControlMaster)**: Built on OpenSSH socket multiplexing. After the initial handshake, subsequent polls take only 10–20ms with zero re-authentication overhead.
- **Native AI Agent Tool (`get_remote_hardware_info`)**: Exposes hardware metrics to the LLM, enabling autonomous checks of free VRAM before tuning batch sizes or diagnosing data loader bottlenecks.
- **Adaptive Display for Single/Multi-GPU & CPU Nodes**: Seamlessly supports single GPU workstations, multi-GPU nodes (2x/4x/8x), and CPU-only servers.
- **Flexible Display Modes**:
- `compact`: Ultra-compact single line above the editor (Default)
- `widget`: Full multi-line ASCII dashboard box
- `footer`: Compact single-line status in the footer bar
- `both`: Both banner and footer
- `none`: Silent background mode (tool queries remain available)
---
## Installation
### 1. Install via npm (Recommended)
Pi Agent natively supports installing extensions directly from the npm registry:
```bash
# Global installation (persists in ~/.pi/agent/settings.json, recommended)
pi install npm:pi-server-monitor
# Install a specific pinned version
pi install npm:pi-server-monitor@0.2.0
# Install for current project only (persists in .pi/settings.json)
pi install npm:pi-server-monitor -l
```
### 2. Temporary Session Load (Zero Config)
Load the extension on demand without saving to local configuration:
```bash
pi -e npm:pi-server-monitor
```
### 3. Install from GitHub
```bash
pi install github:newbietan/pi-server-monitor
```
---
## Connection & Usage
- **Automatic Mode (Recommended)**: Detects `ssh`, `scp`, `sftp`, and SSH-based `rsync` from tool `command` / `cmd` inputs and user `!` commands. Supports SSH config aliases, explicit ports, and language-tagged Shell code or literal Python `subprocess` argument lists.
- **CLI Flag**:
```bash
pi --ssh-monitor root@192.168.1.100
```
- **Integration with a remote-execution extension that registers `--ssh`**:
```bash
pi --ssh user@my-server:/workspace
```
---
### Detection Boundaries
The extension never infers a host from a script name, an arbitrary `--host` option, or a generic project configuration `target` field. It does not read or execute synchronization scripts. When commands only expose a wrapper script, specify the monitoring target explicitly:
```bash
PI_SSH_TARGET=user@my-server pi
# Or run in Pi: /ssh-mon connect user@my-server
```
Quoted documentation, comments, heredocs, dynamic Python argument lists, and rsync daemon transfers do not activate detection. Put authentication, jump-host, and proxy settings in `~/.ssh/config`; monitoring does not copy arbitrary SSH options from observed commands.
### Environment Variables
| Variable | Meaning | Default |
|---|---|---|
| `PI_SSH_TARGET` | Explicit target; lower precedence than `--ssh-monitor` and `--ssh` | None |
| `PI_SSH_INTERVAL` | Normal polling interval in seconds, at least 1 | `2` |
| `PI_SSH_TIMEOUT` | Total timeout per probe in milliseconds, positive | `20000` |
| `PI_SSH_CONNECT_TIMEOUT` | SSH connection timeout in seconds, positive | `15` |
Invalid numeric values fall back to defaults. Failed polls retry no faster than every 5 seconds; successful polls restore the normal interval. Switching hosts clears cached metrics and ignores results from previous requests. Compact mode distinguishes timeout, authentication, refused connections, and DNS errors instead of displaying stale metrics as live data.
---
## Slash Commands
| Command | Description |
|---|---|
| `/ssh-mon connect ` | Manually connect to target host and start monitoring |
| `/ssh-mon disconnect` | Stop monitoring and release SSH multiplexing sockets |
| `/ssh-mon interval ` | Adjust polling frequency (e.g. `/ssh-mon interval 3`) |
| `/ssh-mon mode ` | Switch display mode: `compact` (default), `widget`, `footer`, `both`, or `none` |
| `/ssh-mon info` | Output a full hardware snapshot into conversation |
| `/gpu` | Quick view of all GPU cards, VRAM usage, temperature, and power draw |
| `/ssh-mon help` | Display help and usage guide |
---
## Agent Tool: `get_remote_hardware_info`
The extension automatically registers `get_remote_hardware_info` for the AI Agent.
### Parameters
- `target` *(string, optional)*: Remote SSH target (`user@host` or `user@host:port`). Defaults to currently connected host.
- `forceRefresh` *(boolean, optional)*: Force an immediate live query instead of returning cached metrics.
An explicit different `target` is queried once without starting or switching continuous monitoring. Refreshing the current target updates its cache. Use automatic detection or `/ssh-mon connect` for continuous monitoring.
### Example Prompts for Pi Agent
- *"Check if the GPU has enough free VRAM for me to increase the batch size from 4 to 8."*
- *"Is the training script running? Check GPU utilization."*
- *"Why is training so slow? Check if there's a CPU or memory bottleneck."*
---
## Requirements
- **Local Machine**:
- Node.js >= 18
- OpenSSH client (`ssh`)
- SSH key-based authentication configured to the remote host.
- **Remote Server**:
- Linux (Ubuntu/Debian/CentOS/Rocky, etc.)
- Python 3 (standard library only; shell fallback is used if Python is absent)
- `nvidia-smi`（for NVIDIA GPU metrics）
---
## License
MIT © [newbietan](https://github.com/newbietan)