MoleCode

Represents molecules as explicit graph code so LLMs can read, write and edit chemistry directly instead of reconstructing structure from SMILES strings.

Stars
★ 311
Last updated
5mo ago
License
MIT
Primary language
Python

At a glance

How it runs
Library / SDKAgent plugin / skill
Works with
Universal · cross-platformCodex · Claude Code
Cost
Free software; you pay for model usage
Setup effort
Low · running in minutes
You'll need
Python 3.9+RDKitnetworkxShell / CLILocal filesystem
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.

  1. 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
  2. A computational chemistry team working with Markush patent structures, needing {R1}/{Boc} abbreviation nodes and isomorphism-scored predictions
  3. Teams handling long polymer chains (e.g. Nylon-6) who want repeat units kept explicit with ×n counts instead of exploding with chain length
  4. Engineers building molecule understanding/generation/editing/reasoning tasks on any LLM, reusing molecode.prompts and the OpenAI-compatible client
  5. 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 molecode
  • pip install -e
Environment variables
MOLECODE_API_KEY MOLECODE_BASE_URL MOLECODE_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 molecode

Or 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?\n
mermaid\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.mmd

Examples 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?

Pros
  • 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, …)
Limitations
  • 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?

FollowAgents source review · FARS-2.1
Some gaps
66/ 100 5-point scale 3.3 / 5
Trust 17/29
Reliability 8/14
Adaptability 15/18
Convention 12/18
Effectiveness 10/13
Verifiability 4/8
Why each dimension lost points
Trust17 / 29 · 2.9/5

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.

Reliability8 / 14 · 2.9/5

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.

Adaptability15 / 18 · 4.2/5

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.

Convention12 / 18 · 3.3/5

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.

Effectiveness10 / 13 · 3.8/5

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.

Verifiability4 / 8 · 2.5/5

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.

Risks and how to mitigate them
  • 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.
Evidence confidence: Low Reviewed Nov 22, 2026 Reviewed revision a4df3b04552b
See the full review method →
Maintain this project? Add the FARS badge to your README

The badge shows the current review score and verdict and links back to this page. It refreshes about once an hour after a re-review.

FARS

[![FARS review](https://followagents.com/badge/molecode.svg)](https://followagents.com/en/agents/molecode)
<a href="https://followagents.com/en/agents/molecode"><img src="https://followagents.com/badge/molecode.svg" alt="FARS review"></a>

FAQ

Does it require network access or paid services?
The library works fully offline: conversion, validation, and examples run offline by default. Only actual LLM calls need your own API key (MOLECODE_API_KEY); costs depend on the provider you choose.
Which models and endpoints does it support?
MoleCode is just a representation layer and its prompts are plain strings, so any SDK works. The bundled molecode.llm.LLMClient is a dependency-free OpenAI-compatible client supporting OpenAI, DeepSeek, Azure, Together, vLLM, Ollama and more, with user-supplied key and base_url.
Is the output reliable, or as error-prone as LLMs writing SMILES?
Model-generated Mermaid graphs can be checked via molecode_convert.py validate or mermaid_to_mol with deterministic RDKit validation (formula, atom counts, round-trip), so errors are caught programmatically rather than silently accepted.
How complete is polymer and Markush support?
Polymers support understanding, generation and editing (molecode.polymer, with ×n and TL/TR terminus markers); Markush supports understanding only (molecode.markush, with {R1} abbreviation nodes and an isomorphism comparator) — generation, editing and reasoning are not yet supported.
How do I use it in Claude Code or Codex?
Just clone the repository: Claude Code auto-discovers the Skill at .claude/skills/molecode/, while Codex and other agents read the root AGENTS.md and use the bundled CLI — no MCP server or extra setup required.
Is MoleCode open source?
Yes. The source code is on GitHub (AtomFlow-AI/MoleCode) under the MIT licence.
Is MoleCode safe to use?
FollowAgents' FARS review (Nov 22, 2026) scored MoleCode 17/29 on trust and safety. None of the eight safety controls the review checks for was missing outright.
Is MoleCode still maintained?
Development has slowed: the latest commit on GitHub is from 2026-06-04, within the last six months but not the last 30 days.
Who makes MoleCode?
MoleCode is published on GitHub by the account AtomFlow-AI. FollowAgents has not verified which person or company is behind that account.
What is MoleCode's official website?
The project's GitHub repository lists https://arxiv.org/pdf/2605.16480 as its website. That link is set by the repository owner; the source code itself is on GitHub (AtomFlow-AI/MoleCode).
Was this page helpful?
View on GitHub ↗ Install ↓

Compare agents like this one

The same FARS review applied across the shortlist this agent qualifies for.

Related concepts