ChimeraX command exploration and documentation reference
Reference for ChimeraX commands, documentation lookup, and MCP operation.
For bundle/extension development, use /reference-chimerax-dev.
Local ChimeraX docs are at:
${SKILL_ROOT}/assets/docs/
Structure:
docs/devel/ - Developer documentation (API, bundle development)docs/user/ - User documentation (commands, formats)A JSON index is committed at:
${SKILL_ROOT}/assets/chimerax-1.9.index.json
Current version: 1.9 (149 commands, 13 tutorials, 16 modules)
uv run ${SKILL_ROOT}/build_doc_index.py \
${SKILL_ROOT}/assets/docs \
<VERSION> \
${SKILL_ROOT}/assets/chimerax-<VERSION>.index.json
DOC_INDEX="${SKILL_ROOT}/assets/chimerax-1.9.index.json"
DOC_ROOT="${SKILL_ROOT}/assets/docs"
# 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"
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
From the docs, extract:
jq -r '.tutorials | keys[]' "$DOC_INDEX"
jq '.tutorials["tutorial_command"]' "$DOC_INDEX"
jq -r '.modules | keys[]' "$DOC_INDEX"
jq '.modules["atomic"]' "$DOC_INDEX"
# 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"
When a ChimeraX command fails:
chimerax_run("help <command>")
# 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"
Read ${SKILL_ROOT}/assets/docs/<path-from-index>
# Related commands often share keywords
jq '.keywords["<keyword>"]' "$DOC_INDEX"
When exploring what ChimeraX can do:
# 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"
| Goal | Keywords to search |
|---|---|
| Structure loading | open, fetch, load |
| Visualization | color, surface, cartoon, style |
| Analysis | measure, distance, angle, clash |
| Selection | select, zone, name |
| Export | save, export, image |
| Alignment | align, match, superpose |
| Maps/Density | volume, density, contour |
| Command | Description |
|---|---|
open | Open file or fetch from database |
close | Close models |
save | Save structures/images |
| Command | Description |
|---|---|
color | Color atoms, surfaces, etc. |
style | Set atom/bond style |
cartoon | Cartoon representation |
surface | Generate molecular surface |
hide / show | Hide/show atoms |
transparency | Set transparency |
| Command | Description |
|---|---|
select | Select atoms |
name | Name selections |
| Atom spec | #1/A:10-20@CA syntax |
| Command | Description |
|---|---|
measure | Distances, angles, etc. |
clashes | Find clashes/contacts |
hbonds | Find hydrogen bonds |
contacts | Find contacts |
align | Align structures |
| Command | Description |
|---|---|
view | Set view |
camera | Camera settings |
clip | Clipping planes |
lighting | Lighting settings |
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 10protein - All protein atomsligand - All ligand atomssolvent - All solvent atomsReference: ${SKILL_ROOT}/assets/docs/user/commands/atomspec.html
When operating ChimeraX via MCP:
Commands should be valid ChimeraX command-line syntax:
open 1abc
color protein cornflowerblue
surface protein
Multiple commands can be separated by ;:
open 1abc; color protein gold; surface
Check command output for errors. Common issues:
models toolopen 1abc
color protein bychain
cartoon
surface protein transparency 0.5
select :LIG
select zone :LIG 5 protein
color sel red
surface sel
measure distance #1/A:10@CA #1/A:20@CA
save image.png width 1920 height 1080 supersample 4
/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