CatGo Structure Editor for Codex

中文说明

Open and edit molecular and crystal structures in the Codex desktop app's right-hand panel. CatGo's Svelte/Three.js viewer, scalar WASM and MCP App assets are included. Installation does not require a CatGo checkout, a running CatGo service, Node.js, npm, or a GitHub account.

Install

Requirements: a Codex desktop app supporting MCP Apps and file entrypoints, a recent Codex CLI with codex plugin marketplace, and Python 3.10 or later available as python3 on the app's PATH. Linux is the locally tested platform; macOS and Windows native host rendering have not been tested.

codex plugin marketplace add Hello-QM/catgo-codex-plugin
codex plugin add catgo-editor@catgo

Refresh plugin connections or start a new chat after installation. Open a .cif, .xyz, .extxyz, .poscar, or .vasp file in the right-hand panel. For an extensionless POSCAR/CONTCAR, open the CatGo editor and use Open. Sample structures are in examples/.

If an earlier installation failed with missing plugin.json, refresh the cached marketplace with codex plugin marketplace upgrade catgo, then run the install command again. Version 0.2.9 includes both portable and legacy Codex manifests.

For Windows, check that python3 --version runs from the environment that launches Codex before installing. The shipped launcher uses that command; python or py alone is insufficient. See troubleshooting.

Claude Code

The same package also installs as a Claude Code plugin. Inside Claude Code:

/plugin marketplace add Hello-QM/catgo-codex-plugin
/plugin install catgo-editor@catgo

Or from a shell: claude plugin marketplace add Hello-QM/catgo-codex-plugin and claude plugin install catgo-editor@catgo. Restart the session afterwards.

Ask Claude to show a structure ("view /path/to/CONTCAR"). The plugin's view_structure tool starts a loopback page that runs the same prebuilt editor, and Claude opens it in the Claude desktop app's right-hand Browser pane. Later files load into the open page. In a terminal-only session, open the link Claude gives you in any browser. Extensionless POSCAR/CONTCAR* files open directly.

• Save writes back to the file with a version check; a file changed on disk reloads, or reports a conflict if you have unsaved edits.
• Export and every download open the system Save dialog so you choose where the file goes. Where the browser offers no such dialog, the page asks for a path (starting in the open file's folder) and confirms before replacing a file.
• The toolbar's Import / Export (↑↓) → More formats… opens CatGo's export pane: structure formats, figures and QE/VASP/LAMMPS/CP2K/Gaussian/GROMACS/ORCA/ABACUS/AMBER/SPARK inputs, saved the same way.
• Send selection, then ask Claude about the selection: the get_viewer_selection tool returns those atoms' indices, elements and Cartesian coordinates.
• You can also type an absolute path into the page's top bar.

The page server listens on 127.0.0.1:47821 (CATGO_VIEWER_PORT changes it) and exits after 30 minutes without a connected page. Its API needs a random token kept in ~/.cache/catgo-viewer/ (user-only permissions) and reads or writes only CIF, XYZ, extXYZ, POSCAR/CONTCAR and .vasp files.

Use

Version 0.2.15 adds Claude Code support and CatGo's own export pane under Import / Export → More formats…; native 0.2.15 acceptance in Codex is pending. Version 0.2.14 fixes host-mediated downloads and the Import / Export toolbar, and provides a reversible WebGL performance toggle where WebGPU is unavailable. See the file-action fixes and verification scope. Native 0.2.14 activation/acceptance is pending; the native results below apply to their stated earlier versions.

Version 0.2.12 fixes hidden-tab initialization warnings and own-save resource updates that reset the active editor. See the lifecycle fix and verification. Native Linux acceptance on 2026-10-29 verified the loaded 0.2.12 program, three Save cycles and Undo/Redo across those saves without reopening the file; see the native acceptance report and limits.

• Rotate and inspect atoms, bonds and the unit cell; select atoms and edit coordinates.
• In Controls → Bonds, use Cell-edge stub bonds and Stub Length for periodic boundary bonds. Native Codex Linux checks of 0.2.11 confirmed visible changes at 1.0 and 0.5; see the screenshots and reproduction steps.
• Use undo/redo. Save writes a host-opened writable file with a version check; conflicts keep pending edits. Export saves an edited copy. Native Codex Linux acceptance of 0.2.11 also verified coordinate editing, Undo/Redo before Save, disk persistence and reopening on a fresh disposable 157-atom copy; see the acceptance report.
• Import through Open or drag/drop, when allowed by the host. Imported copies use Export; they do not overwrite the previously opened host file.
• Import / Export opens file actions with POSCAR, Extended XYZ and CIF export; More formats… there opens CatGo's export pane for other formats, calculation inputs and images. Use POSCAR or Extended XYZ to retain fixed/free constraints; CIF retains geometry and cell. The performance gauge uses a drawing-resolution toggle when WebGPU is unavailable, and restores the previous resolution when switched off.
• Open Build Tools → Slab to cut by Miller indices, choose thickness/layers, termination, in-plane supercell, conventional cell and vacuum. Geometry is generated locally; this is not a relaxation or an energy calculation.
• Send selection explicitly adds the selected atoms to model context.

The MCP server serves its packaged UI/resources. File reads and writes go through the Codex host bridge; the server does not resolve host URIs to filesystem paths. Rendering and slab construction run in the embedded editor. The plugin has no standalone telemetry service. Files and explicitly sent selection context remain subject to the host application's own data handling.

Research use and citation

If you use this plugin for research, including molecular/crystal structure editing or slab construction, please cite the CatGo paper:

Liu, G.; Ma, X.; Zhang, L.; Pascasio, J.; Yang, J.; Chen, Y.; Li, W.-L. CatGo: Bridging CLI coding agents with interactive structure and workflow management for computational chemistry. Digital Discovery 2026, 5(9), 3825–3849. DOI: 10.1039/D6DD00273K.

Copy the BibTeX below, download CITATION.bib, or use GitHub's Cite this repository entry. CITATION.cff sets the paper as the preferred citation.

@article{Liu2026CatGo,
  author  = {Liu, Guangsheng and Ma, Xiao and Zhang, Leshen and
             Pascasio, Jenedith and Yang, Jonathan and Chen, Yuxiang and
             Li, Wan-Lu},
  title   = {{CatGo}: Bridging {CLI} coding agents with interactive structure and workflow management for computational chemistry},
  journal = {Digital Discovery},
  year    = {2026},
  volume  = {5},
  number  = {9},
  pages   = {3825--3849},
  doi     = {10.1039/D6DD00273K},
  url     = {https://doi.org/10.1039/D6DD00273K}
}

Update and remove

codex plugin marketplace upgrade catgo
codex plugin add catgo-editor@catgo

Refresh connections before reopening a file. To uninstall:

codex plugin remove catgo-editor@catgo
codex plugin marketplace remove catgo

This is an independently published GitHub marketplace source. It has not been submitted to or approved for OpenAI's public Plugin Directory. Users add this source explicitly. No API key or CatGo account is required.

Development and verification

The repo includes the plugin source, a standalone bundler and the CatGo viewer and scalar WASM corresponding source in vendor/catgo/. No private-repository access is needed to build. See development, verification, and changelog.

CatGo's core code is AGPL-3.0-or-later. Retained third-party components have their own licenses; see LICENSE, NOTICE and third-party notices.