# claudemol: Control PyMOL with Claude Code

Control PyMOL through natural language using Claude Code. This integration enables conversational structural biology, molecular visualization, and analysis.

## Features

- **Natural language control**: Tell Claude what you want to visualize and it executes PyMOL commands
- **Direct socket communication**: Claude Code talks directly to PyMOL (no intermediary server)
- **Full PyMOL access**: Manipulate representations, colors, views, perform measurements, alignments, and more
- **Skill-based workflows**: Built-in skills for common tasks like binding site visualization and publication figures

## Architecture

```
Claude Code → TCP Socket (port 9880) → PyMOL Plugin → cmd.* execution
```

## Quick Start

### Prerequisites

- PyMOL installed on your system
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI installed
- Python 3.10+

### Installation

```bash
pip install claudemol
claudemol setup
```

This installs the package and configures PyMOL to auto-load the socket plugin.

### Start Using It

Open Claude Code and say:

> "Open PyMOL and load structure 1UBQ"

Claude will launch PyMOL (with the socket listener active) and load the structure.

## Usage

### Starting a Session

Simply ask Claude to open PyMOL or load a structure:

- "Open PyMOL"
- "Load PDB 4HHB and show as cartoon"
- "Fetch 1UBQ from the PDB"

Claude will launch PyMOL if it's not already running.

### Example Commands

- "Color the protein by secondary structure"
- "Show the binding site residues within 5Å of the ligand as sticks"
- "Align these two structures and calculate RMSD"
- "Create a publication-quality figure with ray tracing"
- "Make a 360° rotation movie"

### PyMOL Console Commands

Check or control the socket listener from PyMOL's command line:

```
claude_status   # Check if listener is running
claude_stop     # Stop the listener
claude_start    # Start the listener
```

### Available Skills

Claude Code has built-in skills for common workflows:

- **pymol-fundamentals** - Basic visualization, selections, coloring
- **protein-structure-basics** - Secondary structure, B-factor, representations
- **binding-site-visualization** - Protein-ligand interactions
- **structure-alignment-analysis** - Comparing and aligning structures
- **antibody-visualization** - CDR loops, epitopes, Fab structures
- **publication-figures** - High-quality figure export
- **movie-creation** - Animations and rotations

## Troubleshooting

### Connection Issues

- **"Could not connect to PyMOL"**: Make sure PyMOL is running and the plugin is loaded
- **Check listener status**: Run `claude_status` in PyMOL's command line
- **Restart listener**: Run `claude_stop` then `claude_start` in PyMOL

### Plugin Not Loading

- Run `claudemol setup` to configure PyMOL
- Check PyMOL's output for any error messages on startup

### First-Time Setup Help

Run the `/pymol-setup` skill in Claude Code for guided setup assistance.

## Configuration

The default socket port is **9880**. Both the plugin and Claude Code connection module use this port.

Key files:
- `src/claudemol/plugin.py` - PyMOL plugin (auto-loads via pymolrc)
- `src/claudemol/connection.py` - Python module for socket communication
- `claude-plugin/skills/` - Claude Code skills for PyMOL workflows

## Limitations

- PyMOL and Claude Code must run on the same machine (localhost connection)
- One active connection at a time
- Some complex multi-step operations may need guidance

## Contributing

Contributions welcome! This project aims to build comprehensive skills for Claude-PyMOL interaction. If you discover useful patterns or workflows, consider adding them as skills.

## License

MIT License - see LICENSE file for details.
