xtop_
/

xtop-cli / documentation

Documentation

All the xtop-cli ecosystem documentation, in one place. These pages are a faithful mirror of the README.md and docs/ files of every repository — nothing here has been rewritten: if a repo changes, its documentation changes. A translated Spanish mirror lives at /docs/es.

The ecosystem is split into seven repositories with a single dependency rule: every consumer depends only on the contract crates in api — never on the kernel — so each repo compiles standalone.

Repo Role Content
xtop kernel the app: single-crate binary; consumes every other repo
api contracts xtop-plugin-api · xtop-widget-api · xtop-effect-api · xtop-extension-api
widgets renderers widget packs over xtop-widget-api (default pack + blocks)
layouts arrangement xtop-layout: layout model, JSONC loader, modes, presets
plugins functionality plugin implementations (first member: xtop-plugin-samurai)
extensions kernel hooks server-style extensions (first member: xtop-extension-mcp)
effects animation frame effects (first member: xtop-effect-fade)

Start here

If you are new to the code, the natural order is:

  1. What it is → features and the kernel README
  2. Install it → installation — Linux, Windows, macOS and building from source
  3. Use it → usage — keybindings, modules, responsive layouts
  4. Configure it → configuration and customization (JSONC themes and layouts)
  5. Colors → colors — the 12 palettes
  6. Develop → contracts in api, packs in widgets authoring, plugins and MCP in plugins and extensions MCP protocol

Note: links between files are resolved automatically to the equivalent local route when the target is mirrored here; everything else points to the real blob on GitHub.

Mirrors

Repository Files
xtop-cli/api README.md, docs/*.md
xtop-cli/effects README.md, docs/*.md
xtop-cli/extensions README.md, docs/*.md, extensions/xtop-extension-mcp/README.md
xtop-cli/layouts README.md, docs/*.md, layouts/custom/README.md
xtop-cli/plugins README.md, docs/*.md, plugins/xtop-plugin-samurai/README.md
xtop-cli/widgets README.md, docs/*.md, custom/README.md
xtop-cli/xtop README.md, docs/*.md, ROADMAP.md, CHANGELOG.md, CONTRIBUTING.md

Xtop

The application itself: a cross-platform TUI system monitor written in Rust. Single-crate kernel with ratatui rendering, sysinfo providers and the command surface (config, themes, layouts, plugins, widgets, MCP).

XtopFeaturesInstallationUsage

github.com/xtop-cli/xtop →

13 docs

api

Pure contract crates: xtop-plugin-api, xtop-widget-api, xtop-effect-api and xtop-extension-api. The shared data model (SystemSnapshot, AlertThresholds) lives here; every other repo depends only on this one.

apiArchitectureData ModelPlugin Contract

github.com/xtop-cli/api →

8 docs

widgets

Widget packs of renderers against xtop-widget-api: the default pack (11 widgets) plus the blocks pack — one crate per widget, plus the shared xtop-widget-core engine.

widgetsWidgetsAuthoringCustom

github.com/xtop-cli/widgets →

4 docs

layouts

The xtop-layout crate: data-driven layout model, JSONC loader, layout modes and terminal-size degradation. Ships 7 mode layouts + 3 detail presets and hosts the community layouts folder.

layoutsLayout SchemaAuthoringDecisions

github.com/xtop-cli/layouts →

5 docs

plugins

Plugin implementations against xtop-plugin-api. First member: xtop-plugin-samurai — an AI-aware plugin exposing 12 JSON actions and 10 heuristic threat-detection rules.

pluginsXtop Plugin SamuraiArchitectureRules

github.com/xtop-cli/plugins →

4 docs

extensions

Server-style extensions against xtop-extension-api. First member: xtop-extension-mcp — a Model Context Protocol server over stdio that exposes xtop and its hosted plugins as MCP tools.

extensionsXtop Extension MCPArchitectureMCP Protocol

github.com/xtop-cli/extensions →

4 docs

effects

Frame effects against xtop-effect-api. First member: xtop-effect-fade — fades the rendered frame in from black over 500 ms, deterministic and zero-config.

effectsEffectsWrite Effect

github.com/xtop-cli/effects →

3 docs