PyMOL: Molecular Visualization via claudemol

Summary

This skill enables Claude Code to control PyMOL molecular visualization software through the claudemol socket interface. It supports:

Setup: Cross-platform installation of claudemol and PyMOL
Visualization: Rendering proteins, small molecules, and complexes
Publication figures: Ray-traced high-resolution images
Interactive control: Send PyMOL commands programmatically

Applicable Scenarios

Task Category	Examples
Setup	Install PyMOL, configure claudemol, verify connection
Structure Loading	Load PDB files, fetch from RCSB, open local structures
Representations	Cartoon, surface, sticks, spheres, ribbons, lines
Coloring	Color by chain, spectrum, B-factor, custom colors
Selections	Select residues, chains, ligands, binding sites
Camera	Orient view, zoom, rotate, save viewpoints
Ray Tracing	High-quality renders, publication figures
Export	Save images (PNG), sessions (PSE), movies

Setup Instructions

Quick Setup (All Platforms)

Run the automated setup script:

python /path/to/skills/pymol/scripts/setup_pymol.py

Manual Setup

1. Install claudemol

pip install claudemol

2. Install PyMOL

macOS (Recommended):

brew install pymol

Windows/Linux (Headless):

pip install pymol-open-source

Windows (Licensed PyMOL): Connect to existing PyMOL installation - see references/troubleshooting.md

3. Configure PyMOL

claudemol setup

This adds the socket plugin to PyMOL's startup.

4. Launch and Verify

Start PyMOL normally

Check that port 9880 is listening:

lsof -i :9880  # macOS/Linux
netstat -an | findstr 9880  # Windows

Socket Communication

claudemol communicates with PyMOL via a TCP socket on port 9880.

Basic Pattern

import socket
import json

def send_pymol_command(code: str, host: str = 'localhost', port: int = 9880) -> dict:
    """Send a command to PyMOL via claudemol socket."""
    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
    sock.settimeout(30)
    try:
        sock.connect((host, port))
        message = json.dumps({"code": code})
        sock.sendall(message.encode('utf-8'))
        response = sock.recv(65536)
        return json.loads(response.decode('utf-8'))
    finally:
        sock.close()

Multi-Command Example

commands = """
cmd.load('1ubq.pdb')
cmd.show('cartoon')
cmd.color('cyan', 'all')
cmd.orient()
"""
result = send_pymol_command(commands)

Quick Reference

Loading Structures

# From local file
cmd.load('/path/to/structure.pdb')
cmd.load('/path/to/structure.cif')

# From RCSB PDB
cmd.fetch('1ubq')
cmd.fetch('6lu7', type='cif')

Representations

# Show representations
cmd.show('cartoon', 'all')
cmd.show('surface', 'chain A')
cmd.show('sticks', 'resn LIG')
cmd.show('spheres', 'name CA')

# Hide representations
cmd.hide('lines', 'all')
cmd.hide('everything', 'solvent')

Coloring

# Color by chain (automatic colors)
cmd.util.cbc()

# Spectrum coloring (rainbow N to C)
cmd.spectrum('count', 'rainbow', 'all')

# Specific colors
cmd.color('red', 'chain A')
cmd.color('blue', 'resn LIG')
cmd.color('green', 'resi 50-100')

# B-factor coloring
cmd.spectrum('b', 'blue_white_red', 'all')

Selections

# Create named selections
cmd.select('binding_site', 'byres resn LIG around 5')
cmd.select('active_site', 'resi 145+41+166 and chain A')
cmd.select('interface', 'chain A within 4 of chain B')

# Selection algebra
cmd.select('no_water', 'all and not solvent')

View and Camera

# Orient and zoom
cmd.orient()
cmd.zoom('all')
cmd.zoom('chain A', buffer=5)
cmd.center('resn LIG')

# Set specific view
cmd.set_view([...])  # 18-element matrix

# Store and recall views
cmd.view('view1', 'store')
cmd.view('view1', 'recall')

Ray Tracing and Export

# Basic ray trace
cmd.ray(1920, 1080)
cmd.png('/path/to/output.png')

# Publication quality
cmd.set('ray_trace_mode', 1)
cmd.set('ray_shadows', 'on')
cmd.set('antialias', 2)
cmd.ray(2400, 2400)
cmd.png('/path/to/figure.png', dpi=300)

Visualization Workflows

See references/visualization.md for complete workflows:

Basic protein visualization
Cartoon with chain coloring
Surface with transparency
Ligand binding site
Domain highlighting
Publication-quality figures

Command Reference

See references/commands.md for complete command documentation:

All cmd.* functions
Selection syntax
Setting parameters
Color palettes

Troubleshooting

See references/troubleshooting.md for platform-specific issues:

macOS GLUT errors
Windows headless mode
Connection refused errors
Display problems

Common Issues

Issue	Resolution
Connection refused	Ensure PyMOL is running with claudemol plugin loaded
Port 9880 in use	Kill other processes or change port
No GUI (Windows pip)	Use headless mode or licensed PyMOL
GLUT missing (macOS)	Install via Homebrew instead of pip
Slow ray tracing	Reduce resolution or simplify scene

External Resources

PyMOL Documentation: https://pymol.org/dokuwiki/
PyMOL Wiki: https://pymolwiki.org/
claudemol GitHub: https://github.com/colorifix/claudemol
Open-Source PyMOL: https://github.com/schrodinger/pymol-open-source