claudemol 0.1.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

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/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(
@@ -138,7 +162,7 @@ Commands:
   info      Show installation info
 
 For Claude Code skills, install the claudemol-skills plugin:
-  /plugin marketplace add ANaka/ai-mol?path=claude-plugin
+  /plugin marketplace add ANaka/claudemol?path=claude-plugin
   /plugin install claudemol-skills
 """,
     )

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)
@@ -195,7 +198,7 @@ def launch_pymol(file_path=None, wait_for_socket=True, timeout=10.0):
     if not pymol_cmd:
         raise RuntimeError(
             "PyMOL not found. Please install PyMOL:\n"
-            "  - Run: ai-mol setup\n"
+            "  - Run: claudemol setup\n"
             "  - Or: pip install pymol-open-source-whl\n"
             "  - Or: brew install pymol (macOS)"
         )
@@ -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/view.py

@@ -4,7 +4,7 @@ Visual feedback helper for PyMOL.
 Provides a simple way to execute commands and save/view the result.
 
 Usage:
-    from ai_mol.view import pymol_view
+    from claudemol.view import pymol_view
 
     # Execute commands and save a snapshot
     path = pymol_view("cmd.fetch('1ubq'); cmd.show('cartoon')", name="ubq_cartoon")
@@ -21,7 +21,7 @@ from pathlib import Path
 
 DEFAULT_HOST = "localhost"
 DEFAULT_PORT = 9880
-SCRATCH_DIR = Path.home() / ".ai-mol" / "scratch"
+SCRATCH_DIR = Path.home() / ".claudemol" / "scratch"
 
 
 def ensure_scratch_dir():

{claudemol-0.1.0.dist-info → claudemol-0.3.0.dist-info}/METADATA

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: claudemol
-Version: 0.1.0
+Version: 0.3.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
+Project-URL: Homepage, https://github.com/ANaka/claudemol
+Project-URL: Repository, https://github.com/ANaka/claudemol
 Author: Alex Naka
 License: MIT
 License-File: LICENSE
@@ -20,18 +20,17 @@ Classifier: Topic :: Scientific/Engineering :: Visualization
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 
-# ai-mol: Control PyMOL with Claude Code
+# claudemol: 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
+- **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
 
@@ -47,32 +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
+```
 
-1. **Clone the repository:**
+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.
 
-   ```bash
-   git clone https://github.com/ANaka/ai-mol
-   cd ai-mol
-   ```
+### 2. Install the Claude Code plugin
 
-2. **Set up the PyMOL plugin:**
+```
+/plugin marketplace add ANaka/claudemol?path=claude-plugin
+/plugin install claudemol-skills
+```
 
-   Add this line to your `~/.pymolrc` (create it if it doesn't exist):
+This gives Claude the skills and hooks to work with PyMOL.
 
-   ```python
-   run /path/to/ai-mol/claude_socket_plugin.py
-   ```
+### 3. Start using it
 
-   Replace `/path/to/ai-mol` with the actual path where you cloned the repository.
+Open Claude Code and say:
 
-3. **Start using it:**
+> "Open PyMOL and load structure 1UBQ"
 
-   Open Claude Code in the `ai-mol` directory and say:
+Claude will launch PyMOL, connect via socket, and load the structure.
 
-   > "Open PyMOL and load structure 1UBQ"
+### Optional: Seamless permissions
 
-   Claude will launch PyMOL (with the socket listener active) and load the structure.
+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
 
@@ -84,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
 
@@ -106,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
@@ -116,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
@@ -126,22 +153,33 @@ Claude Code has built-in skills for common workflows:
 
 ### Plugin Not Loading
 
-- Verify the path in your `~/.pymolrc` is correct
+- Run `claudemol setup` to configure PyMOL
 - Check PyMOL's output for any error messages on startup
-- Try running `run /path/to/claude_socket_plugin.py` manually in PyMOL
+
+### 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:
-- `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
+- `~/.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
 
 ## Limitations
 

claudemol-0.3.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+claudemol/__init__.py,sha256=SaNeozowULmMoX3-9qAlG9sNk--xgkreurxppLkVE4A,744
+claudemol/cli.py,sha256=fF3hfDLZVx5W6LYO2OOoPGnkvTHbQqF1H6FX1pIfMeQ,5850
+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.3.0.dist-info/METADATA,sha256=qv5TatSb0fhnNjx30iqiuvmiyUR6gX_Va6E7IpWdJLY,6593
+claudemol-0.3.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+claudemol-0.3.0.dist-info/entry_points.txt,sha256=zHSqaPcqaXWoGEavppdq_zTrMARmjjrTqLHa5KEBchw,49
+claudemol-0.3.0.dist-info/licenses/LICENSE,sha256=sZWsSm99w9tlHsmCnA7_6KzEAqQaD7nSQlgYesvvWMQ,1075
+claudemol-0.3.0.dist-info/RECORD,,

claudemol-0.1.0.dist-info/RECORD

@@ -1,11 +0,0 @@
-claudemol/__init__.py,sha256=RZDmQTql01kKApSDdMC3qy07Bz71CE1f6vyOJ_l7wHk,618
-claudemol/cli.py,sha256=J6cKHGbkZX_gYAcvMVlN3NXkIEJmMSjAeEL4R7GO-ww,5008
-claudemol/connection.py,sha256=PG-iqqJ8kYUrA9JQieigHNSzjdI-cab6c0SKUpZkxTg,7516
-claudemol/plugin.py,sha256=xRqpd9Ncn2vDZnmZsKHcFrhISJng38FAZv_0Thy-axc,5513
-claudemol/session.py,sha256=BtaIx9UalvnnlmQ1Zr9HFAlvt_0HzrAnT952HPpFG4w,8258
-claudemol/view.py,sha256=-qe4xu_U_AuVtZpgj_XK3GqnUgq_8ClraHpJjFd58lU,4097
-claudemol-0.1.0.dist-info/METADATA,sha256=kTIUkA5cu-dB3N4bC_qfLZidrEGXPEPAukAr6i7aU2o,5104
-claudemol-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-claudemol-0.1.0.dist-info/entry_points.txt,sha256=zHSqaPcqaXWoGEavppdq_zTrMARmjjrTqLHa5KEBchw,49
-claudemol-0.1.0.dist-info/licenses/LICENSE,sha256=sZWsSm99w9tlHsmCnA7_6KzEAqQaD7nSQlgYesvvWMQ,1075
-claudemol-0.1.0.dist-info/RECORD,,