Real-time LLM activity monitor (Hermes, OpenCode, OpenWebUI) and AMD Radeon GPU VRAM tracker in the GNOME Top Bar.
TokenWatcher TopBar is an intelligent, high-performance GNOME Shell extension and companion daemon designed for developers and AI engineers running local and hybrid LLM workflows. It delivers unified, real-time observability over your AI agent activities, streaming token consumption, generation throughput (
TokenWatcher is compatible with GNOME Shell 45 through 50+ on both Wayland and X11, paired with an ultra-lightweight Python background daemon. It provides real-time monitoring directly in your top bar:
- The active LLM model with cleaned aliases (Gemini 3.7 Flash, Qwen3-Coder-30B, Gemma-4-12B, etc.).
- The cumulative token volume formatted in standard millions
#,##M(e.g.,2.37M). - The live generation speed (
X.X t/s). - The GPU VRAM usage on AMD APUs (Strix Halo / Radeon 8060S / AMD dGPUs).
- The active execution source (Hermes, OpenCode, OpenWebUI).
┌────────────────────────────────────────────────────────────────────────┐
│ [Terminal] Qwen3-Coder-30B | 0.05M | 28.4 t/s | VRAM 14.4 GB | OpenCode│
└────────────────────────────────────────────────────────────────────────┘
The background daemon continuously monitors local sources with zero overhead:
-
Hermes Agent: Real-time SQLite tracking of
~/.hermes/state.db(sessions, models, prompt/completion tokens, tool calls). -
OpenCode: Real-time SQLite monitoring of
~/.local/share/opencode/opencode.db(sessions, messages, real-time delta calculation$\Delta t < 3\text{s}$ , and tokens/s). -
Open WebUI: SQLite monitoring of
webui.dband local ports. - Lemonade Server: Monitoring of the local REST API (port 13305) and the model loaded in VRAM.
Dynamic Priority: As soon as OpenCode or a specialized agent begins generating code, the top bar indicator instantly switches to the active task, then smoothly returns to the primary orchestrator once the job is finished.
- Direct extraction via
amdgpu_topand/sys/class/drm/card*/device/mem_info_vram_*. - Accurate detection of shared / dedicated memory allocation for the AMD Strix Halo APU (Radeon 8060S).
Clicking the indicator opens a detailed popover menu displaying:
- Current session or project context and title.
- Full model name and clean aliases.
- Token breakdown (
Prompt invsCompletion out) and total in millions (#,##M). - Instant generation speed (
$t/s$ ). - GPU and VRAM utilization.
- Direct shortcuts to local Web UIs (Open WebUI: port 8080, Lemonade: port 13305).
TokenWatcher-TopBar/
├── extension/
│ ├── extension.js # GNOME 45-50 extension code (GObject ES6)
│ ├── metadata.json # Extension metadata & GNOME Shell compatibility
│ └── stylesheet.css # Visual styles & popover design
├── daemon/
│ └── tokenwatcher-daemon # Multi-source Python daemon (IPC via /tmp/tokenwatcher_state.json)
├── systemd/
│ └── tokenwatcher.service # Systemd user service unit
├── install.sh # Automated 1-click installation script
├── uninstall.sh # Clean uninstallation script
├── readme-setup.md # Dedicated step-by-step setup guide
├── LICENSE # GNU General Public License v3.0 (GPL-3.0)
├── .gitignore
└── README.md
Clone the repository and run the installation script:
git clone https://github.com/ThomasK2020/tokenwatcher-topbar.git
cd tokenwatcher-topbar
./install.shNote for Wayland / GNOME Shell: Under Wayland, if the extension was just installed or updated, please log out and log back in to your GNOME user session (Log Out / Log In) so the Shell loads the module.
systemctl --user status tokenwatcher.servicejournalctl --user -u tokenwatcher.service -fcat /tmp/tokenwatcher_state.json | jq .gnome-extensions info tokenwatcher@thomas.local- Thomas (@ThomasK2020)
Distributed under the GNU General Public License v3.0 (GPL-3.0). See LICENSE for more information.