CatGo

CatGo offers a VSCode extension for rendering crystal structures and molecular dynamics (MD) or geometry optimization trajectories directly in the editor to speed up typical materials science/computational chemistry workflows.

Scope — what's in the extension vs the desktop client

The extension embeds CatGo's real interactive viewer (the same Structure and Trajectory components as the app), so it does much more than display files:

In the extension (the full single-window viewer): view & animate · edit (move / add / delete atoms, bonds, lattice, selection, measurement, undo/redo, right-click menu) · the structure toolbar — builders, analysis panes, OPTIMADE / PubChem import · save & export (format-preserving input decks) · display/theme customization · remote-SSH file viewing. CatBot and compute/database features that need a backend activate once you configure an LLM provider and/or download the optional catgo-server sidecar.

Desktop client only — the surrounding workbench shell, which the extension does not load: the multi-pane tabbed workspace (tabs / split-view / pop-out windows), the standalone visual workflow DAG editor, and the HPC terminal & job manager.

For the full workbench use the CatGo desktop client (Windows / macOS / Linux) or the web app.

✨ Features

🔬 Structure Visualization

• Reads most codes, not just CIF/POSCAR — open the inputs and outputs of VASP, Quantum ESPRESSO, CP2K, ABACUS, ORCA, Gaussian, CASTEP, SIESTA, OpenMX and LAMMPS (see Supported File Formats)
• Crystals & molecules — periodic slabs, bulk and isolated molecules alike
• Cross-cell PBC bonds — bonds rendered correctly across periodic boundaries, with image atoms
• Symmetry — moyo-driven space group + Wyckoff positions
• Charge density — cube / VASP CHGCAR-family isosurfaces
• Interactive 3D Viewer — rotate, zoom-to-cursor, measure, ortho/perspective cameras

🎬 Trajectory Analysis

• MD / optimization / NEB / IRC — animate ASE .traj, VASP XDATCAR/OUTCAR/vasprun.xml, LAMMPS dumps, extXYZ, HDF5 and pymatgen JSON
• Timeline scrubbing — frame-by-frame navigation with energy / force / per-atom property overlays
• Per-frame bonds — connectivity recomputed each frame
• Frame export — pull any frame out as a structure file

🎨 Customization

• Color Schemes: Multiple built-in color schemes (Jmol, VESTA, Alloy, Pastel, etc.)
• Visualization Modes: Ball-and-stick, space-filling, wireframe representations
• Export Options: Save visualizations to PNG or export structure data to ASE XYZ and pymatgen JSON

🚀 Installation

Search for "CatGo" in the VS Code Extensions marketplace.

📋 Usage

Quick Start

1. Open a structure file in VS Code (.cif, .poscar, .xyz, .json, etc.)
2. Right-click in the explorer or editor
3. Select "Render with CatGo" from the context menu
4. Or use the keyboard shortcut: Ctrl+Shift+V (Windows/Linux) / Cmd+Shift+V (Mac)

Supported File Formats

Anything CatGo can parse renders here — far beyond CIF/POSCAR. Use right-click → Render (or Ctrl/Cmd+Shift+V) on any of the following.

Structures, by code

Trajectories

• ASE .traj (binary)
• VASP XDATCAR, OUTCAR, vasprun.xml (multi-step)
• LAMMPS dump / .lammpstrj
• extXYZ multi-frame
• HDF5 / H5 — torch-sim & VASP vaspout.h5
• pymatgen JSON frames
• .gz-compressed variants of the above

Large trajectories use an OVITO-style file-backed index: CatGo scans frame boundaries once, keeps topology static where possible, and reads only the requested frame. Files above 1 MiB (or compressed files above 256 KiB) take this path in the extension and in the shared desktop/Web application.

Custom Editor Integration

CatGo automatically registers as a custom editor for trajectory files such as .traj, .h5, .hdf5, .xyz.gz, etc.

Remote SSH Support

CatGo supports VSCode/Cursor remote SSH connections. Connect to your server via Remote SSH extension, and CatGo should work just like it does locally.

• ✅ Remote file access: Visualize structures and trajectories on remote servers (HPC clusters, cloud instances, etc.)
• ✅ No manual file transfer: Files are read directly from the remote filesystem
• ✅ File watching: Changes to remote files are automatically detected and reloaded
• ✅ Large trajectory streaming: Streamable trajectory formats are indexed and read frame-by-frame on the remote extension host; they are not copied wholesale into the webview.
• ⚠️ Other files: The 1 GB safety limit still applies to non-streamable files.

⚙️ Configuration & Customization

CatGo provides extensive customization options through VSCode settings. Access these via:

• Settings UI: File → Preferences → Settings → Search for "CatGo"
• JSON Settings: Ctrl+Shift+P → "Preferences: Open Settings (JSON)"

Common Configuration Scenarios

🎨 Visual Appearance

{
  "catgo.color_scheme": "Jmol",
  "catgo.background_color": "#ffffff",
  "catgo.background_opacity": 0.8,
  "catgo.structure.show_image_atoms": true,
  "catgo.structure.atom_radius": 1.2,
  "catgo.structure.bond_thickness": 0.8
}

🎬 Trajectory Playback

{
  "catgo.trajectory.auto_play": true,
  "catgo.trajectory.fps": 10,
  "catgo.trajectory.display_mode": "structure",
  "catgo.trajectory.show_controls": true
}

📊 Plot Customization

{
  "catgo.scatter.point_size": 5,
  "catgo.scatter.line_width": 3,
  "catgo.plot.grid_lines": true,
  "catgo.scatter.show_legend": true
}

🔧 Performance Optimization

{
  "catgo.trajectory.chunk_size": 500,
  "catgo.trajectory.bin_file_threshold": 10485760,
  "catgo.structure.sphere_segments": 16
}

Setting Categories

Pro Tips

• Reset to defaults: Remove custom settings from your JSON config
• Project-specific settings: Use workspace settings (.vscode/settings.json) for per-project customization
• Theme integration: CatGo automatically adapts to your VSCode color theme
• Performance: Reduce sphere_segments for better performance with large structures

⌨️ Keyboard Shortcuts

• Ctrl+Shift+V / Cmd+Shift+V → Render structure/trajectory with CatGo

🐛 Bug Reporting

If you encounter any issues with CatGo, you can use the built-in bug reporting command to collect debug information:

1. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
2. Run "Report CatGo Bug"
3. The command will open a new document with detailed debug information including:
   • Your OS and version
   • VSCode/Cursor version
   • CatGo version
   • Whether you're in a remote session
   • Files currently being rendered
   • System resources and memory usage
   • Extension configuration
4. Copy the information and include it when creating a GitHub issue

📄 License

This extension is distributed under AGPL-3.0-or-later. If CatGo contributes to your work, please include the acknowledgement and preferred citation below. This request is not an additional condition of the AGPL license.

This work used CatGo (https://app.catgo-ucsd.org).

Please cite CatGo using the preferred ChemRxiv DOI 10.26434/chemrxiv.15002984/v1. See the repository's CITATION.cff for the canonical citation metadata.

🔗 Related Projects

• Upstream CatGo / MatterViz: github.com/janosh/catgo
• pymatviz: Jupyter/Marimo extension for Python notebooks. Read about widgets in pymatviz readme for details.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

🛠️ Development

git clone https://github.com/Hello-QM/catgo-LRG
cd catgo/extensions/vscode
pnpm install
pnpm build
vsce package