CLAUDE.md — Glances Maintainer Context

Auto-loaded by Claude Code at the start of every session. Glances-specific context. Global principles (role, refactoring strategy, contribution tone, communication, output formats) are in ~/.claude/CLAUDE.md.

Tech stack

Layer	Technology
Backend	Python, psutil, FastAPI (REST API), curses (TUI)
Frontend	Vue.js, Bootstrap 5, SCSS
Export plugins	InfluxDB, MongoDB, MQTT, DuckDB, and others
Infrastructure	GitHub Actions, Helm/Kubernetes, Snap (snapcraft)
LLM abstraction	LiteLLM (multi-provider)
GPU/NPU monitoring	pynvml, sysfs/debugfs

Reference docs (use `@` to load on demand)

Commands & setup: @.claude/docs/commands.md
Architecture: @.claude/docs/architecture.md

Code principles (Glances-specific)

Exception handling for Snap confinement

Wrap the open() call inside try/except, not just the read(). Snap's strict confinement blocks host file access at the open stage, not the read stage.

Kubernetes workloads

Use a DaemonSet (one pod per node) for system-level monitoring. Prefer SYS_PTRACE over privileged: true.

Security (Glances-specific)

Glances runs unauthenticated by default — this is intentional and documented. Most users deploy on private networks for personal use. See global CLAUDE.md for the general OSS security philosophy (4 rules).

Sensitive endpoints

/api/4/config and /api/4/args — never expose credentials in plain text (InfluxDB passwords, MongoDB tokens, MQTT passphrases, SSL key paths, etc.) for unauthenticated access. Use the conditional as_dict_secure() method, applied when self.args.password is False.
CORS: allow_origins=["*"] + allow_credentials=True is invalid per the CORS spec and reflected by Starlette. Default: allow_credentials=False.
DNS rebinding: TrustedHostMiddleware via webui_allowed_hosts (optional). The MCP endpoint is already protected via mcp_allowed_hosts + TransportSecuritySettings in glances/outputs/glances_mcp.py.

Contribution management (Glances-specific)

Before merging a PR

The code is actively used (no dead code)
Existing tests pass
New behaviour is covered by tests
New configuration keys are documented
Breaking changes are identified and documented
The PR targets the correct branch
Code should be formated and linted (make lint && make format)

Glances-specific output formats

Deliverable	Format
Changelog entry	`.rst` file following the `NEWS.rst` format
Helm Chart	`.tgz` archive or structured directory

Safe refactoring — applied example

Plugin dependency DAG — keep the hardcoded dict as fallback, add class-attribute discovery, deprecate the dict over two releases.

UI / TUI

Web UI

Stack: Vue.js + Bootstrap 5 + SCSS.

Design principles:

Strict typographic consistency across all plugins (size, weight, opacity, letter-spacing).
Pixel-perfect sparkline alignment (CSS grid, fixed row heights).
Footer = vertical alert list (up to 10 entries), not a single horizontal row.
No gauges — prefer sparklines with an inline current value.

TUI (curses)

256-colour system with automatic fallback for limited terminals.
Lightweight hierarchical separators for information density.

CI/CD — GitHub Actions

In build_docker.yml, the trigger condition combines branch exclusion and event type — a dynamic matrix with zero entries causes a silent failure without this guard:

if: >
  github.event_name != 'pull_request' &&
  (github.ref == 'refs/heads/develop' || startsWith(github.ref, 'refs/tags/'))

The master branch does not trigger a Docker build (empty matrix = silent failure without this condition).

3.8 KiB Raw Permalink Blame History