claudemol 0.2.0__tar.gz → 0.3.0__tar.gz

{claudemol-0.2.0 → claudemol-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claudemol
-Version: 0.2.0
+Version: 0.3.0
 Summary: PyMOL integration for Claude Code - control molecular visualization via natural language
 Project-URL: Homepage, https://github.com/ANaka/claudemol
 Project-URL: Repository, https://github.com/ANaka/claudemol
@@ -30,6 +30,7 @@ Control PyMOL through natural language using Claude Code. This integration enabl
 - **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
+- **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
 
 ## Architecture
 
@@ -45,22 +46,47 @@ Claude Code → TCP Socket (port 9880) → PyMOL Plugin → cmd.* execution
 - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI installed
 - Python 3.10+
 
-### Installation
+### 1. Install claudemol
 
 ```bash
 pip install claudemol
 claudemol setup
 ```
 
-This installs the package and configures PyMOL to auto-load the socket plugin.
+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.
 
-### Start Using It
+### 2. Install the Claude Code plugin
+
+```
+/plugin marketplace add ANaka/claudemol?path=claude-plugin
+/plugin install claudemol-skills
+```
+
+This gives Claude the skills and hooks to work with PyMOL.
+
+### 3. 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.
+Claude will launch PyMOL, connect via socket, and load the structure.
+
+### Optional: Seamless permissions
+
+By default, Claude asks for approval before running each command. To auto-approve PyMOL-related commands, add to your project's `.claude/settings.json`:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Bash(claudemol*)",
+      "Bash(*python*claudemol*)",
+      "Bash(pymol*)"
+    ]
+  }
+}
+```
 
 ## Usage
 
@@ -72,15 +98,15 @@ Simply ask Claude to open PyMOL or load a structure:
 - "Load PDB 4HHB and show as cartoon"
 - "Fetch 1UBQ from the PDB"
 
-Claude will launch PyMOL if it's not already running.
+Claude connects to an existing PyMOL if one is running, or launches a new instance.
 
 ### Example Commands
 
 - "Color the protein by secondary structure"
-- "Show the binding site residues within 5Å of the ligand as sticks"
+- "Show the binding site residues within 5A 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"
+- "Make a 360 degree rotation movie"
 
 ### PyMOL Console Commands
 
@@ -94,7 +120,7 @@ claude_start    # Start the listener
 
 ### Available Skills
 
-Claude Code has built-in skills for common workflows:
+The plugin includes skills for common workflows:
 
 - **pymol-fundamentals** - Basic visualization, selections, coloring
 - **protein-structure-basics** - Secondary structure, B-factor, representations
@@ -104,6 +130,19 @@ Claude Code has built-in skills for common workflows:
 - **publication-figures** - High-quality figure export
 - **movie-creation** - Animations and rotations
 
+## How It Works
+
+### Connection Lifecycle
+
+1. On session start, a hook runs `claudemol status` to check if PyMOL is reachable
+2. When you ask Claude to work with PyMOL, it uses `connect_or_launch()` — connecting to an existing instance or starting a new one
+3. Commands are sent as Python code over TCP and executed inside PyMOL via the socket plugin
+4. If the connection drops, `conn.execute()` auto-reconnects (up to 3 attempts)
+
+### Venv Support
+
+`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.
+
 ## Troubleshooting
 
 ### Connection Issues
@@ -117,18 +156,30 @@ Claude Code has built-in skills for common workflows:
 - Run `claudemol setup` to configure PyMOL
 - Check PyMOL's output for any error messages on startup
 
+### claudemol Not Found
+
+If Claude reports `ModuleNotFoundError`, claudemol may be installed in a venv that isn't active. Fix:
+
+```bash
+# Re-run setup from the venv that has claudemol
+.venv/bin/claudemol setup
+```
+
+This updates `~/.claudemol/config.json` so future sessions find it.
+
 ### First-Time Setup Help
 
-Run the `/pymol-setup` skill in Claude Code for guided setup assistance.
+Run `/pymol-setup` 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.
+The default socket port is **9880**. Both the plugin and connection module use this port.
 
 Key files:
-- `src/claudemol/plugin.py` - PyMOL plugin (auto-loads via pymolrc)
+- `~/.pymolrc` - PyMOL startup script (loads the socket plugin)
+- `~/.claudemol/config.json` - Persisted Python path for venv discovery
+- `src/claudemol/plugin.py` - Socket listener plugin (runs inside PyMOL)
 - `src/claudemol/connection.py` - Python module for socket communication
-- `claude-plugin/skills/` - Claude Code skills for PyMOL workflows
 
 ## Limitations
 

