claudemol 0.2.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

claudemol/__init__.py

@@ -6,19 +6,22 @@ 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,
 )
 
-__version__ = "0.1.0"
+__version__ = "0.4.0"
 __all__ = [
     "PyMOLConnection",
     "PyMOLSession",
@@ -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/cli.py

@@ -5,19 +5,46 @@ Usage:
     claudemol setup    # Configure PyMOL to auto-load the socket plugin
     claudemol status   # Check if PyMOL is running and connected
     claudemol test     # Test the connection
+    claudemol info     # Show installation info
+    claudemol launch   # Launch PyMOL or connect to existing instance
+    claudemol exec     # Execute code in PyMOL
 """
 
 import argparse
+import os
+import stat
 import sys
 from pathlib import Path
 
 from claudemol.connection import (
+    CONFIG_FILE,
     PyMOLConnection,
     check_pymol_installed,
+    connect_or_launch,
     find_pymol_command,
+    get_config,
+    get_configured_python,
     get_plugin_path,
+    save_config,
 )
 
+WRAPPER_DIR = Path.home() / ".claudemol" / "bin"
+WRAPPER_PATH = WRAPPER_DIR / "claudemol"
+
+
+def _create_wrapper_script():
+    """Create ~/.claudemol/bin/claudemol shell wrapper with baked Python path."""
+    WRAPPER_DIR.mkdir(parents=True, exist_ok=True)
+    python_path = sys.executable
+    script = f"""#!/bin/bash
+exec "{python_path}" -m claudemol.cli "$@"
+"""
+    WRAPPER_PATH.write_text(script)
+    WRAPPER_PATH.chmod(
+        WRAPPER_PATH.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH
+    )
+    return python_path
+
 
 def setup_pymol():
     """Configure PyMOL to auto-load the socket plugin."""
@@ -34,10 +61,16 @@ 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}")
+            # Create/update wrapper script
+            _create_wrapper_script()
+            print(f"Wrapper script: {WRAPPER_PATH}")
             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 +91,14 @@ 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}")
+
+    # Create wrapper script
+    _create_wrapper_script()
+    print(f"Wrapper script: {WRAPPER_PATH}")
+
     return 0
 
 
@@ -65,6 +106,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,34 +171,121 @@ 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)")
+
+    print(f"  Wrapper script: {WRAPPER_PATH}")
+    print(f"  Wrapper exists: {WRAPPER_PATH.exists()}")
+
+
+def do_launch(args):
+    """Launch PyMOL or connect to existing instance."""
+    file_path = getattr(args, "file", None)
+    try:
+        conn, process = connect_or_launch(file_path=file_path)
+        if process:
+            print(f"Launched PyMOL (pid {process.pid})")
+        else:
+            print("Connected to existing PyMOL instance")
+        conn.disconnect()
+        return 0
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+
+def do_exec(args):
+    """Execute code in PyMOL."""
+    code = getattr(args, "code", None)
+
+    # Read from positional arg or stdin
+    if code:
+        code = code
+    elif not os.isatty(sys.stdin.fileno()):
+        code = sys.stdin.read()
+    else:
+        print(
+            "Error: No code provided. Pass as argument or pipe via stdin.",
+            file=sys.stderr,
+        )
+        print("  claudemol exec \"cmd.fetch('1ubq')\"", file=sys.stderr)
+        print("  echo \"cmd.fetch('1ubq')\" | claudemol exec", file=sys.stderr)
+        return 1
+
+    if not code.strip():
+        print("Error: Empty code.", file=sys.stderr)
+        return 1
+
+    conn = PyMOLConnection()
+    try:
+        conn.connect(timeout=2.0)
+    except ConnectionError:
+        print("Error: Cannot connect to PyMOL. Is it running?", file=sys.stderr)
+        print("  Run: claudemol launch", file=sys.stderr)
+        return 1
+
+    try:
+        result = conn.execute(code)
+        if result:
+            print(result, end="" if result.endswith("\n") else "\n")
+        conn.disconnect()
+        return 0
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        conn.disconnect()
+        return 1
+
 
 def main():
     parser = argparse.ArgumentParser(
         description="claudemol: PyMOL integration for Claude Code",
         formatter_class=argparse.RawDescriptionHelpFormatter,
-        epilog="""
-Commands:
-  setup     Configure PyMOL to auto-load the socket plugin
-  status    Check if PyMOL is running and connected
-  test      Test the connection with a simple command
-  info      Show installation info
-
-For Claude Code skills, install the claudemol-skills plugin:
-  /plugin marketplace add ANaka/claudemol?path=claude-plugin
-  /plugin install claudemol-skills
-""",
     )
-    parser.add_argument(
-        "command",
+
+    subparsers = parser.add_subparsers(dest="command")
+
+    # setup
+    subparsers.add_parser(
+        "setup", help="Configure PyMOL to auto-load the socket plugin"
+    )
+
+    # status
+    subparsers.add_parser("status", help="Check if PyMOL is running and connected")
+
+    # test
+    subparsers.add_parser("test", help="Test the connection with a simple command")
+
+    # info
+    subparsers.add_parser("info", help="Show installation info")
+
+    # launch
+    launch_parser = subparsers.add_parser(
+        "launch", help="Launch PyMOL or connect to existing instance"
+    )
+    launch_parser.add_argument(
+        "file", nargs="?", default=None, help="File to open (e.g., .pdb, .cif)"
+    )
+
+    # exec
+    exec_parser = subparsers.add_parser("exec", help="Execute code in PyMOL")
+    exec_parser.add_argument(
+        "code",
         nargs="?",
-        choices=["setup", "status", "test", "info"],
-        default="info",
-        help="Command to run",
+        default=None,
+        help="Python code to execute (or pipe via stdin)",
     )
 
     args = parser.parse_args()
 
-    if args.command == "setup":
+    if args.command is None:
+        show_info()
+        return 0
+    elif args.command == "setup":
         return setup_pymol()
     elif args.command == "status":
         return check_status()
@@ -161,6 +294,10 @@ For Claude Code skills, install the claudemol-skills plugin:
     elif args.command == "info":
         show_info()
         return 0
+    elif args.command == "launch":
+        return do_launch(args)
+    elif args.command == "exec":
+        return do_exec(args)
 
 
 if __name__ == "__main__":

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

{claudemol-0.2.0.dist-info → claudemol-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claudemol
-Version: 0.2.0
+Version: 0.4.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.4.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+claudemol/__init__.py,sha256=JPTUCYrIbuBw8Om4QKJre3KG0HZg4mcm91HsnSBnqls,744
+claudemol/cli.py,sha256=9gVAY-MfrKFv4me9QKTuHHi_EeJEz54rA2UpRMUBhhY,9175
+claudemol/connection.py,sha256=pJXO5eBXir8NHXohOl5gk3YSE5bv0zggDK9cfnP0hE0,8333
+claudemol/plugin.py,sha256=xRqpd9Ncn2vDZnmZsKHcFrhISJng38FAZv_0Thy-axc,5513
+claudemol/session.py,sha256=BtaIx9UalvnnlmQ1Zr9HFAlvt_0HzrAnT952HPpFG4w,8258
+claudemol/view.py,sha256=k5wzx2jOeYgZKJKNJfk-3Aat3iDvKU-8y9dMAjb4E-A,4103
+claudemol-0.4.0.dist-info/METADATA,sha256=p6E78_QKolJyxD2mXhCeE1mxSd4gQ2J59O9EM73e7V0,6593
+claudemol-0.4.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+claudemol-0.4.0.dist-info/entry_points.txt,sha256=zHSqaPcqaXWoGEavppdq_zTrMARmjjrTqLHa5KEBchw,49
+claudemol-0.4.0.dist-info/licenses/LICENSE,sha256=sZWsSm99w9tlHsmCnA7_6KzEAqQaD7nSQlgYesvvWMQ,1075
+claudemol-0.4.0.dist-info/RECORD,,

claudemol-0.2.0.dist-info/RECORD

@@ -1,11 +0,0 @@
-claudemol/__init__.py,sha256=RZDmQTql01kKApSDdMC3qy07Bz71CE1f6vyOJ_l7wHk,618
-claudemol/cli.py,sha256=YMOWlO5fLsczb-fLztnEj8xhj1M9H6Bog16maw_A7ME,5011
-claudemol/connection.py,sha256=lvHb6wJ2uxKiVxpQU-KXUyWD4R_hkNttw12dO1CcXC0,7519
-claudemol/plugin.py,sha256=xRqpd9Ncn2vDZnmZsKHcFrhISJng38FAZv_0Thy-axc,5513
-claudemol/session.py,sha256=BtaIx9UalvnnlmQ1Zr9HFAlvt_0HzrAnT952HPpFG4w,8258
-claudemol/view.py,sha256=k5wzx2jOeYgZKJKNJfk-3Aat3iDvKU-8y9dMAjb4E-A,4103
-claudemol-0.2.0.dist-info/METADATA,sha256=bomqdT1MfSEAGo5GB-WrXO2tjWTxaPLr5bcRnDguDb8,4686
-claudemol-0.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-claudemol-0.2.0.dist-info/entry_points.txt,sha256=zHSqaPcqaXWoGEavppdq_zTrMARmjjrTqLHa5KEBchw,49
-claudemol-0.2.0.dist-info/licenses/LICENSE,sha256=sZWsSm99w9tlHsmCnA7_6KzEAqQaD7nSQlgYesvvWMQ,1075
-claudemol-0.2.0.dist-info/RECORD,,