claudemol 0.1.0__tar.gz

claudemol-0.1.0/.gitignore

@@ -0,0 +1,125 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual Environments
+venv/
+.venv/
+env/
+ENV/
+env.bak/
+venv.bak/
+
+# PyCharm
+.idea/
+
+# VS Code
+.vscode/
+*.code-workspace
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# Environment variables
+.env
+.env.local
+.env.*.local
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+Icon
+._*
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Windows
+Thumbs.db
+Thumbs.db:encryptable
+ehthumbs.db
+ehthumbs_vista.db
+*.stackdump
+[Dd]esktop.ini
+$RECYCLE.BIN/
+*.cab
+*.msi
+*.msix
+*.msm
+*.msp
+*.lnk
+
+# Linux
+*~
+.fuse_hidden*
+.directory
+.Trash-*
+.nfs*
+
+# Project-specific
+images/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.hypothesis/
+*.cover
+*.log
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+.pytype/
+
+# Ruff
+.ruff_cache/
+
+# uv
+.uv/
+settings.json
+.mcp.json
+
+# Structure files (downloaded during sessions)
+*.cif
+*.pdb
+*.pdb1
+*.ccp4
+*.mtz
+
+# Scratch directory for temporary images
+scratch/
+
+# Ralph loop local state
+.claude/ralph-loop.local.md

claudemol-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vishnu Rajan Tejus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

claudemol-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+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.

claudemol-0.1.0/README.md

@@ -0,0 +1,136 @@
+# 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.

claudemol-0.1.0/claude-plugin/README.md

@@ -0,0 +1,44 @@
+# ai-mol Skills for Claude Code
+
+PyMOL visualization skills for Claude Code.
+
+## Installation
+
+```bash
+/plugin marketplace add ANaka/ai-mol?path=claude-plugin
+/plugin install ai-mol-skills
+```
+
+Then restart Claude Code.
+
+## Prerequisites
+
+You need the `ai-mol` pip package installed:
+
+```bash
+pip install ai-mol
+ai-mol setup
+```
+
+## Available Skills
+
+- **pymol-fundamentals** - Basic PyMOL operations: loading structures, selections, representations
+- **protein-structure-basics** - Visualizing protein secondary structure, B-factors, surfaces
+- **binding-site-visualization** - Protein-ligand binding pockets and active sites
+- **antibody-visualization** - Antibody structures, CDR loops, epitopes
+- **structure-alignment-analysis** - Comparing and aligning protein structures
+- **publication-figures** - Creating publication-quality molecular figures
+- **movie-creation** - Animations, rotations, and morphing sequences
+- **pymol-setup** - First-time PyMOL configuration
+- **pymol-connect** - Connecting to PyMOL sessions
+
+## Usage
+
+Once installed, just describe what you want to visualize:
+
+- "Load 1ubq and show it as a cartoon"
+- "Visualize the binding site of 1hsg"
+- "Create a publication figure of this protein"
+- "Align these two structures and show the differences"
+
+Claude will use the appropriate skill automatically.

claudemol-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[project]
+name = "claudemol"
+version = "0.1.0"
+description = "PyMOL integration for Claude Code - control molecular visualization via natural language"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "Alex Naka" }]
+keywords = ["pymol", "molecular-visualization", "claude", "ai", "structural-biology"]
+license = { text = "MIT" }
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "Topic :: Scientific/Engineering :: Visualization",
+]
+dependencies = []
+
+[project.scripts]
+claudemol = "claudemol.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/ANaka/ai-mol"
+Repository = "https://github.com/ANaka/ai-mol"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/claudemol"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/claudemol/**/*.py",
+    "README.md",
+    "LICENSE",
+]
+
+[tool.pyright]
+include = ["src/claudemol"]
+venvPath = "."
+venv = ".venv"
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+ignore = []
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+[tool.uv]
+dev-dependencies = ["pyright>=1.1.379", "pytest>=8.3.3", "ruff>=0.6.9"]

claudemol-0.1.0/src/claudemol/__init__.py

@@ -0,0 +1,32 @@
+"""
+claudemol: PyMOL integration for Claude Code
+
+Connect to PyMOL via socket for AI-assisted molecular visualization.
+"""
+
+from claudemol.connection import (
+    PyMOLConnection,
+    connect_or_launch,
+    launch_pymol,
+    find_pymol_command,
+    check_pymol_installed,
+)
+from claudemol.session import (
+    PyMOLSession,
+    get_session,
+    ensure_running,
+    stop_pymol,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "PyMOLConnection",
+    "PyMOLSession",
+    "connect_or_launch",
+    "launch_pymol",
+    "find_pymol_command",
+    "check_pymol_installed",
+    "get_session",
+    "ensure_running",
+    "stop_pymol",
+]