claudemol 0.1.0__tar.gz → 0.3.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {claudemol-0.1.0 → claudemol-0.3.0}/PKG-INFO +71 -33
- claudemol-0.3.0/README.md +174 -0
- {claudemol-0.1.0 → claudemol-0.3.0}/claude-plugin/README.md +6 -6
- {claudemol-0.1.0 → claudemol-0.3.0}/pyproject.toml +3 -3
- {claudemol-0.1.0 → claudemol-0.3.0}/src/claudemol/__init__.py +9 -3
- {claudemol-0.1.0 → claudemol-0.3.0}/src/claudemol/cli.py +26 -2
- {claudemol-0.1.0 → claudemol-0.3.0}/src/claudemol/connection.py +29 -1
- {claudemol-0.1.0 → claudemol-0.3.0}/src/claudemol/view.py +2 -2
- claudemol-0.1.0/README.md +0 -136
- {claudemol-0.1.0 → claudemol-0.3.0}/.gitignore +0 -0
- {claudemol-0.1.0 → claudemol-0.3.0}/LICENSE +0 -0
- {claudemol-0.1.0 → claudemol-0.3.0}/src/claudemol/plugin.py +0 -0
- {claudemol-0.1.0 → claudemol-0.3.0}/src/claudemol/session.py +0 -0
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: claudemol
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.3.0
|
|
4
4
|
Summary: PyMOL integration for Claude Code - control molecular visualization via natural language
|
|
5
|
-
Project-URL: Homepage, https://github.com/ANaka/
|
|
6
|
-
Project-URL: Repository, https://github.com/ANaka/
|
|
5
|
+
Project-URL: Homepage, https://github.com/ANaka/claudemol
|
|
6
|
+
Project-URL: Repository, https://github.com/ANaka/claudemol
|
|
7
7
|
Author: Alex Naka
|
|
8
8
|
License: MIT
|
|
9
9
|
License-File: LICENSE
|
|
@@ -20,18 +20,17 @@ Classifier: Topic :: Scientific/Engineering :: Visualization
|
|
|
20
20
|
Requires-Python: >=3.10
|
|
21
21
|
Description-Content-Type: text/markdown
|
|
22
22
|
|
|
23
|
-
#
|
|
23
|
+
# claudemol: Control PyMOL with Claude Code
|
|
24
24
|
|
|
25
25
|
Control PyMOL through natural language using Claude Code. This integration enables conversational structural biology, molecular visualization, and analysis.
|
|
26
26
|
|
|
27
|
-
https://github.com/user-attachments/assets/687f43dc-d45e-477e-ac2b-7438e175cb36
|
|
28
|
-
|
|
29
27
|
## Features
|
|
30
28
|
|
|
31
29
|
- **Natural language control**: Tell Claude what you want to visualize and it executes PyMOL commands
|
|
32
30
|
- **Direct socket communication**: Claude Code talks directly to PyMOL (no intermediary server)
|
|
33
31
|
- **Full PyMOL access**: Manipulate representations, colors, views, perform measurements, alignments, and more
|
|
34
32
|
- **Skill-based workflows**: Built-in skills for common tasks like binding site visualization and publication figures
|
|
33
|
+
- **Connect to anything**: Because Claude is the bridge, it can pull in data from online databases (UniProt, PDB, OPM), literature, protein language model annotations, or local analysis scripts and map them directly onto your structure
|
|
35
34
|
|
|
36
35
|
## Architecture
|
|
37
36
|
|
|
@@ -47,32 +46,47 @@ Claude Code → TCP Socket (port 9880) → PyMOL Plugin → cmd.* execution
|
|
|
47
46
|
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI installed
|
|
48
47
|
- Python 3.10+
|
|
49
48
|
|
|
50
|
-
###
|
|
49
|
+
### 1. Install claudemol
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
pip install claudemol
|
|
53
|
+
claudemol setup
|
|
54
|
+
```
|
|
51
55
|
|
|
52
|
-
|
|
56
|
+
This configures PyMOL to auto-load the socket plugin and saves your Python path to `~/.claudemol/config.json` so future Claude Code sessions can find it automatically.
|
|
53
57
|
|
|
54
|
-
|
|
55
|
-
git clone https://github.com/ANaka/ai-mol
|
|
56
|
-
cd ai-mol
|
|
57
|
-
```
|
|
58
|
+
### 2. Install the Claude Code plugin
|
|
58
59
|
|
|
59
|
-
|
|
60
|
+
```
|
|
61
|
+
/plugin marketplace add ANaka/claudemol?path=claude-plugin
|
|
62
|
+
/plugin install claudemol-skills
|
|
63
|
+
```
|
|
60
64
|
|
|
61
|
-
|
|
65
|
+
This gives Claude the skills and hooks to work with PyMOL.
|
|
62
66
|
|
|
63
|
-
|
|
64
|
-
run /path/to/ai-mol/claude_socket_plugin.py
|
|
65
|
-
```
|
|
67
|
+
### 3. Start using it
|
|
66
68
|
|
|
67
|
-
|
|
69
|
+
Open Claude Code and say:
|
|
68
70
|
|
|
69
|
-
|
|
71
|
+
> "Open PyMOL and load structure 1UBQ"
|
|
70
72
|
|
|
71
|
-
|
|
73
|
+
Claude will launch PyMOL, connect via socket, and load the structure.
|
|
72
74
|
|
|
73
|
-
|
|
75
|
+
### Optional: Seamless permissions
|
|
74
76
|
|
|
75
|
-
|
|
77
|
+
By default, Claude asks for approval before running each command. To auto-approve PyMOL-related commands, add to your project's `.claude/settings.json`:
|
|
78
|
+
|
|
79
|
+
```json
|
|
80
|
+
{
|
|
81
|
+
"permissions": {
|
|
82
|
+
"allow": [
|
|
83
|
+
"Bash(claudemol*)",
|
|
84
|
+
"Bash(*python*claudemol*)",
|
|
85
|
+
"Bash(pymol*)"
|
|
86
|
+
]
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
```
|
|
76
90
|
|
|
77
91
|
## Usage
|
|
78
92
|
|
|
@@ -84,15 +98,15 @@ Simply ask Claude to open PyMOL or load a structure:
|
|
|
84
98
|
- "Load PDB 4HHB and show as cartoon"
|
|
85
99
|
- "Fetch 1UBQ from the PDB"
|
|
86
100
|
|
|
87
|
-
Claude
|
|
101
|
+
Claude connects to an existing PyMOL if one is running, or launches a new instance.
|
|
88
102
|
|
|
89
103
|
### Example Commands
|
|
90
104
|
|
|
91
105
|
- "Color the protein by secondary structure"
|
|
92
|
-
- "Show the binding site residues within
|
|
106
|
+
- "Show the binding site residues within 5A of the ligand as sticks"
|
|
93
107
|
- "Align these two structures and calculate RMSD"
|
|
94
108
|
- "Create a publication-quality figure with ray tracing"
|
|
95
|
-
- "Make a 360
|
|
109
|
+
- "Make a 360 degree rotation movie"
|
|
96
110
|
|
|
97
111
|
### PyMOL Console Commands
|
|
98
112
|
|
|
@@ -106,7 +120,7 @@ claude_start # Start the listener
|
|
|
106
120
|
|
|
107
121
|
### Available Skills
|
|
108
122
|
|
|
109
|
-
|
|
123
|
+
The plugin includes skills for common workflows:
|
|
110
124
|
|
|
111
125
|
- **pymol-fundamentals** - Basic visualization, selections, coloring
|
|
112
126
|
- **protein-structure-basics** - Secondary structure, B-factor, representations
|
|
@@ -116,6 +130,19 @@ Claude Code has built-in skills for common workflows:
|
|
|
116
130
|
- **publication-figures** - High-quality figure export
|
|
117
131
|
- **movie-creation** - Animations and rotations
|
|
118
132
|
|
|
133
|
+
## How It Works
|
|
134
|
+
|
|
135
|
+
### Connection Lifecycle
|
|
136
|
+
|
|
137
|
+
1. On session start, a hook runs `claudemol status` to check if PyMOL is reachable
|
|
138
|
+
2. When you ask Claude to work with PyMOL, it uses `connect_or_launch()` — connecting to an existing instance or starting a new one
|
|
139
|
+
3. Commands are sent as Python code over TCP and executed inside PyMOL via the socket plugin
|
|
140
|
+
4. If the connection drops, `conn.execute()` auto-reconnects (up to 3 attempts)
|
|
141
|
+
|
|
142
|
+
### Venv Support
|
|
143
|
+
|
|
144
|
+
`claudemol setup` saves your Python interpreter path to `~/.claudemol/config.json`. This means claudemol works even when installed in a project virtualenv — the SessionStart hook and skills read the config to find the right Python.
|
|
145
|
+
|
|
119
146
|
## Troubleshooting
|
|
120
147
|
|
|
121
148
|
### Connection Issues
|
|
@@ -126,22 +153,33 @@ Claude Code has built-in skills for common workflows:
|
|
|
126
153
|
|
|
127
154
|
### Plugin Not Loading
|
|
128
155
|
|
|
129
|
-
-
|
|
156
|
+
- Run `claudemol setup` to configure PyMOL
|
|
130
157
|
- Check PyMOL's output for any error messages on startup
|
|
131
|
-
|
|
158
|
+
|
|
159
|
+
### claudemol Not Found
|
|
160
|
+
|
|
161
|
+
If Claude reports `ModuleNotFoundError`, claudemol may be installed in a venv that isn't active. Fix:
|
|
162
|
+
|
|
163
|
+
```bash
|
|
164
|
+
# Re-run setup from the venv that has claudemol
|
|
165
|
+
.venv/bin/claudemol setup
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
This updates `~/.claudemol/config.json` so future sessions find it.
|
|
132
169
|
|
|
133
170
|
### First-Time Setup Help
|
|
134
171
|
|
|
135
|
-
Run
|
|
172
|
+
Run `/pymol-setup` in Claude Code for guided setup assistance.
|
|
136
173
|
|
|
137
174
|
## Configuration
|
|
138
175
|
|
|
139
|
-
The default socket port is **9880**. Both the plugin and
|
|
176
|
+
The default socket port is **9880**. Both the plugin and connection module use this port.
|
|
140
177
|
|
|
141
178
|
Key files:
|
|
142
|
-
- `
|
|
143
|
-
-
|
|
144
|
-
-
|
|
179
|
+
- `~/.pymolrc` - PyMOL startup script (loads the socket plugin)
|
|
180
|
+
- `~/.claudemol/config.json` - Persisted Python path for venv discovery
|
|
181
|
+
- `src/claudemol/plugin.py` - Socket listener plugin (runs inside PyMOL)
|
|
182
|
+
- `src/claudemol/connection.py` - Python module for socket communication
|
|
145
183
|
|
|
146
184
|
## Limitations
|
|
147
185
|
|
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
# claudemol: Control PyMOL with Claude Code
|
|
2
|
+
|
|
3
|
+
Control PyMOL through natural language using Claude Code. This integration enables conversational structural biology, molecular visualization, and analysis.
|
|
4
|
+
|
|
5
|
+
## Features
|
|
6
|
+
|
|
7
|
+
- **Natural language control**: Tell Claude what you want to visualize and it executes PyMOL commands
|
|
8
|
+
- **Direct socket communication**: Claude Code talks directly to PyMOL (no intermediary server)
|
|
9
|
+
- **Full PyMOL access**: Manipulate representations, colors, views, perform measurements, alignments, and more
|
|
10
|
+
- **Skill-based workflows**: Built-in skills for common tasks like binding site visualization and publication figures
|
|
11
|
+
- **Connect to anything**: Because Claude is the bridge, it can pull in data from online databases (UniProt, PDB, OPM), literature, protein language model annotations, or local analysis scripts and map them directly onto your structure
|
|
12
|
+
|
|
13
|
+
## Architecture
|
|
14
|
+
|
|
15
|
+
```
|
|
16
|
+
Claude Code → TCP Socket (port 9880) → PyMOL Plugin → cmd.* execution
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Quick Start
|
|
20
|
+
|
|
21
|
+
### Prerequisites
|
|
22
|
+
|
|
23
|
+
- PyMOL installed on your system
|
|
24
|
+
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI installed
|
|
25
|
+
- Python 3.10+
|
|
26
|
+
|
|
27
|
+
### 1. Install claudemol
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
pip install claudemol
|
|
31
|
+
claudemol setup
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
This configures PyMOL to auto-load the socket plugin and saves your Python path to `~/.claudemol/config.json` so future Claude Code sessions can find it automatically.
|
|
35
|
+
|
|
36
|
+
### 2. Install the Claude Code plugin
|
|
37
|
+
|
|
38
|
+
```
|
|
39
|
+
/plugin marketplace add ANaka/claudemol?path=claude-plugin
|
|
40
|
+
/plugin install claudemol-skills
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
This gives Claude the skills and hooks to work with PyMOL.
|
|
44
|
+
|
|
45
|
+
### 3. Start using it
|
|
46
|
+
|
|
47
|
+
Open Claude Code and say:
|
|
48
|
+
|
|
49
|
+
> "Open PyMOL and load structure 1UBQ"
|
|
50
|
+
|
|
51
|
+
Claude will launch PyMOL, connect via socket, and load the structure.
|
|
52
|
+
|
|
53
|
+
### Optional: Seamless permissions
|
|
54
|
+
|
|
55
|
+
By default, Claude asks for approval before running each command. To auto-approve PyMOL-related commands, add to your project's `.claude/settings.json`:
|
|
56
|
+
|
|
57
|
+
```json
|
|
58
|
+
{
|
|
59
|
+
"permissions": {
|
|
60
|
+
"allow": [
|
|
61
|
+
"Bash(claudemol*)",
|
|
62
|
+
"Bash(*python*claudemol*)",
|
|
63
|
+
"Bash(pymol*)"
|
|
64
|
+
]
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## Usage
|
|
70
|
+
|
|
71
|
+
### Starting a Session
|
|
72
|
+
|
|
73
|
+
Simply ask Claude to open PyMOL or load a structure:
|
|
74
|
+
|
|
75
|
+
- "Open PyMOL"
|
|
76
|
+
- "Load PDB 4HHB and show as cartoon"
|
|
77
|
+
- "Fetch 1UBQ from the PDB"
|
|
78
|
+
|
|
79
|
+
Claude connects to an existing PyMOL if one is running, or launches a new instance.
|
|
80
|
+
|
|
81
|
+
### Example Commands
|
|
82
|
+
|
|
83
|
+
- "Color the protein by secondary structure"
|
|
84
|
+
- "Show the binding site residues within 5A of the ligand as sticks"
|
|
85
|
+
- "Align these two structures and calculate RMSD"
|
|
86
|
+
- "Create a publication-quality figure with ray tracing"
|
|
87
|
+
- "Make a 360 degree rotation movie"
|
|
88
|
+
|
|
89
|
+
### PyMOL Console Commands
|
|
90
|
+
|
|
91
|
+
Check or control the socket listener from PyMOL's command line:
|
|
92
|
+
|
|
93
|
+
```
|
|
94
|
+
claude_status # Check if listener is running
|
|
95
|
+
claude_stop # Stop the listener
|
|
96
|
+
claude_start # Start the listener
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
### Available Skills
|
|
100
|
+
|
|
101
|
+
The plugin includes skills for common workflows:
|
|
102
|
+
|
|
103
|
+
- **pymol-fundamentals** - Basic visualization, selections, coloring
|
|
104
|
+
- **protein-structure-basics** - Secondary structure, B-factor, representations
|
|
105
|
+
- **binding-site-visualization** - Protein-ligand interactions
|
|
106
|
+
- **structure-alignment-analysis** - Comparing and aligning structures
|
|
107
|
+
- **antibody-visualization** - CDR loops, epitopes, Fab structures
|
|
108
|
+
- **publication-figures** - High-quality figure export
|
|
109
|
+
- **movie-creation** - Animations and rotations
|
|
110
|
+
|
|
111
|
+
## How It Works
|
|
112
|
+
|
|
113
|
+
### Connection Lifecycle
|
|
114
|
+
|
|
115
|
+
1. On session start, a hook runs `claudemol status` to check if PyMOL is reachable
|
|
116
|
+
2. When you ask Claude to work with PyMOL, it uses `connect_or_launch()` — connecting to an existing instance or starting a new one
|
|
117
|
+
3. Commands are sent as Python code over TCP and executed inside PyMOL via the socket plugin
|
|
118
|
+
4. If the connection drops, `conn.execute()` auto-reconnects (up to 3 attempts)
|
|
119
|
+
|
|
120
|
+
### Venv Support
|
|
121
|
+
|
|
122
|
+
`claudemol setup` saves your Python interpreter path to `~/.claudemol/config.json`. This means claudemol works even when installed in a project virtualenv — the SessionStart hook and skills read the config to find the right Python.
|
|
123
|
+
|
|
124
|
+
## Troubleshooting
|
|
125
|
+
|
|
126
|
+
### Connection Issues
|
|
127
|
+
|
|
128
|
+
- **"Could not connect to PyMOL"**: Make sure PyMOL is running and the plugin is loaded
|
|
129
|
+
- **Check listener status**: Run `claude_status` in PyMOL's command line
|
|
130
|
+
- **Restart listener**: Run `claude_stop` then `claude_start` in PyMOL
|
|
131
|
+
|
|
132
|
+
### Plugin Not Loading
|
|
133
|
+
|
|
134
|
+
- Run `claudemol setup` to configure PyMOL
|
|
135
|
+
- Check PyMOL's output for any error messages on startup
|
|
136
|
+
|
|
137
|
+
### claudemol Not Found
|
|
138
|
+
|
|
139
|
+
If Claude reports `ModuleNotFoundError`, claudemol may be installed in a venv that isn't active. Fix:
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
# Re-run setup from the venv that has claudemol
|
|
143
|
+
.venv/bin/claudemol setup
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
This updates `~/.claudemol/config.json` so future sessions find it.
|
|
147
|
+
|
|
148
|
+
### First-Time Setup Help
|
|
149
|
+
|
|
150
|
+
Run `/pymol-setup` in Claude Code for guided setup assistance.
|
|
151
|
+
|
|
152
|
+
## Configuration
|
|
153
|
+
|
|
154
|
+
The default socket port is **9880**. Both the plugin and connection module use this port.
|
|
155
|
+
|
|
156
|
+
Key files:
|
|
157
|
+
- `~/.pymolrc` - PyMOL startup script (loads the socket plugin)
|
|
158
|
+
- `~/.claudemol/config.json` - Persisted Python path for venv discovery
|
|
159
|
+
- `src/claudemol/plugin.py` - Socket listener plugin (runs inside PyMOL)
|
|
160
|
+
- `src/claudemol/connection.py` - Python module for socket communication
|
|
161
|
+
|
|
162
|
+
## Limitations
|
|
163
|
+
|
|
164
|
+
- PyMOL and Claude Code must run on the same machine (localhost connection)
|
|
165
|
+
- One active connection at a time
|
|
166
|
+
- Some complex multi-step operations may need guidance
|
|
167
|
+
|
|
168
|
+
## Contributing
|
|
169
|
+
|
|
170
|
+
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.
|
|
171
|
+
|
|
172
|
+
## License
|
|
173
|
+
|
|
174
|
+
MIT License - see LICENSE file for details.
|
|
@@ -1,23 +1,23 @@
|
|
|
1
|
-
#
|
|
1
|
+
# claudemol Skills for Claude Code
|
|
2
2
|
|
|
3
3
|
PyMOL visualization skills for Claude Code.
|
|
4
4
|
|
|
5
5
|
## Installation
|
|
6
6
|
|
|
7
7
|
```bash
|
|
8
|
-
/plugin marketplace add ANaka/
|
|
9
|
-
/plugin install
|
|
8
|
+
/plugin marketplace add ANaka/claudemol?path=claude-plugin
|
|
9
|
+
/plugin install claudemol-skills
|
|
10
10
|
```
|
|
11
11
|
|
|
12
12
|
Then restart Claude Code.
|
|
13
13
|
|
|
14
14
|
## Prerequisites
|
|
15
15
|
|
|
16
|
-
You need the `
|
|
16
|
+
You need the `claudemol` pip package installed:
|
|
17
17
|
|
|
18
18
|
```bash
|
|
19
|
-
pip install
|
|
20
|
-
|
|
19
|
+
pip install claudemol
|
|
20
|
+
claudemol setup
|
|
21
21
|
```
|
|
22
22
|
|
|
23
23
|
## Available Skills
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "claudemol"
|
|
3
|
-
version = "0.
|
|
3
|
+
version = "0.3.0"
|
|
4
4
|
description = "PyMOL integration for Claude Code - control molecular visualization via natural language"
|
|
5
5
|
readme = "README.md"
|
|
6
6
|
requires-python = ">=3.10"
|
|
@@ -24,8 +24,8 @@ dependencies = []
|
|
|
24
24
|
claudemol = "claudemol.cli:main"
|
|
25
25
|
|
|
26
26
|
[project.urls]
|
|
27
|
-
Homepage = "https://github.com/ANaka/
|
|
28
|
-
Repository = "https://github.com/ANaka/
|
|
27
|
+
Homepage = "https://github.com/ANaka/claudemol"
|
|
28
|
+
Repository = "https://github.com/ANaka/claudemol"
|
|
29
29
|
|
|
30
30
|
[build-system]
|
|
31
31
|
requires = ["hatchling"]
|
|
@@ -6,15 +6,18 @@ Connect to PyMOL via socket for AI-assisted molecular visualization.
|
|
|
6
6
|
|
|
7
7
|
from claudemol.connection import (
|
|
8
8
|
PyMOLConnection,
|
|
9
|
+
check_pymol_installed,
|
|
9
10
|
connect_or_launch,
|
|
10
|
-
launch_pymol,
|
|
11
11
|
find_pymol_command,
|
|
12
|
-
|
|
12
|
+
get_config,
|
|
13
|
+
get_configured_python,
|
|
14
|
+
launch_pymol,
|
|
15
|
+
save_config,
|
|
13
16
|
)
|
|
14
17
|
from claudemol.session import (
|
|
15
18
|
PyMOLSession,
|
|
16
|
-
get_session,
|
|
17
19
|
ensure_running,
|
|
20
|
+
get_session,
|
|
18
21
|
stop_pymol,
|
|
19
22
|
)
|
|
20
23
|
|
|
@@ -26,6 +29,9 @@ __all__ = [
|
|
|
26
29
|
"launch_pymol",
|
|
27
30
|
"find_pymol_command",
|
|
28
31
|
"check_pymol_installed",
|
|
32
|
+
"get_config",
|
|
33
|
+
"save_config",
|
|
34
|
+
"get_configured_python",
|
|
29
35
|
"get_session",
|
|
30
36
|
"ensure_running",
|
|
31
37
|
"stop_pymol",
|
|
@@ -12,10 +12,14 @@ import sys
|
|
|
12
12
|
from pathlib import Path
|
|
13
13
|
|
|
14
14
|
from claudemol.connection import (
|
|
15
|
+
CONFIG_FILE,
|
|
15
16
|
PyMOLConnection,
|
|
16
17
|
check_pymol_installed,
|
|
17
18
|
find_pymol_command,
|
|
19
|
+
get_config,
|
|
20
|
+
get_configured_python,
|
|
18
21
|
get_plugin_path,
|
|
22
|
+
save_config,
|
|
19
23
|
)
|
|
20
24
|
|
|
21
25
|
|
|
@@ -34,10 +38,13 @@ def setup_pymol():
|
|
|
34
38
|
if "claudemol" in content or "claude_socket_plugin" in content:
|
|
35
39
|
print("PyMOL already configured for claudemol.")
|
|
36
40
|
print(f"Plugin: {plugin_path}")
|
|
41
|
+
# Still save config (in case Python path changed)
|
|
42
|
+
save_config({"python_path": sys.executable})
|
|
43
|
+
print(f"Saved Python path: {sys.executable}")
|
|
37
44
|
return 0
|
|
38
45
|
|
|
39
46
|
# Add to .pymolrc
|
|
40
|
-
run_command = f
|
|
47
|
+
run_command = f"\n# claudemol: Claude Code integration\nrun {plugin_path}\n"
|
|
41
48
|
|
|
42
49
|
if pymolrc_path.exists():
|
|
43
50
|
with open(pymolrc_path, "a") as f:
|
|
@@ -58,6 +65,10 @@ def setup_pymol():
|
|
|
58
65
|
print(" - brew install pymol (macOS)")
|
|
59
66
|
print(" - Download from https://pymol.org")
|
|
60
67
|
|
|
68
|
+
# Save Python path for SessionStart hook and skills
|
|
69
|
+
save_config({"python_path": sys.executable})
|
|
70
|
+
print(f"Saved Python path: {sys.executable}")
|
|
71
|
+
|
|
61
72
|
return 0
|
|
62
73
|
|
|
63
74
|
|
|
@@ -65,6 +76,11 @@ def check_status():
|
|
|
65
76
|
"""Check PyMOL connection status."""
|
|
66
77
|
print("Checking PyMOL status...")
|
|
67
78
|
|
|
79
|
+
# Show configured Python if available
|
|
80
|
+
configured_python = get_configured_python()
|
|
81
|
+
if configured_python:
|
|
82
|
+
print(f"Configured Python: {configured_python}")
|
|
83
|
+
|
|
68
84
|
# Check if PyMOL is installed
|
|
69
85
|
pymol_cmd = find_pymol_command()
|
|
70
86
|
if pymol_cmd:
|
|
@@ -125,6 +141,14 @@ def show_info():
|
|
|
125
141
|
pymol_cmd = find_pymol_command()
|
|
126
142
|
print(f" PyMOL command: {' '.join(pymol_cmd) if pymol_cmd else 'not found'}")
|
|
127
143
|
|
|
144
|
+
print(f" Config file: {CONFIG_FILE}")
|
|
145
|
+
config = get_config()
|
|
146
|
+
if config:
|
|
147
|
+
for key, value in config.items():
|
|
148
|
+
print(f" Config {key}: {value}")
|
|
149
|
+
else:
|
|
150
|
+
print(" Config: not set (run 'claudemol setup' to configure)")
|
|
151
|
+
|
|
128
152
|
|
|
129
153
|
def main():
|
|
130
154
|
parser = argparse.ArgumentParser(
|
|
@@ -138,7 +162,7 @@ Commands:
|
|
|
138
162
|
info Show installation info
|
|
139
163
|
|
|
140
164
|
For Claude Code skills, install the claudemol-skills plugin:
|
|
141
|
-
/plugin marketplace add ANaka/
|
|
165
|
+
/plugin marketplace add ANaka/claudemol?path=claude-plugin
|
|
142
166
|
/plugin install claudemol-skills
|
|
143
167
|
""",
|
|
144
168
|
)
|
|
@@ -17,6 +17,9 @@ DEFAULT_PORT = 9880
|
|
|
17
17
|
CONNECT_TIMEOUT = 5.0
|
|
18
18
|
RECV_TIMEOUT = 30.0
|
|
19
19
|
|
|
20
|
+
CONFIG_DIR = Path.home() / ".claudemol"
|
|
21
|
+
CONFIG_FILE = CONFIG_DIR / "config.json"
|
|
22
|
+
|
|
20
23
|
# Common PyMOL installation paths
|
|
21
24
|
PYMOL_PATHS = [
|
|
22
25
|
# uv environment (created by /pymol-setup)
|
|
@@ -195,7 +198,7 @@ def launch_pymol(file_path=None, wait_for_socket=True, timeout=10.0):
|
|
|
195
198
|
if not pymol_cmd:
|
|
196
199
|
raise RuntimeError(
|
|
197
200
|
"PyMOL not found. Please install PyMOL:\n"
|
|
198
|
-
" - Run:
|
|
201
|
+
" - Run: claudemol setup\n"
|
|
199
202
|
" - Or: pip install pymol-open-source-whl\n"
|
|
200
203
|
" - Or: brew install pymol (macOS)"
|
|
201
204
|
)
|
|
@@ -247,3 +250,28 @@ def connect_or_launch(file_path=None):
|
|
|
247
250
|
process = launch_pymol(file_path=file_path)
|
|
248
251
|
conn.connect()
|
|
249
252
|
return conn, process
|
|
253
|
+
|
|
254
|
+
|
|
255
|
+
def get_config():
|
|
256
|
+
"""Read persisted claudemol config."""
|
|
257
|
+
if CONFIG_FILE.exists():
|
|
258
|
+
try:
|
|
259
|
+
return json.loads(CONFIG_FILE.read_text())
|
|
260
|
+
except (json.JSONDecodeError, OSError):
|
|
261
|
+
return {}
|
|
262
|
+
return {}
|
|
263
|
+
|
|
264
|
+
|
|
265
|
+
def save_config(config):
|
|
266
|
+
"""Save claudemol config."""
|
|
267
|
+
CONFIG_DIR.mkdir(parents=True, exist_ok=True)
|
|
268
|
+
CONFIG_FILE.write_text(json.dumps(config, indent=2) + "\n")
|
|
269
|
+
|
|
270
|
+
|
|
271
|
+
def get_configured_python():
|
|
272
|
+
"""Get the Python path from persisted config. Returns path string or None."""
|
|
273
|
+
config = get_config()
|
|
274
|
+
python_path = config.get("python_path")
|
|
275
|
+
if python_path and os.path.isfile(python_path) and os.access(python_path, os.X_OK):
|
|
276
|
+
return python_path
|
|
277
|
+
return None
|
|
@@ -4,7 +4,7 @@ Visual feedback helper for PyMOL.
|
|
|
4
4
|
Provides a simple way to execute commands and save/view the result.
|
|
5
5
|
|
|
6
6
|
Usage:
|
|
7
|
-
from
|
|
7
|
+
from claudemol.view import pymol_view
|
|
8
8
|
|
|
9
9
|
# Execute commands and save a snapshot
|
|
10
10
|
path = pymol_view("cmd.fetch('1ubq'); cmd.show('cartoon')", name="ubq_cartoon")
|
|
@@ -21,7 +21,7 @@ from pathlib import Path
|
|
|
21
21
|
|
|
22
22
|
DEFAULT_HOST = "localhost"
|
|
23
23
|
DEFAULT_PORT = 9880
|
|
24
|
-
SCRATCH_DIR = Path.home() / ".
|
|
24
|
+
SCRATCH_DIR = Path.home() / ".claudemol" / "scratch"
|
|
25
25
|
|
|
26
26
|
|
|
27
27
|
def ensure_scratch_dir():
|
claudemol-0.1.0/README.md
DELETED
|
@@ -1,136 +0,0 @@
|
|
|
1
|
-
# ai-mol: Control PyMOL with Claude Code
|
|
2
|
-
|
|
3
|
-
Control PyMOL through natural language using Claude Code. This integration enables conversational structural biology, molecular visualization, and analysis.
|
|
4
|
-
|
|
5
|
-
https://github.com/user-attachments/assets/687f43dc-d45e-477e-ac2b-7438e175cb36
|
|
6
|
-
|
|
7
|
-
## Features
|
|
8
|
-
|
|
9
|
-
- **Natural language control**: Tell Claude what you want to visualize and it executes PyMOL commands
|
|
10
|
-
- **Direct socket communication**: Claude Code talks directly to PyMOL (no intermediary server)
|
|
11
|
-
- **Full PyMOL access**: Manipulate representations, colors, views, perform measurements, alignments, and more
|
|
12
|
-
- **Skill-based workflows**: Built-in skills for common tasks like binding site visualization and publication figures
|
|
13
|
-
|
|
14
|
-
## Architecture
|
|
15
|
-
|
|
16
|
-
```
|
|
17
|
-
Claude Code → TCP Socket (port 9880) → PyMOL Plugin → cmd.* execution
|
|
18
|
-
```
|
|
19
|
-
|
|
20
|
-
## Quick Start
|
|
21
|
-
|
|
22
|
-
### Prerequisites
|
|
23
|
-
|
|
24
|
-
- PyMOL installed on your system
|
|
25
|
-
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI installed
|
|
26
|
-
- Python 3.10+
|
|
27
|
-
|
|
28
|
-
### Installation
|
|
29
|
-
|
|
30
|
-
1. **Clone the repository:**
|
|
31
|
-
|
|
32
|
-
```bash
|
|
33
|
-
git clone https://github.com/ANaka/ai-mol
|
|
34
|
-
cd ai-mol
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
2. **Set up the PyMOL plugin:**
|
|
38
|
-
|
|
39
|
-
Add this line to your `~/.pymolrc` (create it if it doesn't exist):
|
|
40
|
-
|
|
41
|
-
```python
|
|
42
|
-
run /path/to/ai-mol/claude_socket_plugin.py
|
|
43
|
-
```
|
|
44
|
-
|
|
45
|
-
Replace `/path/to/ai-mol` with the actual path where you cloned the repository.
|
|
46
|
-
|
|
47
|
-
3. **Start using it:**
|
|
48
|
-
|
|
49
|
-
Open Claude Code in the `ai-mol` directory and say:
|
|
50
|
-
|
|
51
|
-
> "Open PyMOL and load structure 1UBQ"
|
|
52
|
-
|
|
53
|
-
Claude will launch PyMOL (with the socket listener active) and load the structure.
|
|
54
|
-
|
|
55
|
-
## Usage
|
|
56
|
-
|
|
57
|
-
### Starting a Session
|
|
58
|
-
|
|
59
|
-
Simply ask Claude to open PyMOL or load a structure:
|
|
60
|
-
|
|
61
|
-
- "Open PyMOL"
|
|
62
|
-
- "Load PDB 4HHB and show as cartoon"
|
|
63
|
-
- "Fetch 1UBQ from the PDB"
|
|
64
|
-
|
|
65
|
-
Claude will launch PyMOL if it's not already running.
|
|
66
|
-
|
|
67
|
-
### Example Commands
|
|
68
|
-
|
|
69
|
-
- "Color the protein by secondary structure"
|
|
70
|
-
- "Show the binding site residues within 5Å of the ligand as sticks"
|
|
71
|
-
- "Align these two structures and calculate RMSD"
|
|
72
|
-
- "Create a publication-quality figure with ray tracing"
|
|
73
|
-
- "Make a 360° rotation movie"
|
|
74
|
-
|
|
75
|
-
### PyMOL Console Commands
|
|
76
|
-
|
|
77
|
-
Check or control the socket listener from PyMOL's command line:
|
|
78
|
-
|
|
79
|
-
```
|
|
80
|
-
claude_status # Check if listener is running
|
|
81
|
-
claude_stop # Stop the listener
|
|
82
|
-
claude_start # Start the listener
|
|
83
|
-
```
|
|
84
|
-
|
|
85
|
-
### Available Skills
|
|
86
|
-
|
|
87
|
-
Claude Code has built-in skills for common workflows:
|
|
88
|
-
|
|
89
|
-
- **pymol-fundamentals** - Basic visualization, selections, coloring
|
|
90
|
-
- **protein-structure-basics** - Secondary structure, B-factor, representations
|
|
91
|
-
- **binding-site-visualization** - Protein-ligand interactions
|
|
92
|
-
- **structure-alignment-analysis** - Comparing and aligning structures
|
|
93
|
-
- **antibody-visualization** - CDR loops, epitopes, Fab structures
|
|
94
|
-
- **publication-figures** - High-quality figure export
|
|
95
|
-
- **movie-creation** - Animations and rotations
|
|
96
|
-
|
|
97
|
-
## Troubleshooting
|
|
98
|
-
|
|
99
|
-
### Connection Issues
|
|
100
|
-
|
|
101
|
-
- **"Could not connect to PyMOL"**: Make sure PyMOL is running and the plugin is loaded
|
|
102
|
-
- **Check listener status**: Run `claude_status` in PyMOL's command line
|
|
103
|
-
- **Restart listener**: Run `claude_stop` then `claude_start` in PyMOL
|
|
104
|
-
|
|
105
|
-
### Plugin Not Loading
|
|
106
|
-
|
|
107
|
-
- Verify the path in your `~/.pymolrc` is correct
|
|
108
|
-
- Check PyMOL's output for any error messages on startup
|
|
109
|
-
- Try running `run /path/to/claude_socket_plugin.py` manually in PyMOL
|
|
110
|
-
|
|
111
|
-
### First-Time Setup Help
|
|
112
|
-
|
|
113
|
-
Run the `/pymol-setup` skill in Claude Code for guided setup assistance.
|
|
114
|
-
|
|
115
|
-
## Configuration
|
|
116
|
-
|
|
117
|
-
The default socket port is **9880**. Both the plugin and Claude Code connection module use this port.
|
|
118
|
-
|
|
119
|
-
Key files:
|
|
120
|
-
- `claude_socket_plugin.py` - PyMOL plugin (headless, auto-loads via pymolrc)
|
|
121
|
-
- `pymol_connection.py` - Python module for socket communication
|
|
122
|
-
- `.claude/skills/` - Claude Code skills for PyMOL workflows
|
|
123
|
-
|
|
124
|
-
## Limitations
|
|
125
|
-
|
|
126
|
-
- PyMOL and Claude Code must run on the same machine (localhost connection)
|
|
127
|
-
- One active connection at a time
|
|
128
|
-
- Some complex multi-step operations may need guidance
|
|
129
|
-
|
|
130
|
-
## Contributing
|
|
131
|
-
|
|
132
|
-
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.
|
|
133
|
-
|
|
134
|
-
## License
|
|
135
|
-
|
|
136
|
-
MIT License - see LICENSE file for details.
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|