CatGO Plugin Hub

Plugin catalog for CatGO — a materials science visualization toolkit. Browse, install, and share analysis tools, calculators, file readers, and workflow nodes.

Available Plugins

Plugin	Category	Description	Dependencies
Bond Length Histogram	General	Compute bond length distribution from a crystal structure	numpy, pymatgen
CP2K DOS Reader	Reader	Read projected density of states from CP2K .pdos files	numpy
LAMMPS NVT	Workflow Node	LAMMPS NVT molecular dynamics node for workflow graphs	--
Lennard-Jones Calculator	Calculator	ASE Lennard-Jones potential for noble gas systems	ase

Installing Plugins

From the app

Open the Plugin Hub panel (puzzle icon in the toolbar) and click Install on any plugin.

From CatBot

Ask the AI assistant:

"Search the plugin hub for bond analysis tools" "Install the bond histogram plugin"

Setup (private repo access)

Since this repo is private, set a GitHub token before starting the backend:

export CATGO_HUB_TOKEN=$(gh auth token)
pnpm desktop:serve

Writing Plugins

Every plugin is a Python file with two things: a TOOL dict describing the plugin, and an execute(context) function that runs it.

TOOL = {
    "name": "my_plugin",
    "description": "What it does",
    "category": "general",          # general | calculator | reader | optimizer | workflow_node
    "input_schema": {
        "type": "object",
        "properties": {
            "param_name": {"type": "number", "default": 1.0, "description": "A parameter"}
        }
    },
    "output_type": "bar_plot",      # bar_plot | scatter_plot | table | text | structure
}

async def execute(context):
    structure = context["structure"]  # current crystal structure from the viewer
    params = context.get("params", {})

    # ... your analysis logic ...

    return {
        "series": [{"label": "Result", "values": [1, 2, 3]}],
        "x_axis": {"label": "X"},
        "y_axis": {"label": "Y"},
    }

Allowed imports

math, numpy, scipy, pymatgen, ase, json, re, itertools, collections, functools

Blocked imports (security)

os, sys, subprocess, pathlib, socket, http, and similar system-access modules

CatBot can write plugins too

Ask CatBot to create one:

"Create a plugin that computes the radial distribution function"

It will write the code, test it in a sandbox, and save it to your local tools.

Publishing a Plugin

1. Write your plugin and test it locally (via CatBot or the REST API)
2. Run the publish endpoint to get the index entry:

   curl -X POST http://localhost:8000/api/hub/publish/my_plugin

3. Fork this repo
4. Add your plugin folder under plugins/your-plugin/ with tool.py and catgo-tool.json
5. Add the generated entry to index.json (or run python scripts/generate_hub_index.py plugins/ -o index.json)
6. Submit a pull request

Repo Structure

index.json                        # Auto-generated plugin registry
plugins/
  bond-histogram/
    tool.py                       # Plugin code (TOOL dict + execute function)
    catgo-tool.json               # Manifest (name, version, author, trust)
  cp2k-dos-reader/
    ...
scripts/
  generate_hub_index.py           # Regenerates index.json from plugin folders

Regenerating the Index

python scripts/generate_hub_index.py plugins/ -o index.json

This reads each plugin's tool.py and catgo-tool.json, computes SHA-256 hashes, and builds the registry manifest.