Skip to content
Back to search

spmind

MarketplaceWorks with Claude CodeGitHub

[ICML 2026] Autonomous AI agent for end-to-end spatial proteomics analysis, with SP-Bench for agentic multiplexed-imaging workflows.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tomtommyyuan--spmind/badge.svg)](/listings/tomtommyyuan--spmind)

HTML

<a href="/listings/tomtommyyuan--spmind"><img src="/api/listings/tomtommyyuan--spmind/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- Python ≥ 3.11 - [Claude Code CLI](https://docs.claude.com/en/docs/claude-code) — `npm install -g @anthropic-ai/claude-code` - A container runtime for the imaging tools: **Docker** (local) or **Apptainer/Singularity** (HPC)

Install the package

git clone https://github.com/tomtommyyuan/spmind.git
cd spmind
pip install -e .

(Optional) Install scimap for host-side analysis

The clustering and phenotyping steps run `scimap` **inside the tool containers**, so `scimap` is not required for the core pipeline and is intentionally left out of the package dependencies. If you want `scimap` available in your local environment (e.g. for interactive downstream analysis), install it separately. Its published metadata pins several outdated versions, so install it without dependencies and then add the runtime extras:

pip install scimap --no-deps
pip install combat fast_histogram smart_open requests "gensim>=4.3.2" \
    shapely plotly mpl-scatter-density PhenoGraph "dask[array]" tifffile

Configure your API key

cp .env.example .env
# then edit .env and set ANTHROPIC_API_KEY=...

Or export it directly:

export ANTHROPIC_API_KEY="your-anthropic-api-key"

Pull the tool containers

The analysis tools run inside containers. Pull them once with the helper scripts:

# Linux / Intel Mac
bash scripts/pull_docker_images.sh

# Apple Silicon (ARM64)
bash scripts/pull_docker_images_arm64.sh

# HPC with Apptainer / Singularity
bash scripts/pull_singularity_images.sh

<br>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 18 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "spmind",
  3. "owner": {
  4. "name": "SP-Mind Team",
  5. "url": "https://github.com/tomtommyyuan/spmind"
  6. },
  7. "metadata": {
  8. "description": "SP-Mind: spatial proteomics analysis tools for Claude Code."
  9. },
  10. "plugins": [
  11. {
  12. "name": "spmind",
  13. "source": "./spmind-plugin",
  14. "description": "Spatial proteomics analysis toolchain (MCMICRO pipeline) exposed as MCP tools for Claude Code.",
  15. "version": "1.0.0"
  16. }
  17. ]
  18. }
