Metadata-Version: 2.4
Name: claudemol
Version: 0.1.0
Summary: PyMOL integration for Claude Code - control molecular visualization via natural language
Project-URL: Homepage, https://github.com/ANaka/ai-mol
Project-URL: Repository, https://github.com/ANaka/ai-mol
Author: Alex Naka
License: MIT
License-File: LICENSE
Keywords: ai,claude,molecular-visualization,pymol,structural-biology
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# ai-mol: Control PyMOL with Claude Code

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

https://github.com/user-attachments/assets/687f43dc-d45e-477e-ac2b-7438e175cb36

## 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

1. **Clone the repository:**

   ```bash
   git clone https://github.com/ANaka/ai-mol
   cd ai-mol
   ```

2. **Set up the PyMOL plugin:**

   Add this line to your `~/.pymolrc` (create it if it doesn't exist):

   ```python
   run /path/to/ai-mol/claude_socket_plugin.py
   ```

   Replace `/path/to/ai-mol` with the actual path where you cloned the repository.

3. **Start using it:**

   Open Claude Code in the `ai-mol` directory 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

- Verify the path in your `~/.pymolrc` is correct
- Check PyMOL's output for any error messages on startup
- Try running `run /path/to/claude_socket_plugin.py` manually in PyMOL

### 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:
- `claude_socket_plugin.py` - PyMOL plugin (headless, auto-loads via pymolrc)
- `pymol_connection.py` - Python module for socket communication
- `.claude/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.
