What is co-pymol AGENTS.md?

Contributor instructions for co-pymol, a PyMOL plugin that lets AI clients control PyMOL's molecular-visualisation commands through an MCP server.

Use them when developing or installing co-pymol, connecting an MCP client to PyMOL, or working with its structure-analysis metrics.

They document the plugin's architecture, installation scenarios and thread-safety rules for safe development and use.

How soo-jeongkim/co-pymol configures Codex and OpenCode

Reuse

Borrowing it

Nothing to install: this file belongs to soo-jeongkim/co-pymol. Take a copy, put it at the same path in your own repository, and replace the rules that are about this project with yours.

Copy the file

curl -O https://raw.githubusercontent.com/soo-jeongkim/co-pymol/main/AGENTS.md

Clone the repo

git clone --depth 1 https://github.com/soo-jeongkim/co-pymol

Made for: Codex, OpenCode.

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

README.md

[![agentmods](https://agentmods.dev/badge/instructions/soo-jeongkim/co-pymol/agents-md/github.svg)](https://agentmods.dev/instructions/soo-jeongkim/co-pymol/agents-md)

Your own site

<a href="https://agentmods.dev/instructions/soo-jeongkim/co-pymol/agents-md"><img src="https://agentmods.dev/badge/instructions/soo-jeongkim/co-pymol/agents-md/github.svg" alt="Measured on agentmods" height="20"></a>

Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.

Your own site · 80×15

<a href="https://agentmods.dev/instructions/soo-jeongkim/co-pymol/agents-md"><img src="https://agentmods.dev/badge/instructions/soo-jeongkim/co-pymol/agents-md.svg" alt="Reviewed on agentmods" width="80" height="20"></a>

Per session 3,921 This file is loaded in full into every session.

When invoked 3,921 The same file — it is already loaded in full.

Security scan A 1 finding. A grade says what 26 rules found in the file — not that it is safe.

Origin original No closer match found in the catalogue.

Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

Model	Per session	Once invoked
Fable 5.1	$0.03921	$0.03921
Opus 5	$0.01961	$0.01961
Sonnet 5	$0.00784	$0.00784
Haiku 4.5	$0.00392	$0.00392

Measured 11d ago against content hash 48b402f357be, method: parsed. Prices are Anthropic first-party input rates as of 2026-09-10, from the pricing page.

Security

Grade A, and why

co-pymol AGENTS.md scanned grade A with 1 finding against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 11d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Makes network callslowCapability

Not a fault in itself. Listed so you know the mod talks to something, and to what.

curl -sN --max-time 2 http://127.0.0.1:8766/sse 2>/dev/null \

AGENTS.md · 277 lines

How it starts

The opening of the file, as written. The whole thing — 277 lines — stays where its author put it; the contents beside it link to each section on GitHub.

AGENTS.md

Instructions for coding agents (Claude Code, Codex, Cursor, etc.) working with co-pymol.

What co-pymol is: a PyMOL plugin that starts an MCP server inside PyMOL's own Python process, exposing the pymol.cmd API (plus a gemmi-backed metrics layer for pLDDT/ipTM/pTM/PAE) as tools. Once installed, an MCP client like Codex, Claude Code, or Cursor can drive PyMOL in natural language.

Two scenarios — jump to whichever fits:

You're editing this repo → see §1 Working on this repo.
You're helping a user install co-pymol on their machine → see §2 Installing co-pymol on a user's machine.

1. Working on this repo

Architecture

Plugin runs inside PyMOL's process. On startup (__init_plugin__), an MCP server launches in a daemon background thread on port 8766.
MCP server (src/co_pymol/server.py) exposes PyMOL's cmd module as MCP tools at http://localhost:8766/sse. MCP clients normally launch the bundled stdio proxy, which forwards to that endpoint and survives PyMOL restarts.
Metrics (src/co_pymol/core/metrics.py) uses gemmi for structure metadata extraction — not PyMOL. This keeps metric parsing clean and avoids polluting PyMOL's object state. Reads PAE/ipTM/pTM from _ma_qa_metric_* categories in mmCIF first, falls back to sibling JSON.
Triage (src/co_pymol/core/triage.py) manages navigation/flagging state for reviewing batches of structures (mobile eval workflow).

Layers

The package uses a src-layout: it lives at src/co_pymol/. Inside it:

package root (__init__.py, cli.py, server.py) — entry points; constants.py holds shared constants (port, palette, etc.); instructions.py loads MCP_INSTRUCTIONS from the sibling instructions.md. No domain logic.
core/ — domain logic + state, no MCP: session.py (per-session state), metrics.py and triage.py (pure, no PyMOL). triage_view.py is the one exception — it drives PyMOL to render a focused structure (triage_render); the pure triage state stays in triage.py. session depends on metrics/triage.
utils/pymol/ — cross-cutting PyMOL primitives: helper.py (ensure_pymol, pymol_lock) and render.py (render_image, apply_plddt_palette).
tools/ — thin MCP wrappers, one register_*_tools(mcp) per file; no logic beyond marshalling to core/ and utils/.

Read the full file on GitHub · 277 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

11d ago First seen · 277 lines · 3,921 tokens per session scan A 48b402f357be

Subscribe to this mod's changes

co-pymol AGENTS.md is an instructions file published in the GitHub repository soo-jeongkim/co-pymol (44 stars, last pushed 22d ago), licensed MIT. It adds 3,921 tokens to every session, about $0.0196 per session on Opus 5. A static security scan graded it A with 1 finding (makes network calls). No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.

Building agents Scientific

next.js AGENTS.md

AGENTS.md instructions for vercel/next.js, covering next.js development guide, codebase structure, monorepo overview, core package: packages/next and other important packages.

vercel/next.js · 7,296 tokens

codex AGENTS.md

AGENTS.md instructions for openai/codex, covering rust/codex-rs, the codex-core crate, code review rules, crate api surface and model visible context.

openai/codex · 5,153 tokens

vscode buildNext.instructions.md

Working notes and architecture documentation for the new esbuild-based build system in build/next. Use when making changes to the new build pipeline (transpile/bundle commands, NLS plugin, source-map handling, resource copying, or self-hosting watch tasks).

microsoft/vscode · 6,785 tokens

co-pymol: Instructions file for Codex