{"id":"top","repo":"xpufx/paseo","url":"https://github.com/xpufx/paseo/tree/main/plugins/top","name":"top","description":"Live host system resource monitor and telemetry provider for [Paseo](https://github.com/getpaseo/paseo) (v0.8+).","categories":["monitoring"],"platforms":[],"caveats":[],"images":["https://raw.githubusercontent.com/xpufx/paseo/85da190e0951f086385d969aa45270abbee01bfd/plugins/top/screenshots/paseo-top-general-view.jpg","https://raw.githubusercontent.com/xpufx/paseo/85da190e0951f086385d969aa45270abbee01bfd/plugins/top/screenshots/paseo-top-dashboard.jpg","https://raw.githubusercontent.com/xpufx/paseo/85da190e0951f086385d969aa45270abbee01bfd/plugins/top/screenshots/1-paseo-top-modal-system.jpg","https://raw.githubusercontent.com/xpufx/paseo/85da190e0951f086385d969aa45270abbee01bfd/plugins/top/screenshots/2-paseo-top-modal-workspace.jpg","https://raw.githubusercontent.com/xpufx/paseo/85da190e0951f086385d969aa45270abbee01bfd/plugins/top/screenshots/3-paseo-top-modal-settings.jpg","https://raw.githubusercontent.com/xpufx/paseo/85da190e0951f086385d969aa45270abbee01bfd/plugins/top/screenshots/4-paseo-top-modal-about.jpg"],"health":{"manifestValid":true,"hasReadme":true,"hasLicense":true,"hasTests":true,"hasTypecheckScript":true,"updatedRecently":true},"scannedAt":"2026-09-14T08:29:22.379Z","addedAt":"2026-09-13T16:54:35Z","path":"plugins/top","version":"0.4.0","security":{"status":"passed","blockingFindings":0,"advisoryFindings":0,"scannedAt":"2026-09-14T08:27:38.731Z","commit":"85da190e0951f086385d969aa45270abbee01bfd"},"paseoVersionRequirement":">=0.8.0","manifest":{"id":"top","requirements":{"paseo":">=0.8.0"}},"repoMeta":{"stars":0,"defaultBranch":"main","pushedAt":"2026-09-14T07:30:44Z"},"owner":{"login":"xpufx","avatarUrl":"https://avatars.githubusercontent.com/u/25581961?v=4"},"installNotesHtml":"<p>Install using the native Paseo monorepo subpath syntax:</p>\n<pre><code class=\"language-bash\">paseo plugin add xpufx/paseo --path plugins/top\n</code></pre>\n<p>For local development:</p>\n<pre><code class=\"language-bash\">git clone git@github.com:xpufx/paseo.git\ncd paseo\npaseo plugin add ./plugins/top\n</code></pre>","readmeText":"# paseo-top\n\nLive host system resource monitor and telemetry provider for [Paseo](https://github.com/getpaseo/paseo) (v0.8+).\n\nDisplays real-time host metrics, session metadata, turn telemetry, and custom pill widgets directly in the composer track bar without cluttering the interface. Automatically stamps performance summaries into agent conversation timelines and provides an interactive modal dashboard with live gauges.\n\n> [!NOTE]\n> **Prerequisites & Platform Support**:\n> - Zero install requirements: the helper runtime is vendored (`client|server|shared/vendor/paseo-plugin-helper/`, pinned helper 0.4.0-beta.12 — see `shared/vendor/paseo-plugin-helper/README.md`), so Paseo installs this plugin with no build step and no npm/registry access. For local development (`typecheck`/`test`), Node.js (v18+) is enough.\n> - Developed and tested primarily on **Linux** (using `/proc` telemetry), with fallback support for **macOS** and **Windows** host platforms.\n\n| General Composer View | Dashboard View |\n| :---: | :---: |\n| [![General Composer View](screenshots/paseo-top-general-view.jpg)](screenshots/paseo-top-general-view.jpg) | [![Dashboard View](screenshots/paseo-top-dashboard.jpg)](screenshots/paseo-top-dashboard.jpg) |\n\n| System Resources Modal | Workspace Context Modal | Settings Modal | About Modal |\n| :---: | :---: | :---: | :---: |\n| <img src=\"screenshots/1-paseo-top-modal-system.jpg\" alt=\"System Resources Modal\" width=\"100%\" /> | <img src=\"screenshots/2-paseo-top-modal-workspace.jpg\" alt=\"Workspace Context Modal\" width=\"100%\" /> | <img src=\"screenshots/3-paseo-top-modal-settings.jpg\" alt=\"Settings Modal\" width=\"100%\" /> | <img src=\"screenshots/4-paseo-top-modal-about.jpg\" alt=\"About Modal\" width=\"100%\" /> |\n\n\n## Core Capabilities\n\n### 1. Host Resource Telemetry\n- **CPU & Memory Tracking**: Continuous utilization monitoring with Linux `/proc/meminfo` available-RAM accuracy.\n- **Load Averages & Architecture**: Reports 1m, 5m, and 15m load averages, physical and logical CPU core counts, platform architecture, and host uptime.\n- **Three-Tier Status Indicators**:\n  - **Success / Normal**: Below 60% CPU and 70% RAM.\n  - **Warning / Elevated**: 60% to 84% CPU or 70% to 84% RAM.\n  - **Danger / Critical**: 85% or higher CPU or RAM.\n- **Adaptive Polling**: Throttles telemetry refresh rates when the modal is closed to conserve CPU cycles.\n\n### 2. Workspace & Agent Session Context\n- **Git Branch & Worktree**: Monitors active branch name and worktree directory path.\n- **Git Diff Shortstats**: Summarizes uncommitted file changes, lines added, and lines deleted.\n- **Agent Identity**: Displays active agent session ID, display name, model name, and LLM provider.\n- **Agent Activity State**: Reflects lifecycle state (running, idle, waiting for input).\n\n### 3. Turn Telemetry & Token Accounting\n- **Lifetime Turn Counter**: Tracks conversation turn counts throughout the session.\n- **Token Accounting**: Captures input tokens, cached prompt tokens, output tokens, and context window utilization percentage.\n- **Cost Estimation**: Reports cumulative estimated USD cost per turn when supported by the provider.\n- **Tool Execution Auditing**: Counts tool invocations and execution error tallies per turn.\n- **Timeline Turn Telemetry**: Automatically appends a structured telemetry card to the conversation timeline at the conclusion of each agent turn.\n\n### 4. Fleet & MCP Integration\n- **MCP Server Health**: Bridges with `mcp-tools` to monitor connected MCP servers, distinguishing healthy, degraded, or offline servers alongside latency figures.\n\n### 5. Flexible Display Modes\n- **Cycle Mode**: Automatically cycles through enabled metric segments on each refresh interval.\n- **All Mode**: Combines all enabled metrics into a single unified ticker.\n- **Multiple Mode**: Splits selected metrics into distinct, individual pills placed side-by-side in the composer track bar.\n\n> [!NOTE]\n> Displaying too many pills separately in Multiple Mode may cause UI performance issues. Consider using **Cycle Mode** or **All Mode** when monitoring multiple metrics simultaneously.\n\n### 6. Dual Surface Routing Matrix\nEvery metric can be routed independently via settings to:\n- **Pill**: Render in the composer track bar.\n- **Timeline**: Render in the turn completion card.\n- **Both**: Display in both locations.\n- **None**: Disable the metric entirely.\n\n### 7. Extensible Custom Metric Pills (JSONC Engine)\nAdd user-defined metrics by dropping declarative `.jsonc` definitions into `~/.paseo/xpufx-plugins/top/pills/`:\n- **Shell Command Execution**: Executes commands or scripts at configurable intervals.\n- **Threshold Matching**: Maps outputs or exit codes to visual statuses (`neutral`, `success`, `warning`, `danger`, `accent`, `info`).\n- **Interactive Modal Drilldown**: Clicking a custom pill can trigger an on-demand secondary command (for example, `docker ps -a` or `df -h`) and render terminal output directly inside the detail modal.\n- Built-in templates available in [`examples/pills/`](examples/pills/):\n  - `docker-containers.jsonc`: Active container tally and list\n  - `gpu-nvidia.jsonc`: GPU load and VRAM usage via `nvidia-smi`\n  - `disk-usage.jsonc`: Root filesystem utilization meter\n  - `battery.jsonc`: Battery percentage and AC charging state\n  - `git-dirty.jsonc`: Modified file count in working tree\n\n### 8. Native Modal Dashboard\nClicking the pill opens a native dashboard with:\n- **Pinned Header Navbar**: Fixed tabs for System Resources, Activity Timeline, Custom Pills, Settings, and About. Content smoothly scrolls beneath the navbar.\n- **Visual Gauges**: Responsive bars showing CPU and RAM distribution.\n- **Full Settings Suite**: Live toggles for every metric and pill, with persistent state managed by `PluginStorage`.\n\n## Installation\n\nInstall using the native Paseo monorepo subpath syntax:\n\n```bash\npaseo plugin add xpufx/paseo --path plugins/top\n```\n\nFor local development:\n\n```bash\ngit clone git@github.com:xpufx/paseo.git\ncd paseo\npaseo plugin add ./plugins/top\n```\n\n## Development\n\n```bash\n# Typecheck\nnpm run typecheck --workspace=plugins/top\n\n# Run test suite\nnpm test --workspace=plugins/top\n\n# Reload in a running Paseo daemon\npaseo plugin reload top\npaseo plugin logs top\n```\n\n## License\n\nMIT\n"}