MoleCode
Represents molecules as explicit graph code so LLMs can read, write and edit chemistry directly instead of reconstructing structure from SMILES strings.
- Source repo
- AtomFlow-AI/MoleCode
- Stars
- ★ 311
- Last updated
- 5mo ago
- License
- MIT
- Primary language
- Python
- FA score
- 66/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A medicinal chemist who wants Claude Code or Codex to edit molecules at the named atom/bond level (e.g. add a methyl) with deterministic RDKit validation
- Not a fit if
- Teams whose pipelines require plain-string SMILES and cannot switch representations
- Users doing traditional cheminformatics with no LLM in the loop
- Anyone expecting a turnkey hosted app rather than a code library
- Website
- arxiv.org/pdf/2605.16480 ↗ set on GitHub
- Maintenance
- Commits in the last 6 monthslast commit 2026-06-04
- Source review
- 66/100 · Some gaps
What does this agent do, and when should you use it?
MoleCode (AtomFlow-AI/MoleCode, MIT-licensed) is an LLM-native molecular representation: every atom and bond is written as a typed declaration with a persistent identifier and serialized as a Mermaid graph, making topology directly readable, editable and auditable inside the context window. The format converts deterministically and losslessly to and from SMILES/MOL via RDKit, with no learned model involved. One Subgraph→Node→Edge grammar covers three domains: small molecules (molecode.molecule), polymers (molecode.polymer, with explicit repeat units carrying a symbolic ×n count), and Markush structures (molecode.markush, with abbreviation nodes and a graph-isomorphism comparator). It ships as a pip package including molecode.prompts system prompts and an optional OpenAI-compatible LLMClient, plus a Claude Code Agent Skill and an AGENTS.md entrypoint that let coding agents convert, validate and edit graphs through a molecode_convert.py CLI. The paper reports ~76–80% accuracy on novel molecules (vs ~20–42% for SMILES), Markush understanding jumping from 38.1% to 84.0%, and roughly 5× lower total token cost per query.
MoleCode performs lossless bidirectional conversion between SMILES/MOL/polymer-SMILES/Markush and Mermaid graphs (mol_to_mermaid, mermaid_to_mol, polymer_to_mermaid, mermaid_to_psmiles) with deterministic RDKit round-trip validation. The workflow is: convert a molecule → inspect named atoms/bonds → edit the graph → validate (formula, counts, round-trip) → convert back to SMILES. The library also provides system prompts such as MOLECULE_SYSTEM_PROMPT and an optional molecode.llm.LLMClient — a dependency-free, OpenAI-compatible client built on stdlib urllib where you supply your own key and base_url (works with OpenAI, DeepSeek, Azure, vLLM, Ollama, …). The examples/ folder contains eight runnable scripts covering round-trips, atom/formula/ring counting, constrained de novo design, local graph edits (add/delete/substitute), reaction-product prediction, and molecule-image-to-MoleCode OCSR (requires a vision model). As a Claude Code / Codex Agent Skill it works through the .claude/skills/molecode/scripts/molecode_convert.py CLI with doctor, smiles-to-molecode, validate, compare and molecode-to-smiles subcommands.
- A medicinal chemist who wants Claude Code or Codex to edit molecules at the named atom/bond level (e.g. add a methyl) with deterministic RDKit validation
- A computational chemistry team working with Markush patent structures, needing {R1}/{Boc} abbreviation nodes and isomorphism-scored predictions
- Teams handling long polymer chains (e.g. Nylon-6) who want repeat units kept explicit with ×n counts instead of exploding with chain length
- Engineers building molecule understanding/generation/editing/reasoning tasks on any LLM, reusing molecode.prompts and the OpenAI-compatible client
- Researchers doing OCSR, converting molecule images to MoleCode with a vision model and then back to SMILES
Key setup facts
Pulled from the install and usage notes below. The project README has the current values.
- Install / run
pip install molecodepip install -e
- Environment variables
MOLECODE_API_KEYMOLECODE_BASE_URLMOLECODE_MODEL- Runtime
- Python 3.9+
How do you install or deploy this agent?
Install the library from PyPI (pulls in rdkit and networkx):
pip install molecodeOr from source (for the examples, the Agent Skill, and development):
git clone https://github.com/AtomFlow-AI/MoleCode.git
cd MoleCode
pip install -e .Requires Python 3.9+. The pip install gives you molecode.molecule, molecode.polymer, molecode.markush, molecode.prompts and molecode.llm; the runnable examples and Agent Skill live in the repository.
How do you use this agent?
Core round-trip conversion:
from rdkit import Chem
from molecode import mol_to_mermaid, mermaid_to_mol, mol_to_smiles
# SMILES -> MoleCode graph
graph = mol_to_mermaid(Chem.MolFromSmiles("CC(=O)Oc1ccccc1C(=O)O"), name="Aspirin")
print(graph)
# MoleCode graph -> SMILES (lossless round-trip)
assert mol_to_smiles(mermaid_to_mol(graph)) == Chem.CanonSmiles("CC(=O)Oc1ccccc1C(=O)O")Call any LLM (you supply the key and base URL):
from molecode import LLMClient
from molecode.prompts import MOLECULE_SYSTEM_PROMPT
from molecode.molecule import mol_to_mermaid
from rdkit import Chem
client = LLMClient(api_key="sk-...", base_url="https://api.openai.com/v1", model="")
# or set MOLECODE_API_KEY / MOLECODE_BASE_URL / MOLECODE_MODEL and call LLMClient()
graph = mol_to_mermaid(Chem.MolFromSmiles("CC(=O)Oc1ccccc1C(=O)O"), name="Aspirin")
reply = client.chat(f"How many carbons are in this molecule?\nmermaid\n{graph}\n system=MOLECULE_SYSTEM_PROMPT)
print(reply)Use it as an Agent Skill in Claude Code / Codex via the bundled CLI:
python .claude/skills/molecode/scripts/molecode_convert.py doctor
python .claude/skills/molecode/scripts/molecode_convert.py smiles-to-molecode "CCO" --name Ethanol
python .claude/skills/molecode/scripts/molecode_convert.py validate --input edited.mmd
python .claude/skills/molecode/scripts/molecode_convert.py molecode-to-smiles --input edited.mmdExamples in examples/ run offline by default (they print the exact prompt); set MOLECODE_API_KEY to actually call a model.
What are this agent's strengths and limitations?
- Explicit topology: atoms carry persistent IDs and bonds are named edges, so the model never has to rebuild the graph from SMILES syntax
- Lossless deterministic conversion to/from SMILES/MOL via RDKit — output is machine-checkable, not learned
- Documented results: ~76–80% accuracy on novel molecules (SMILES ~20–42%) and roughly 5× lower total token cost
- One grammar spans small molecules, polymers (explicit ×n repeat units) and Markush abbreviation nodes
- Model-agnostic: prompts are plain strings and any OpenAI-compatible endpoint works (OpenAI, DeepSeek, vLLM, Ollama, …)
- Longer input representation; pipelines deeply bound to SMILES strings require format migration
- Actual LLM calls require your own paid API key (MOLECODE_API_KEY); the project ships no model
- Uneven domain coverage: generation/editing/reasoning for polymers and Markush are not yet supported (task table shows several em dashes)
- OCSR (image-to-structure) depends on an external vision model, not a built-in capability
How does this agent compare with similar options?
The README contrasts MoleCode with SMILES point by point: in SMILES topology is implicit and positional, atoms have no identity, editing requires a whole-string rewrite, and validation relies on fragile string parsing; MoleCode offers explicit named nodes and edges, local graph operations (adding a methyl = 1 node + 1 edge), deterministic RDKit round-trip validation, and generalization over structure instead of syntax memorization.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| MoleCode This agent | 66 · Some gaps | Library / SDKFree + model costs | ★ 311 | 5mo ago | Python | Codex · Claude Code |
| Graphicle | 84 · Good | CLIFree + model costs | ★ 620 | 1d ago | Rust | Codex · Claude Code |
| Fable Method – Distilled Agent Workflow | 79 · Good | Agent plugin / skillFree + model costs | ★ 2.3k | 1mo ago | Python | Claude Code |
| Caura | 77 · Good | Self-hosted serviceFreemium | ★ 576 | today | Python | Codex · Claude Code · Claude.ai |
How does FollowAgents rate this agent?
Why each dimension lost points
Least privilege: the skill does local file I/O and conversion only; AGENTS.md says 'do not install packages into the user's environment without asking' and requires scratch-file cleanup; no destructive defaults found — 2. No explicit confirmation step before writing user files or committing edits, so user_confirmation is 1. Data-flow transparency: conversions run locally via the bundled CLI ('do not call an external service for conversion'); LLM calls require a user-supplied key and base_url — clear. Sensitive data: API keys come from env/user input, nothing hard-coded, but no explicit warning about key leakage, not full marks. Dependencies: rdkit/networkx are established with explicit minimum versions; publishing uses PyPI OIDC trusted publishing with minimized workflow permissions — 2; no hash pinning or vulnerability notes. Rollback: only scratch-file hygiene, no versioned recovery — 1. Attribution: clear naming of AtomFlow and the paper — 2.
Self-consistency: README/AGENTS.md/SKILL.md/pyproject agree on install, CLI commands, and layout (minor drift: examples counted as 7 vs 8) — 2. Dependency availability: pip install pulls rdkit/networkx and `doctor` diagnoses the environment — 2. Failure messages: `doctor` exists but the packet does not show actual error/diagnostic text — 1.
Audience and scenarios: well targeted at chemistry researchers and coding agents across small molecules/polymers/Markush and four task families with offline examples — 3. Capability boundaries: SKILL.md states when to fall back to specialized cheminformatics code, and the README table marks unsupported cells, but edge conditions are thin — 2. Trigger precision: the description enumerates concrete trigger tasks and explicitly excludes trivial SMILES edits — 3. Environment fit: Python>=3.9, dual Claude Code/Codex entry points; RDKit install difficulty on some platforms is not discussed — 2.
Information architecture: clean layering (library/examples/docs/skill) with numbered docs — 3. Install notes: PyPI and source paths plus doctor smoke checks — 3. Naming stability: consistent CLI subcommand names, but v0.1.0 with no changelog and one-shot PyPI version policy — 2. Examples and FAQ: rich examples, no FAQ — 2. Known limitations: paper-based comparisons are cited but the repo does not enumerate MoleCode's own limitations beyond one aromaticity caveat — 1. License: full MIT text — 3. Versioning/changelog: no CHANGELOG, only tag-triggered publishing notes — 1. Maintenance responsibility: no CONTRIBUTING, contact, or update commitments, only attribution — 1.
Output usability: validate/compare/doctor and round-trip checks make outputs verifiable; the workflow requires retaining validation evidence — 2. Marginal value: making SMILES topology explicit and enabling local graph edits instead of whole-string rewrites is a genuine, paper-backed improvement — 3. Cost-benefit: the ~5x token-cost claim is a paper result not statically verifiable here, and longer inputs are themselves a cost — 2.
Claim traceability: performance numbers point to the arXiv paper and docs/06-why-it-works.md — 2. Cross-source corroboration: the packet contains no test suite or benchmark data to independently check the paper numbers, so 1. Fact/inference separation: empirical figures are labeled 'empirically (see paper)' and kept distinct from design rationale — 2.
- The paper-reported numbers (~76–80% accuracy, ~5x cost reduction, 38.1%→84.0%) cannot be independently verified from the packet — no test suite or benchmark data is included; run round-trip validation yourself before relying on them.
- This is v0.1.0 from an unverified publisher (AtomFlow-AI) with no CHANGELOG or maintenance commitments; evaluate for production use on your own.
- When using LLMClient, manage your API key yourself (env vars) and avoid leaking it into scratch files or commits.
- RDKit is a heavy install on some platforms; run the `doctor` CLI command first to verify the environment.
FAQ
Does it require network access or paid services?
Which models and endpoints does it support?
Is the output reliable, or as error-prone as LLMs writing SMILES?
How complete is polymer and Markush support?
How do I use it in Claude Code or Codex?
Is MoleCode open source?
Is MoleCode safe to use?
Is MoleCode still maintained?
Who makes MoleCode?
What is MoleCode's official website?
Thanks — we use this to improve the page.