{claudemol-0.2.0 → claudemol-0.3.0}/README.md

@@ -8,6 +8,7 @@ Control PyMOL through natural language using Claude Code. This integration enabl
 - **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
+- **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
 
 ## Architecture
 
@@ -23,22 +24,47 @@ Claude Code → TCP Socket (port 9880) → PyMOL Plugin → cmd.* execution
 - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI installed
 - Python 3.10+
 
-### Installation
+### 1. Install claudemol
 
 ```bash
 pip install claudemol
 claudemol setup
 ```
 
-This installs the package and configures PyMOL to auto-load the socket plugin.
+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.
 
-### Start Using It
+### 2. Install the Claude Code plugin
+
+```
+/plugin marketplace add ANaka/claudemol?path=claude-plugin
+/plugin install claudemol-skills
+```
+
+This gives Claude the skills and hooks to work with PyMOL.
+
+### 3. 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.
+Claude will launch PyMOL, connect via socket, and load the structure.
+
+### Optional: Seamless permissions
+
+By default, Claude asks for approval before running each command. To auto-approve PyMOL-related commands, add to your project's `.claude/settings.json`:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Bash(claudemol*)",
+      "Bash(*python*claudemol*)",
+      "Bash(pymol*)"
+    ]
+  }
+}
+```
 
 ## Usage
 
@@ -50,15 +76,15 @@ Simply ask Claude to open PyMOL or load a structure:
 - "Load PDB 4HHB and show as cartoon"
 - "Fetch 1UBQ from the PDB"
 
-Claude will launch PyMOL if it's not already running.
+Claude connects to an existing PyMOL if one is running, or launches a new instance.
 
 ### Example Commands
 
 - "Color the protein by secondary structure"
-- "Show the binding site residues within 5Å of the ligand as sticks"
+- "Show the binding site residues within 5A 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"
+- "Make a 360 degree rotation movie"
 
 ### PyMOL Console Commands
 
@@ -72,7 +98,7 @@ claude_start    # Start the listener
 
 ### Available Skills
 
-Claude Code has built-in skills for common workflows:
+The plugin includes skills for common workflows:
 
 - **pymol-fundamentals** - Basic visualization, selections, coloring
 - **protein-structure-basics** - Secondary structure, B-factor, representations
@@ -82,6 +108,19 @@ Claude Code has built-in skills for common workflows:
 - **publication-figures** - High-quality figure export
 - **movie-creation** - Animations and rotations
 
+## How It Works
+
+### Connection Lifecycle
+
+1. On session start, a hook runs `claudemol status` to check if PyMOL is reachable
+2. When you ask Claude to work with PyMOL, it uses `connect_or_launch()` — connecting to an existing instance or starting a new one
+3. Commands are sent as Python code over TCP and executed inside PyMOL via the socket plugin
+4. If the connection drops, `conn.execute()` auto-reconnects (up to 3 attempts)
+
+### Venv Support
+
+`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.
+
 ## Troubleshooting
 
 ### Connection Issues
@@ -95,18 +134,30 @@ Claude Code has built-in skills for common workflows:
 - Run `claudemol setup` to configure PyMOL
 - Check PyMOL's output for any error messages on startup
 
+### claudemol Not Found
+
+If Claude reports `ModuleNotFoundError`, claudemol may be installed in a venv that isn't active. Fix:
+
+```bash
+# Re-run setup from the venv that has claudemol
+.venv/bin/claudemol setup
+```
+
+This updates `~/.claudemol/config.json` so future sessions find it.
+
 ### First-Time Setup Help
 
-Run the `/pymol-setup` skill in Claude Code for guided setup assistance.
+Run `/pymol-setup` 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.
+The default socket port is **9880**. Both the plugin and connection module use this port.
 
 Key files:
-- `src/claudemol/plugin.py` - PyMOL plugin (auto-loads via pymolrc)
+- `~/.pymolrc` - PyMOL startup script (loads the socket plugin)
+- `~/.claudemol/config.json` - Persisted Python path for venv discovery
+- `src/claudemol/plugin.py` - Socket listener plugin (runs inside PyMOL)
 - `src/claudemol/connection.py` - Python module for socket communication
-- `claude-plugin/skills/` - Claude Code skills for PyMOL workflows
 
 ## Limitations
 

