Plugin System Overview

tokentop is built on a plugin architecture with four distinct plugin types. Everything from provider integrations to color themes is a plugin, making the system highly extensible.

Plugin types

Type	Purpose	Examples
Provider	Fetch usage data from AI model APIs	Anthropic, OpenAI, Google
Agent	Parse coding agent sessions	Claude Code, Cursor, OpenCode
Theme	Visual color schemes for the TUI	Tokyo Night, Dracula, Nord
Notification	Alert delivery mechanisms	Terminal bell, visual flash

Plugin loading order

Plugins are loaded from three sources, in order:

1. Built-in plugins — Shipped with tokentop in the core package
2. Local plugins — Discovered from ~/.config/tokentop/plugins/ and paths specified via --plugin flag or config.plugins.local
3. npm plugins — Packages listed in config.plugins.npm

Plugins listed in config.plugins.disabled are removed after loading.

Plugin discovery

tokentop discovers local plugins from several sources:

• Default directory: ~/.config/tokentop/plugins/ (files and directories)
• CLI flag: ttop --plugin <path> loads a plugin for that run (repeatable)
• Config file: plugins.local array in ~/.config/tokentop/config.json

See Local Development for a detailed guide on all three methods, entry point resolution, and a recommended development workflow.

Permission sandboxing

All plugins must declare their required permissions:

permissions: {
  network?: { enabled: boolean; allowedDomains?: string[] };
  filesystem?: { read?: boolean; write?: boolean; paths?: string[] };
  env?: { read?: boolean; vars?: string[] };
  system?: { notifications?: boolean; clipboard?: boolean };
}

tokentop enforces these permissions at runtime, preventing plugins from accessing resources they haven’t declared.

npm naming conventions

Tier	Pattern	Example
Official	@tokentop/{type}-<name>	@tokentop/agent-opencode
Community	tokentop-{type}-<name>	tokentop-provider-replicate
Scoped	@scope/tokentop-{type}-<name>	@myname/tokentop-theme-catppuccin

The @tokentop/* scope is reserved for official plugins.

Getting started

• Provider Plugins — Build a provider integration
• Agent Plugins — Build an agent integration
• Theme Plugins — Create a custom theme
• Notification Plugins — Create a notification hook
• Local Development — Develop and test plugins locally
• Publishing — Publish your plugin to npm