README.md · README · 270 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <h1 align="center">
  2. 🧬 SP-Mind: An Autonomous Reasoning Agent for Spatial Proteomics (ICML 2026)
  3. </h1>
  4. <p align="center">
  5. <a href="https://arxiv.org/abs/2606.24235" target="_blank"><img src="https://img.shields.io/badge/arXiv-2606.24235-FF6B6B?style=for-the-badge&logo=arxiv&logoColor=white" alt="arXiv"></a>
  6. <a href="https://github.com/tomtommyyuan/spmind"><img src="https://img.shields.io/badge/GitHub-Code-4A90E2?style=for-the-badge&logo=github&logoColor=white" alt="GitHub"></a>
  7. <a href="https://huggingface.co/datasets/tomyuanyucheng/spmind"><img src="https://img.shields.io/badge/HuggingFace-Dataset-FFBF00?style=for-the-badge&logo=huggingface&logoColor=white" alt="HuggingFace Dataset"></a>
  8. </p>
  9. <p align="center">
  10. <video src="https://github.com/user-attachments/assets/bfb34300-3d4f-4960-9d26-89412a211c24" controls muted width="100%"></video>
  11. </p>
  12. <p align="center">
  13. <em>▶ 55-second overview — if the player doesn't load, <a href="https://github.com/tomtommyyuan/spmind/raw/main/assets/spmind_promo_55s_voiceover.mp4">watch the demo video</a>.</em>
  14. </p>
  15. <p align="center">
  16. <img src="assets/spmind_1.png" alt="SP-Mind overview: from raw multiplexed imaging through the agent's skill-guided pipeline to downstream phenotype discovery and benchmark results" width="100%">
  17. </p>
  18. ## Abstract
  19. Spatial proteomics enables single-cell-resolution characterization of protein expression within tissue architecture, playing a critical role in understanding tumor microenvironments and guiding precision medicine. However, current analysis workflows remain fragmented, requiring expert manual orchestration of heterogeneous tools and limiting research scalability and reproducibility. We present SP-Mind, the first autonomous AI agent designed to unify the spatial proteomics analysis pipeline, from raw multiplexed tissue imaging to downstream phenotype discovery. Equipped with expert-curated biological analysis skills and specialized computational tools, SP-Mind converts natural-language queries into end-to-end analytical workflows without task-specific fine-tuning. To rigorously evaluate its capabilities, we introduce SP-Bench, a comprehensive benchmark spanning diverse tissue types, comprising 102 tasks across 18 distinct categories. Through extensive evaluation on SP-Bench and established downstream tasks, SP-Mind achieves state-of-the-art performance compared to existing open-source biomedical agent baselines.
  20. ## Overview
  21. SP-Mind is built on the **Claude Agent SDK** and ships with:
  22. - A reasoning agent that selects tools, writes code, inspects intermediate
  23. results, and iterates in a data-driven loop.
  24. - Wrappers around the standard multiplexed-imaging toolchain (MCMICRO-style),
  25. packaged as containerized tools.
  26. - A curated set of domain **skills** that inject best-practice methodologies for
  27. each analysis stage.
  28. - **SP-Bench**, a benchmark of realistic spatial proteomics task queries, plus
  29. evaluation scripts for cell annotation and quantification.
  30. ### Agent Design
  31. - **MCP-native tools (opt-in).** With `--mcp`, the full toolchain is exposed to
  32. the agent as a [Model Context Protocol](https://modelcontextprotocol.io) server
  33. of typed, schema-validated tools (generated from the tool metadata in
  34. [`spmind/tool/tool_description/`](spmind/tool/tool_description/)), rather than as
  35. free-form code the model has to write. The same server can be installed into
  36. Claude Desktop / Claude Code (see [Use SP-Mind inside Claude](#use-sp-mind-inside-claude)).
  37. Off by default, so the base agent's behavior is unchanged.
  38. - **Sandboxed execution.** An optional `--sandbox` flag installs `PreToolUse`
  39. guardrails that block destructive shell commands before they run — a safety
  40. layer for fully autonomous (`--dangerously-skip-permissions`) runs.
  41. ### Pipeline Capabilities
  42. | Stage | Module | Backend |
  43. |-------|--------|---------|
  44. | Illumination correction | `spmind.tool.basic_illumination` | BaSiC |
  45. | Registration / stitching | `spmind.tool.registration` | ASHLAR |
  46. | Background subtraction | `spmind.tool.background_subtraction` | Backsub |
  47. | TMA dearraying | `spmind.tool.unetcoreograph` | UNetCoreograph |
  48. | Nuclei probability maps | `spmind.tool.segmentation_unmicst` | UnMICST |
  49. | Cell segmentation | `spmind.tool.segmentation_s3segmenter` | S3Segmenter |
  50. | Quantification | `spmind.tool.quantification` | MCQuant |
  51. | Clustering & phenotyping | `spmind.tool.clustering` | Scimap |
  52. | Cell-type annotation | skill-guided LLM reasoning | — |
  53. <br>
  54. ## Installation
  55. ### Prerequisites
  56. - Python ≥ 3.11
  57. - [Claude Code CLI](https://docs.claude.com/en/docs/claude-code) — `npm install -g @anthropic-ai/claude-code`
  58. - A container runtime for the imaging tools: **Docker** (local) or **Apptainer/Singularity** (HPC)
  59. ### Install the package
  60. ```bash
  61. git clone https://github.com/tomtommyyuan/spmind.git
  62. cd spmind
  63. pip install -e .
  64. ```
  65. ### (Optional) Install scimap for host-side analysis
  66. The clustering and phenotyping steps run `scimap` **inside the tool containers**, so
  67. `scimap` is not required for the core pipeline and is intentionally left out of the
  68. package dependencies. If you want `scimap` available in your local environment (e.g.
  69. for interactive downstream analysis), install it separately. Its published metadata
  70. pins several outdated versions, so install it without dependencies and then add the
  71. runtime extras:
  72. ```bash
  73. pip install scimap --no-deps
  74. pip install combat fast_histogram smart_open requests "gensim>=4.3.2" \
  75. shapely plotly mpl-scatter-density PhenoGraph "dask[array]" tifffile
  76. ```
  77. ### Configure your API key
  78. ```bash
  79. cp .env.example .env
  80. # then edit .env and set ANTHROPIC_API_KEY=...
  81. ```
  82. Or export it directly:
  83. ```bash
  84. export ANTHROPIC_API_KEY="your-anthropic-api-key"
  85. ```
  86. ### Pull the tool containers
  87. The analysis tools run inside containers. Pull them once with the helper scripts:
  88. ```bash
  89. # Linux / Intel Mac
  90. bash scripts/pull_docker_images.sh
  91. # Apple Silicon (ARM64)
  92. bash scripts/pull_docker_images_arm64.sh
  93. # HPC with Apptainer / Singularity
  94. bash scripts/pull_singularity_images.sh
  95. ```
  96. <br>
  97. ## Quick Start
  98. ### 1. Interactive CLI
  99. The fastest way to start. Launches an interactive session (like Claude Code):
  100. ```bash
  101. spmind --dangerously-skip-permissions
  102. ```
  103. Or run a single task non-interactively:
  104. ```bash
  105. spmind -p "Perform cell probability mapping + segmentation on 1.ome.tif, save the result to ./output" --dangerously-skip-permissions
  106. ```
  107. Useful flags: `--model claude-sonnet-4-5`, `--path ./data`, `-v` (verbose),
  108. `--mcp` (expose the toolchain as native MCP tools), `--sandbox` (block
  109. destructive shell commands), `--dangerously-skip-permissions` (fully autonomous).
  110. ### 2. Python API
  111. ```python
  112. from spmind.agent import SPMindAgent
  113. agent = SPMindAgent(path="./data", model="claude-sonnet-4-5")
  114. result = agent.go(
  115. "Generate illumination correction profiles for the 10 raw cycles in "
  116. "./data/illumination_input and save the flat-field/dark-field profiles to ./data/illum"
  117. )
  118. print(result)
  119. # Multi-turn: the session is maintained automatically
  120. agent.go("Now stitch and register those cycles into a single mosaic.")
  121. # Start a fresh conversation
  122. agent.reset_session()
  123. ```
  124. For streaming output, use `async for msg in agent.go_stream(prompt): ...`.
  125. ### 3. Script runner
  126. `run_agent.py` runs a single prompt and logs the full trace with a timestamp:
  127. ```bash
  128. python run_agent.py "Segment cells in 1.ome.tif and quantify marker intensities" \
  129. --output-dir ./agent_logs --dangerously-skip-permissions
  130. ```
  131. ### 4. Web interface
  132. ```bash
  133. python gradio_app.py
  134. ```
  135. ### 5. Use SP-Mind inside Claude
  136. Because the toolchain is exposed as an MCP server, you can call the SP-Mind tools
  137. directly from your own **Claude Code** or **Claude Desktop** session. This is a
  138. *local* integration — SP-Mind must be `pip install`-ed and its containers pulled
  139. on your machine, and the tools run locally (nothing is uploaded).
  140. **Option A — add the MCP server directly:**
  141. ```bash
  142. # Claude Code
  143. claude mcp add spmind -- python -m spmind.mcp_stdio
  144. ```
  145. For **Claude Desktop**, add to `claude_desktop_config.json`:
  146. ```json
  147. {
  148. "mcpServers": {
  149. "spmind": { "command": "python", "args": ["-m", "spmind.mcp_stdio"] }
  150. }
  151. }
  152. ```
  153. **Option B — install as a Claude Code plugin** (this repo doubles as a plugin
  154. marketplace):
  155. ```bash
  156. /plugin marketplace add tomtommyyuan/spmind
  157. /plugin install spmind@spmind
  158. ```
  159. Both options expose the same 19 typed tools.
  160. <br>
  161. ## Benchmark & Experiments
  162. - **`benchmark/`** — SP-Bench task queries (`sp_bench.jsonl`) spanning the full
  163. spatial proteomics pipeline across difficulty tiers, plus a generator script.
  164. - **`experiments/`** — reproduction scripts for the three evaluation tracks in
  165. the paper (SP-Bench execution, cell annotation, cell quantification). See
  166. [`experiments/README.md`](experiments/README.md) for full instructions and
  167. dataset download links.
  168. > [!NOTE]
  169. > **Model version.** All experiments reported in the paper were run with
  170. > **Claude Sonnet 4** (`claude-sonnet-4-20250514`). That model has since been
  171. > retired, so for a smooth out-of-the-box experience the codebase now defaults to
  172. > **Claude Sonnet 4.5** (`claude-sonnet-4-5`).
  173. The SP-Bench and cell annotation datasets are hosted on
  174. [Hugging Face](https://huggingface.co/datasets/tomyuanyucheng/spmind):
  175. ```bash
  176. huggingface-cli download tomyuanyucheng/spmind --repo-type dataset --local-dir data
  177. ```
  178. <br>
  179. ## Citation
  180. If you find SP-Mind useful, please cite our paper:
  181. ```bibtex
  182. @InProceedings{pmlr-v306-yuan26b,
  183. title = {{SP}-Mind: An Autonomous Reasoning Agent for Spatial Proteomics Analysis},
  184. author = {Yuan, Yucheng and Ji, Yuanfeng and Li, Zhongxiao and Li, Ruijiang},
  185. booktitle = {Proceedings of the 43rd International Conference on Machine Learning},
  186. pages = {151849--151872},
  187. year = {2026},
  188. volume = {306},
  189. series = {Proceedings of Machine Learning Research},
  190. publisher = {PMLR},
  191. url = {https://proceedings.mlr.press/v306/yuan26b.html}
  192. }
  193. ```
  194. <br>
  195. ## License
  196. SP-Mind is released under the terms of the [LICENSE](LICENSE) file in this
  197. repository. Note that the integrated third-party tools and their container
  198. images may carry their own licenses; review each before commercial use.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.