{claudemol-0.2.0 → claudemol-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "claudemol"
-version = "0.2.0"
+version = "0.3.0"
 description = "PyMOL integration for Claude Code - control molecular visualization via natural language"
 readme = "README.md"
 requires-python = ">=3.10"

{claudemol-0.2.0 → claudemol-0.3.0}/src/claudemol/__init__.py

@@ -6,15 +6,18 @@ Connect to PyMOL via socket for AI-assisted molecular visualization.
 
 from claudemol.connection import (
     PyMOLConnection,
+    check_pymol_installed,
     connect_or_launch,
-    launch_pymol,
     find_pymol_command,
-    check_pymol_installed,
+    get_config,
+    get_configured_python,
+    launch_pymol,
+    save_config,
 )
 from claudemol.session import (
     PyMOLSession,
-    get_session,
     ensure_running,
+    get_session,
     stop_pymol,
 )
 
@@ -26,6 +29,9 @@ __all__ = [
     "launch_pymol",
     "find_pymol_command",
     "check_pymol_installed",
+    "get_config",
+    "save_config",
+    "get_configured_python",
     "get_session",
     "ensure_running",
     "stop_pymol",

{claudemol-0.2.0 → claudemol-0.3.0}/src/claudemol/cli.py

@@ -12,10 +12,14 @@ import sys
 from pathlib import Path
 
 from claudemol.connection import (
+    CONFIG_FILE,
     PyMOLConnection,
     check_pymol_installed,
     find_pymol_command,
+    get_config,
+    get_configured_python,
     get_plugin_path,
+    save_config,
 )
 
 
@@ -34,10 +38,13 @@ def setup_pymol():
         if "claudemol" in content or "claude_socket_plugin" in content:
             print("PyMOL already configured for claudemol.")
             print(f"Plugin: {plugin_path}")
+            # Still save config (in case Python path changed)
+            save_config({"python_path": sys.executable})
+            print(f"Saved Python path: {sys.executable}")
             return 0
 
     # Add to .pymolrc
-    run_command = f'\n# claudemol: Claude Code integration\nrun {plugin_path}\n'
+    run_command = f"\n# claudemol: Claude Code integration\nrun {plugin_path}\n"
 
     if pymolrc_path.exists():
         with open(pymolrc_path, "a") as f:
@@ -58,6 +65,10 @@ def setup_pymol():
         print("  - brew install pymol (macOS)")
         print("  - Download from https://pymol.org")
 
+    # Save Python path for SessionStart hook and skills
+    save_config({"python_path": sys.executable})
+    print(f"Saved Python path: {sys.executable}")
+
     return 0
 
 
@@ -65,6 +76,11 @@ def check_status():
     """Check PyMOL connection status."""
     print("Checking PyMOL status...")
 
+    # Show configured Python if available
+    configured_python = get_configured_python()
+    if configured_python:
+        print(f"Configured Python: {configured_python}")
+
     # Check if PyMOL is installed
     pymol_cmd = find_pymol_command()
     if pymol_cmd:
@@ -125,6 +141,14 @@ def show_info():
     pymol_cmd = find_pymol_command()
     print(f"  PyMOL command: {' '.join(pymol_cmd) if pymol_cmd else 'not found'}")
 
+    print(f"  Config file: {CONFIG_FILE}")
+    config = get_config()
+    if config:
+        for key, value in config.items():
+            print(f"  Config {key}: {value}")
+    else:
+        print("  Config: not set (run 'claudemol setup' to configure)")
+
 
 def main():
     parser = argparse.ArgumentParser(

{claudemol-0.2.0 → claudemol-0.3.0}/src/claudemol/connection.py

@@ -17,6 +17,9 @@ DEFAULT_PORT = 9880
 CONNECT_TIMEOUT = 5.0
 RECV_TIMEOUT = 30.0
 
+CONFIG_DIR = Path.home() / ".claudemol"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+
 # Common PyMOL installation paths
 PYMOL_PATHS = [
     # uv environment (created by /pymol-setup)
@@ -247,3 +250,28 @@ def connect_or_launch(file_path=None):
     process = launch_pymol(file_path=file_path)
     conn.connect()
     return conn, process
+
+
+def get_config():
+    """Read persisted claudemol config."""
+    if CONFIG_FILE.exists():
+        try:
+            return json.loads(CONFIG_FILE.read_text())
+        except (json.JSONDecodeError, OSError):
+            return {}
+    return {}
+
+
+def save_config(config):
+    """Save claudemol config."""
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    CONFIG_FILE.write_text(json.dumps(config, indent=2) + "\n")
+
+
+def get_configured_python():
+    """Get the Python path from persisted config. Returns path string or None."""
+    config = get_config()
+    python_path = config.get("python_path")
+    if python_path and os.path.isfile(python_path) and os.access(python_path, os.X_OK):
+        return python_path
+    return None