protein-inspect

protein-inspect

A Claude Code plugin that turns any PDB ID, mmCIF/PDB file, or AlphaFold model into a layered semantic representation Claude can reason over fluently — summary.yaml describing fold, ligands, cofactors, interfaces, and predicted-confidence regions, plus a labeled grid of PyMOL views composed into a single image.

Example: protein-inspect 1mbn --render-views — myoglobin with a HEM cofactor closeup, hydrophobic surface, and overview panels.

What it does

Three layers wired together:

1. Feature extraction (gemmi + biotite) — chains, sequence, secondary structure, disulfides, ligands (classified into cofactors / metals / glycans / nucleotides / cryoprotectants / artifacts via a curated table), nucleic-acid chains, peptide ligands, oligomeric state, interface residues, B-factor or pLDDT statistics depending on whether the input is crystal or computed.
2. A codified decision tree (skills/protein-inspect/decision_tree.yaml) — small interpretable rules that fire on the extracted features. "If multi-chain and asymmetric ligand occupancy → flag for inspection." "If method == AlphaFold → emit pLDDT bands and warn the LLM not to confuse it with B-factor." "If 3 aromatics within 5 Å of a small-molecule ligand → aromatic cage detected (nicotinic-receptor-like)." Roughly 35 rules at v0.1.
3. A canonical PyMOL view battery (skills/protein-inspect/view_battery.yaml) — 13+ views fired conditionally: overview top/side, pLDDT or B-factor colored cartoon, hydrophobic surface, metal closeup with coordinating residues + distances, ligand pocket closeup with measured H-bond distances, cofactor closeup, glycan closeup, nucleic-acid interface, peptide-ligand interface, interface views, vicinal-SS zooms. Composed into a single labeled montage to bypass the Claude Code CLI's 3-image attachment cap.

Output: <entry>/summary.yaml + <entry>/views/*.png + <entry>/montage.png. Raw coordinates stay on disk and are referenced by path; the LLM-facing layer is structured text and a single composed image.

Why

Raw PDB/mmCIF text is hostile to LLM reasoning: token-inefficient, no metric closeness, fixed-column formatting. This plugin produces ~10× denser per-token information by operating at the residue / motif / pocket level and externalizing coordinates to a path the LLM doesn't have to read.

The decision tree is hand-curated structural-biology knowledge — the equivalent of a junior biologist's checklist when first looking at a new structure — encoded in YAML so it's versionable, testable, and inspectable, rather than buried in a model's prior.

Install

There are two ways to install. The first is what you almost certainly want.

Path 1 — as a Claude Code plugin (recommended)

From inside a Claude Code session:

/plugin marketplace add https://github.com/LBM-EPFL/protein-inspect
/plugin install protein-inspect@protein-inspect-marketplace

This registers the /protein-inspect slash command, loads SKILL.md so Claude automatically knows when to invoke it ("look at this PDB", "what's in this structure", etc.) and how to interpret its YAML output, and installs the Python package + CLI behind the scenes. After this, any future Claude Code session — in any directory — can act on a structure with a one-line ask.

Path 2 — as a standalone CLI

If you want the tool outside Claude (in scripts, notebooks, CI):

uv tool install git+https://github.com/LBM-EPFL/protein-inspect

This puts protein-inspect on your $PATH. Claude in any session can still call it via Bash, but without the skill registered it won't automatically know to render views or how to read the output — you'll need to explain that yourself.

Dependencies

PyMOL (required for --render-views), and optionally Merizo for ML-based domain segmentation.

Quick start

# A deposited crystal structure
uv run protein-inspect 1mbn --render-views --out 1mbn/

# A local file (mmCIF or PDB)
uv run protein-inspect /path/design.cif --render-views --out design/

# An AlphaFold model (downloaded from AF-DB)
uv run protein-inspect AF-P00533-F1.cif --render-views --out egfr/

# Highlight a specific motif
uv run protein-inspect 1kxj --motif His153,Asp166,Ser142 --render-views

Outputs land under <out>/:

<entry>/
├── 1mbn.cif              # coords (copied / fetched)
├── summary.yaml          # the LLM-facing semantic layer
├── montage.png           # single labeled grid of all views
└── views/                # individual view PNGs (1200×900)
    ├── 01_top.png
    ├── 02_side.png
    ├── 03_bfactor_chain_A.png
    ├── 04_surface_hydrophobic.png
    ├── 05_pocket_HEM_A.png
    └── ...