{"id":51634242,"url":"https://github.com/fastfold-ai/fastfold-pymol-agent","last_synced_at":"2026-07-13T12:01:53.745Z","repository":{"id":354969180,"uuid":"1226157978","full_name":"fastfold-ai/fastfold-pymol-agent","owner":"fastfold-ai","description":"PyMOL plugin to run Fastfold workflows and analyze structures with an in-app AI agent.","archived":false,"fork":false,"pushed_at":"2026-05-01T06:51:51.000Z","size":4219,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-01T08:27:56.079Z","etag":null,"topics":["ai-agent","anthropic","molecular-dynamics","molecular-visualization","protein-structure","pymol","pymol-plugin"],"latest_commit_sha":null,"homepage":"https://docs.fastfold.ai","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fastfold-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-01T03:24:34.000Z","updated_at":"2026-05-01T06:51:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fastfold-ai/fastfold-pymol-agent","commit_stats":null,"previous_names":["fastfold-ai/fastfold-pymol-agent"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/fastfold-ai/fastfold-pymol-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastfold-ai%2Ffastfold-pymol-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastfold-ai%2Ffastfold-pymol-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastfold-ai%2Ffastfold-pymol-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastfold-ai%2Ffastfold-pymol-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fastfold-ai","download_url":"https://codeload.github.com/fastfold-ai/fastfold-pymol-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastfold-ai%2Ffastfold-pymol-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35421719,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-13T02:00:06.543Z","response_time":119,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","anthropic","molecular-dynamics","molecular-visualization","protein-structure","pymol","pymol-plugin"],"created_at":"2026-07-13T12:01:51.227Z","updated_at":"2026-07-13T12:01:53.735Z","avatar_url":"https://github.com/fastfold-ai.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Fastfold PyMOL Agent\n\nFastfold PyMOL Agent is a PyMOL plugin for biology workflows: run Fastfold skills, bring generated artifacts into PyMOL, and keep iterating with natural-language visualization and analysis.\n\n![Fastfold PyMOL Agent UI](assets/fastfold-ui-demo.png)\n\n- Skill-first workflows: discover and run installed Fastfold skills from chat, then immediately load generated structures and artifacts into PyMOL.\n- PyMOL-native agent UX: multiline chat UI, local file references, streaming responses, and iterative structure edits without leaving PyMOL.\n- Built for reusable skills: add skills as folders and use the same interface for fold jobs, MD workflows, and custom script-backed automations.\n- Official skills catalog: [https://cloud.fastfold.ai/agent/skills](https://cloud.fastfold.ai/agent/skills)\n\n---\n\n## Quick Install\n\nInstall the Fastfold agent and PyMOL open source with our standalone installers \n\n```bash\ncurl -LsSf https://fastfold.ai/pymol-agent/install.sh | sh\n```\n\nIf you already have commercial PyMOL installed, skip to [Commercial PyMOL: plugin zip install](#commercial-pymol-plugin-zip-install).\n\n\u003e Note: when PyMOL Open Source is not already installed, this step can take around 5 minutes.\n\nInstall agent only (skip PyMOL install):\n\n```bash\ncurl -LsSf https://fastfold.ai/pymol-agent/install.sh | sh -s -- --agent-only\n```\n\nOverride conda env name:\n\n```bash\ncurl -LsSf https://fastfold.ai/pymol-agent/install.sh | sh -s -- --env-name myenv\n```\n\nThen launch PyMOL:\n\n```bash\nconda activate myenv\npymol\n```\n\nThis opens the PyMOL UI. Then follow the **First run in PyMOL** section below to configure API keys and launch the agent UI.\n\n```text\nfastfold help\n```\n\n### Commercial PyMOL: plugin zip install\n\nIf you use commercial PyMOL and prefer Plugin Manager installs, install the release zip artifact directly from GitHub Releases.\n\nRecommended release asset URL (always latest):\n\n```text\nhttps://github.com/fastfold-ai/fastfold-pymol-agent/releases/latest/download/fastfold-pymol-agent-plugin.zip\n```\n\nVersion-pinned URL (optional):\n\n```text\nhttps://github.com/fastfold-ai/fastfold-pymol-agent/releases/download/1.0.0/fastfold-pymol-agent-1.0.0-plugin.zip\n```\n\nInstall directly from URL in PyMOL:\n\n1. Open **Plugin \u003e Plugin Manager \u003e Install New Plugin**.\n2. In **Install from PyMOLWiki or any URL**, paste:\n   `https://github.com/fastfold-ai/fastfold-pymol-agent/releases/latest/download/fastfold-pymol-agent-plugin.zip`\n3. Click **Fetch** and confirm install in PyMOL.\n   - Please wait until the install completes. PyMOL may appear unresponsive during this step (PyMOL limitation), because plugin installation runs on the same UI thread.\n4. Open the plugin from the Plugins menu.\n5. In the PyMOL command line, install required Python dependencies once:\n\n```text\nfastfold deps install\n```\n\nOn success, PyMOL shows:\n\n```text\nFastfold Agent: dependencies installed.\nFastfold Agent dependency check:\n  [OK] anthropic\n  [OK] claude-agent-sdk\n\nAll required dependencies are installed.\n```\n\nOptional local-file install:\n\n1. Download the zip from the release URL above.\n2. In **Install from local file**, click **Choose file...** and select the downloaded zip.\n3. Confirm install.\n\n\n\n### Explore Fastfold Apps\n\nAfter install, explore Fastfold Apps to see what the PyMOL Agent can orchestrate across the Fastfold agentic platform.\n\n- Browse the Fastfold Apps catalog: [https://cloud.fastfold.ai/apps](https://cloud.fastfold.ai/apps)\n- Fold model options include: ESM-1b, IntelliFold, OpenFold 3, AlphaFold2, Boltz-1, Boltz-2, Chai-1, and SimpleFold.\n- MD workflow options include: OpenMM Calvados and OpenMMDL.\n- Protein Design workflows coming soon: Boltzgen and Bindcraft.\n\n![Fastfold Apps Catalog](assets/fastfold-apps-overview.png)\n\n### Upgrade an existing install\n\nIf you already installed the plugin and want the latest version from GitHub, run this inside PyMOL:\n\n```text\nfastfold upgrade\n```\n\nThen restart PyMOL to load the updated plugin.\n\n---\n\n## First run in PyMOL\n\nConfigure keys and start the agent:\n\n```text\nfastfold doctor\nfastfold setup anthropic \u003cyour-anthropic-api-key\u003e\nfastfold setup fastfold \u003cyour-fastfold-api-key\u003e\nfastfold ui\n```\n\nWhere to get keys:\n\n- Fastfold API key: [https://cloud.fastfold.ai/api-keys](https://cloud.fastfold.ai/api-keys)\n- Anthropic API key: [https://platform.claude.com/dashboard](https://platform.claude.com/dashboard)\n\n### Model selection\n\nFastfold PyMOL Agent defaults to `claude-haiku-4-5` (fastest profile from the Anthropic model lineup).\n\nTo change the base Anthropic model:\n\n```text\nfastfold config set anthropic_model \u003cmodel-name\u003e\n```\n\nModel validation is enforced: only model IDs/aliases from Anthropic's models overview are accepted.\n\nRecommended model options:\n\n| Feature | Claude Opus 4.7 | Claude Sonnet 4.6 | Claude Haiku 4.5 |\n| --- | --- | --- | --- |\n| Claude API alias | `claude-opus-4-7` | `claude-sonnet-4-6` | `claude-haiku-4-5` |\n| Extended thinking | No | Yes | Yes |\n| Adaptive thinking | Yes | Yes | No |\n| Comparative latency | Moderate | Fast | Fastest |\n\nExamples:\n\n```text\nfastfold config set anthropic_model claude-haiku-4-5\nfastfold config set anthropic_model claude-sonnet-4-6\n```\n\nCheck current settings anytime:\n\n```text\nfastfold config show\n```\n\n---\n\n## Chat UI workflow (recommended)\n\nUse the chat window for long prompts, local file paths, and multi-step workflows:\n\n```text\nfastfold ui\n```\n\n### Combining Fastfold skills + PyMOL edits\n\nUse one request that asks the agent to run a skill workflow and then style/analyze results in PyMOL.\n\nAll submitted jobs are visible in your Fastfold dashboard: [https://cloud.fastfold.ai/jobs](https://cloud.fastfold.ai/jobs).\n\nSimple prompt example:\n\n```text\nUse esm1b in Fastfold to run a fold job.\n\nUse these sequences:\nSequence 1 (protein): MGLSDGEWQLVLNVWGKVEADIPGHGQEVLIRLFKGHPETLERFDKFKHLKSEDEMKASEDLKKHGATVLTALGGILKKKGHHEAEIKPLAQSHATKHKIPVKYLEFISECIIQVLQSKHPGDFGADAQRAMNKALELFRKDMASNYKELGFQG and show the prediction as cartoon colored by secondary structure.\n```\n\nExample (fold -\u003e CIF -\u003e PyMOL):\n\n```text\nUse the fold skill to submit an esm1b job for this sequence, wait for completion, download the CIF, load it into PyMOL as \"esm1b_result\", then color by pLDDT and label low-confidence loops.\n```\n\nExample (MD workflow -\u003e frames/artifacts -\u003e PyMOL):\n\n```text\nUse md-openmmdl to run a short workflow from my topology and ligand files, fetch artifacts, load representative structures in PyMOL, then compare start vs end conformations with cartoons and sticks at the binding site.\n```\n\nExample (artifact refinement loop):\n\n```text\nFrom the latest Fastfold artifact, load structure(s), create publication-style scenes for chain interfaces, and export both a PNG and a PyMOL session file.\n```\n\n### Referencing local files in chat\n\n- Use the **Insert File Path** button in the UI to inject absolute paths.\n- You can also paste paths manually; keep paths quoted if they contain spaces.\n- Ask explicitly what to do with each file (load, align, style, measure, export).\n\nExamples:\n\n```text\nLoad \"/Users/you/data/model.cif\" as object \"pred_cif\", show cartoon, color by chain, and center view.\n```\n\n```text\nLoad \"/Users/you/data/model.pdb\" as \"ref_pdb\", align it to \"pred_cif\", then highlight residues 45-70 as sticks.\n```\n\n```text\nLoad topology \"/Users/you/data/protein.pdb\" as \"traj_top\", load trajectory \"/Users/you/data/run.dcd\", then show RMSD over time and display frame 1 and last frame as cartoons.\n```\n\n### PDB, CIF, and trajectory editing patterns\n\nAfter files are loaded, ask for concrete modifications:\n\n```text\nPDB: show cartoon, color by chain, show ligand as sticks, and add hydrogen-bond distances.\nCIF: map confidence to spectrum colors, select residues with confidence \u003c 70, and make them transparent surface.\nTrajectory: align all frames to chain A, compute RMSD, and generate snapshots for frames 1/50/100.\n```\n\nTip: give object names in your prompt (`as \"obj_name\"`) so follow-up instructions are consistent.\n\n---\n\n## Commands\n\n### Core\n\n```text\nfastfold \u003cprompt\u003e                     ask the agent and auto-execute\nfastfold dry \u003cprompt\u003e                 preview generated commands\nfastfold save [file.py] \u003cprompt\u003e      run prompt and save script\nfastfold save [file.py]               save last generated script\nfastfold undo                         restore scene before last command\nfastfold reset                        clear conversation and undo state\nff \u003c...\u003e                              short alias for fastfold\n```\n\n### Agent mode and GUI\n\n```text\nagent \u003cmessage\u003e                       conversational alias\nfastfold agent on|off|status          toggle/show agent mode\nfastfold ui                           open multiline Fastfold Agent window\n```\n\n### Setup and config\n\n```text\nfastfold setup\nfastfold setup \u003canthropic\u003e \u003cfastfold\u003e\nfastfold setup anthropic \u003ckey\u003e\nfastfold setup fastfold \u003ckey\u003e\nfastfold deps install|check\nfastfold upgrade\nfastfold doctor\n\nfastfold config show\nfastfold config set \u003ckey\u003e \u003cvalue\u003e\nfastfold config set anthropic_model \u003cmodel-name\u003e\n```\n\n### Skills and logs\n\n```text\nfastfold skills list\nfastfold skills show \u003cname\u003e\nfastfold skills howto \u003cname\u003e\nfastfold skills search \u003cquery\u003e\nfastfold skills reload\n\nfastfold log show\nfastfold log save [file.py]\nfastfold log export [file.json]\n```\n\n---\n\n## Skills (drop-in folders)\n\nDefault config file:\n\n```text\n~/.fastfold-pymol-agent.json\n```\n\nDefault skills path:\n\n```text\n~/.fastfold-pymol-agent/skills\n```\n\nMinimum skill layout:\n\n```text\n~/.fastfold-pymol-agent/skills/my-skill/SKILL.md\n```\n\nOptional:\n\n- `scripts/` for helper executables\n- `references/` for docs/schemas\n- `skill.json` for metadata\n\nAfter adding/editing skills:\n\n```text\nfastfold skills reload\n```\n\n---\n\n## Inspired by\n\n- [KodyKlupt/PromptMOL](https://github.com/KodyKlupt/PromptMOL)\n- [colbyford/PyMOLfold](https://github.com/colbyford/PyMOLfold)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffastfold-ai%2Ffastfold-pymol-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffastfold-ai%2Ffastfold-pymol-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffastfold-ai%2Ffastfold-pymol-agent/lists"}