Explore Chimerax

Rebuild Index (version update only)

uv run ${SKILL_ROOT}/build_doc_index.py \
  ${SKILL_ROOT}/assets/docs \
  <VERSION> \
  ${SKILL_ROOT}/assets/chimerax-<VERSION>.index.json

Index & Docs Paths

DOC_INDEX="${SKILL_ROOT}/assets/chimerax-1.9.index.json"
DOC_ROOT="${SKILL_ROOT}/assets/docs"

Primary Workflow: Index-Based Lookup

1. Find the command

# Exact command lookup
jq '.commands["color"]' "$DOC_INDEX"

# Search by partial name
jq -r '.commands | to_entries[] | select(.key | test("surf")) | .key' "$DOC_INDEX"

# Search by keyword (returns doc paths)
jq '.keywords["distance"]' "$DOC_INDEX"

# List all command names
jq -r '.commands | keys[]' "$DOC_INDEX"

2. Read full documentation

Once you have the command name, read its HTML doc:

# Get the relative path
jq -r '.commands["color"].path' "$DOC_INDEX"
# -> user/commands/color.html

# Read the full doc
Read ${SKILL_ROOT}/assets/docs/user/commands/color.html

3. Extract command syntax

From the docs, extract:

• Command name and aliases
• Required arguments
• Optional arguments
• Atom specification syntax
• Examples

Find tutorials

jq -r '.tutorials | keys[]' "$DOC_INDEX"
jq '.tutorials["tutorial_command"]' "$DOC_INDEX"

Find API modules

jq -r '.modules | keys[]' "$DOC_INDEX"
jq '.modules["atomic"]' "$DOC_INDEX"

Search by keyword

# Find all docs mentioning "surface"
jq '.keywords["surface"]' "$DOC_INDEX"

# Search keywords by partial match
jq '.keywords | to_entries[] | select(.key | test("dist"))' "$DOC_INDEX"

Error Resolution Flow

When a ChimeraX command fails:

Step 1: Get built-in help

chimerax_run("help <command>")

Step 2: Search the index

# Find the command in the index
jq '.commands["<command>"]' "$DOC_INDEX"

# Search by keyword if command name is unclear
jq '.keywords | to_entries[] | select(.key | test("<keyword>")) | {key: .key, paths: .value}' "$DOC_INDEX"

Step 3: Read the documentation

Read ${SKILL_ROOT}/assets/docs/<path-from-index>

Step 4: Find related commands

# Related commands often share keywords
jq '.keywords["<keyword>"]' "$DOC_INDEX"

Comprehensive Exploration Flow

When exploring what ChimeraX can do:

By category

# All commands with their titles
jq -r '.commands | to_entries[] | "\(.key): \(.value.title)"' "$DOC_INDEX"

# Filter by keyword category
jq -r '.keywords["surface"][]' "$DOC_INDEX"
jq -r '.keywords["align"][]' "$DOC_INDEX"
jq -r '.keywords["color"][]' "$DOC_INDEX"

By functionality

Command Categories

Structure Loading

Visualization

Selection & Specification

Analysis

Camera & View

Atom Specification Syntax

ChimeraX uses hierarchical atom specification:

#model/chain:residue@atom

Examples:

• #1 - Model 1
• #1/A - Chain A of model 1
• #1/A:10-20 - Residues 10-20 of chain A
• #1/A:10@CA - CA atom of residue 10
• protein - All protein atoms
• ligand - All ligand atoms
• solvent - All solvent atoms

Reference: ${SKILL_ROOT}/assets/docs/user/commands/atomspec.html

MCP Operation Guide

When operating ChimeraX via MCP:

Format commands correctly

Commands should be valid ChimeraX command-line syntax:

open 1abc
color protein cornflowerblue
surface protein

Chain commands

Multiple commands can be separated by ;:

open 1abc; color protein gold; surface

Handle errors

Check command output for errors. Common issues:

• Invalid atom specification -> check atomspec syntax above
• Unknown command -> search index for correct name
• Missing model -> verify model number with models tool

Common Tasks

Open and visualize a PDB

open 1abc
color protein bychain
cartoon
surface protein transparency 0.5

Highlight binding site

select :LIG
select zone :LIG 5 protein
color sel red
surface sel

Measure distance

measure distance #1/A:10@CA #1/A:20@CA

Save image

save image.png width 1920 height 1080 supersample 4

Usage

/explore-chimerax                      # Interactive - describe what you want
/explore-chimerax color protein        # Find coloring commands
/explore-chimerax measure distance     # Find measurement commands
/explore-chimerax open pdb             # File loading