Skip to content

CLAUDE.md

Latest commit

 

History

History
144 lines (97 loc) · 4.83 KB

CLAUDE.md

File metadata and controls

144 lines (97 loc) · 4.83 KB
Raw

CLAUDE.md — Glances Maintainer Context

Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.

1. Think Before Coding

Don't assume. Don't hide confusion. Surface tradeoffs.

Before implementing:

  • State your assumptions explicitly. If uncertain, ask.
  • If multiple interpretations exist, present them - don't pick silently.
  • If a simpler approach exists, say so. Push back when warranted.
  • If something is unclear, stop. Name what's confusing. Ask.

2. Simplicity First

Minimum code that solves the problem. Nothing speculative.

  • No features beyond what was asked.
  • No abstractions for single-use code.
  • No "flexibility" or "configurability" that wasn't requested.
  • No error handling for impossible scenarios.
  • If you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

3. Surgical Changes

Touch only what you must. Clean up only your own mess.

When editing existing code:

  • Don't "improve" adjacent code, comments, or formatting.
  • Don't refactor things that aren't broken.
  • Match existing style, even if you'd do it differently.
  • If you notice unrelated dead code, mention it - don't delete it.

When your changes create orphans:

  • Remove imports/variables/functions that YOUR changes made unused.
  • Don't remove pre-existing dead code unless asked.

The test: Every changed line should trace directly to the user's request.

4. Goal-Driven Execution

Define success criteria. Loop until verified.

Transform tasks into verifiable goals:

  • "Add validation" → "Write tests for invalid inputs, then make them pass"
  • "Fix the bug" → "Write a test that reproduces it, then make it pass"
  • "Refactor X" → "Ensure tests pass before and after"

For multi-step tasks, state a brief plan:

1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]

Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

Additionnal context

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

Code principles

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.

Security

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

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

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.

These guidelines are working if: fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.