pymol

name	pymol
description	Control PyMOL molecular visualization through Claude Code. Use when asked to "visualize protein", "render structure", "show cartoon", "color by chain", "ray trace", "set up pymol", "install pymol", or work with molecular graphics. Handles setup, visualization commands, and publication-quality figure generation.

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

1. Start PyMOL normally
2. 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