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.
@@ -1,9 +1,9 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: claudemol
3
- Version: 0.1.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/ai-mol
6
- Project-URL: Repository, https://github.com/ANaka/ai-mol
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
- # ai-mol: Control PyMOL with Claude Code
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
- ### Installation
49
+ ### 1. Install claudemol
50
+
51
+ ```bash
52
+ pip install claudemol
53
+ claudemol setup
54
+ ```
51
55
 
52
- 1. **Clone the repository:**
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
- ```bash
55
- git clone https://github.com/ANaka/ai-mol
56
- cd ai-mol
57
- ```
58
+ ### 2. Install the Claude Code plugin
58
59
 
59
- 2. **Set up the PyMOL plugin:**
60
+ ```
61
+ /plugin marketplace add ANaka/claudemol?path=claude-plugin
62
+ /plugin install claudemol-skills
63
+ ```
60
64
 
61
- Add this line to your `~/.pymolrc` (create it if it doesn't exist):
65
+ This gives Claude the skills and hooks to work with PyMOL.
62
66
 
63
- ```python
64
- run /path/to/ai-mol/claude_socket_plugin.py
65
- ```
67
+ ### 3. Start using it
66
68
 
67
- Replace `/path/to/ai-mol` with the actual path where you cloned the repository.
69
+ Open Claude Code and say:
68
70
 
69
- 3. **Start using it:**
71
+ > "Open PyMOL and load structure 1UBQ"
70
72
 
71
- Open Claude Code in the `ai-mol` directory and say:
73
+ Claude will launch PyMOL, connect via socket, and load the structure.
72
74
 
73
- > "Open PyMOL and load structure 1UBQ"
75
+ ### Optional: Seamless permissions
74
76
 
75
- Claude will launch PyMOL (with the socket listener active) and load the structure.
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 will launch PyMOL if it's not already running.
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 of the ligand as sticks"
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° rotation movie"
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
- Claude Code has built-in skills for common workflows:
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
- - Verify the path in your `~/.pymolrc` is correct
156
+ - Run `claudemol setup` to configure PyMOL
130
157
  - Check PyMOL's output for any error messages on startup
131
- - Try running `run /path/to/claude_socket_plugin.py` manually in PyMOL
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 the `/pymol-setup` skill in Claude Code for guided setup assistance.
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 Claude Code connection module use this port.
176
+ The default socket port is **9880**. Both the plugin and connection module use this port.
140
177
 
141
178
  Key files:
142
- - `claude_socket_plugin.py` - PyMOL plugin (headless, auto-loads via pymolrc)
143
- - `pymol_connection.py` - Python module for socket communication
144
- - `.claude/skills/` - Claude Code skills for PyMOL workflows
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
- # ai-mol Skills for Claude Code
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/ai-mol?path=claude-plugin
9
- /plugin install ai-mol-skills
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 `ai-mol` pip package installed:
16
+ You need the `claudemol` pip package installed:
17
17
 
18
18
  ```bash
19
- pip install ai-mol
20
- ai-mol setup
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.1.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/ai-mol"
28
- Repository = "https://github.com/ANaka/ai-mol"
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
- check_pymol_installed,
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'\n# claudemol: Claude Code integration\nrun {plugin_path}\n'
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/ai-mol?path=claude-plugin
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: ai-mol setup\n"
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 ai_mol.view import pymol_view
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() / ".ai-mol" / "scratch"
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