Skip to content

REGISTRY_FORMAT.md

Latest commit

 

History

History
187 lines (148 loc) · 5.97 KB

REGISTRY_FORMAT.md

File metadata and controls

187 lines (148 loc) · 5.97 KB

Registry Format — Tmux Plugin Panel

This document describes the JSON schema for plugin registries used by tmuxpanel.

Overview

tmuxpanel ships with a built-in registry (registry.json) compiled into the binary. You can add external registries — local JSON files or remote URLs — to extend the available plugins and themes.

Registry JSON Schema

A registry file must be valid JSON with this top-level structure:

{
  "version": 2,
  "updated": "2025-01-15",
  "plugins": [
    { ... },
    { ... }
  ]
}

Top-Level Fields

Field Type Required Description
version integer Yes Schema version (current: 2)
updated string No ISO 8601 date of last update
plugins array Yes Array of plugin entries (see below)

Plugin Entry

Each entry in the plugins array:

{
  "repo": "tmux-plugins/tmux-sensible",
  "name": "Sensible",
  "description": "A set of sensible tmux defaults everyone can agree on",
  "category": "essential",
  "stars": 5500,
  "compat": ["tmux", "psmux"]
}
Field Type Required Description
repo string Yes GitHub repo path in owner/name format
name string Yes Human-readable plugin name
description string Yes Short description of what the plugin does
category string Yes One of the category values below
stars integer No GitHub star count (for sorting/display)
compat string[] Yes Compatibility: "tmux", "psmux", or both

Category Values

Value Label Description
essential Essential Must-have plugins (TPM, sensible, etc.)
theme Theme Color themes and visual styles
session Session Session save/restore/management
navigation Navigation Pane/window navigation helpers
statusbar Status Bar Status bar enhancements
clipboard Clipboard Copy/paste and yank integration
utility Utility Everything else

Compatibility Values

Value Description
tmux Compatible with tmux (Linux/macOS)
psmux Compatible with PSMux (Windows PowerShell mux)

A plugin can be compatible with both — use ["tmux", "psmux"].

External Registry Sources

Registry sources are configured in ~/.config/tmuxpanel/registry_sources.json:

{
  "sources": [
    {
      "name": "Built-in Registry",
      "url": "",
      "source_type": "embedded",
      "enabled": true
    },
    {
      "name": "My Custom Plugins",
      "url": "/home/user/.config/tmuxpanel/my-plugins.json",
      "source_type": "local",
      "enabled": true
    },
    {
      "name": "Community Registry",
      "url": "https://example.com/tmuxpanel-registry.json",
      "source_type": "remote",
      "enabled": true
    }
  ]
}

Source Types

Type Description
embedded Built into the binary (always present, cannot be removed)
local A JSON file on the local filesystem
remote A URL that returns registry JSON (fetched via HTTP)

Source Fields

Field Type Required Description
name string Yes Display name for the source
url string Yes* File path (local) or URL (remote). Empty for embedded.
source_type string Yes "embedded", "local", or "remote"
enabled boolean No Whether to load this source (default: true)

Example: Creating a Custom Registry

  1. Create a JSON file following the schema:
{
  "version": 2,
  "updated": "2025-01-15",
  "plugins": [
    {
      "repo": "myorg/my-tmux-plugin",
      "name": "My Plugin",
      "description": "Custom plugin for my team",
      "category": "utility",
      "stars": 0,
      "compat": ["tmux"]
    }
  ]
}
  1. Add it as a source in ~/.config/tmuxpanel/registry_sources.json:
{
  "sources": [
    {
      "name": "Built-in Registry",
      "url": "",
      "source_type": "embedded",
      "enabled": true
    },
    {
      "name": "Team Plugins",
      "url": "/path/to/team-registry.json",
      "source_type": "local",
      "enabled": true
    }
  ]
}
  1. Restart tmuxpanel — your plugins will appear in the Browse tab.

Validation

tmuxpanel validates registries on load. Common issues:

  • Missing version field
  • repo not in owner/name format
  • Missing compat array
  • Invalid JSON syntax

The built-in registry is always loaded first. External registries are merged — if a plugin repo already exists, the built-in version takes priority.

Plugin Sources

tmux Plugins

Most tmux plugins live under the tmux-plugins GitHub organization. The repo field uses tmux-plugins/plugin-name format.

PSMux Plugins

PSMux plugins and themes are maintained in the marlocarlo/psmux-plugins monorepo. Each subdirectory is a plugin, so the repo field uses psmux-plugins/plugin-name format.

Both types are supported in the same registry and can coexist.