OpenReadout

OpenReadout

OpenReadout lets AI agents read and analyze raw files from lab instruments like microscopes, mass specs, flow cytometers, plate readers and NMR. It reads 120+ formats without vendor software, and runs as an MCP server, a CLI, or a Python or R package.

🧪 Try it: browser demo | 📖 Docs: openreadout.github.io/openreadout

Gallery

Light Microscopy

Leica LIF · fly egg chamber DeltaVision · HeLa cells Imaris · plant root section

Imaris · a single neuron Yokogawa CellVoyager · Cell Painting Evident OIR · testes, confocal

Electron Microscopy

EMDB MRC · virus capsid Gatan DM3 · atoms by ptychography Gatan DM4 · ZnO nanorods

Gatan DM4 · electron diffraction Velox EMD · STEM HAADF FEI SER · silica particles

Figures

ABI .ab1 · Sanger read WITec · Raman of graphene MicroCal ITC · titration

BD FCS + FlowJo · gated T cells SoftMax .pda · 96 growth curves Bruker TopSpin · NMR from the FID

Bruker EPR · power series ABI .fsa · fragment sizing mzML · TIC and spectrum

Axon ABF · firing against current Gamry · cyclic voltammogram Applied Biosystems .eds · qPCR

All read from the raw files. More in the gallery, and image credits in CREDITS.md.

Get Started

Install it, then connect it to your agent:

brew install openreadout/tap/openreadout    # other ways under Installation below
openreadout mcp --install claude-desktop    # or claude, codex, cursor, vscode, gemini

Then ask your agent about a file, like "What's in cells.czi?" In Claude Code you can install it as a plugin instead (see AI Integration).

Or try the browser demo with no install. Your files never leave your computer.

With an Agent

Claude finds the cerebellum in a 3.7 GB slide scan and labels its layers.

https://github.com/user-attachments/assets/7ee0f9fe-e6e0-4378-a46d-5cdc04d57151

Data: Zenodo 10577621 (CC BY 4.0).

Claude checks a gene knockout with files from five instruments.

https://github.com/user-attachments/assets/658d300b-dc9d-4164-af84-bb48261fd33f

Data: Edyanto et al., figshare (CC BY 4.0).

What It Does

• Inspect images, channels, traces, spectra, tables, and metadata, in plain text or structured JSON
• Check files for truncation, missing planes, and damaged structure, with exit code 4 when a file is corrupt
• Export to OME-TIFF, OME-Zarr, mzML, NWB, CSV, Parquet, Arrow, JCAMP-DX, Allotrope ASM, and RDML, reading every export back to verify it
• Preview image planes, traces, spectra, and plate heat maps as PNG
• Analyze chromatographic peaks, plate assays (IC50, standard curves), qPCR (Cq, ΔΔCq), NMR peaks, patch-clamp features, spikes, and flow-cytometry gates, with documented methods
• Batch over whole directories, index lab shares, and watch running acquisitions

On the Command Line

# Install (macOS / Linux; other ways under Installation)
curl -fsSL https://raw.githubusercontent.com/openreadout/openreadout/main/scripts/install.sh | sh

# What is in the file?
openreadout info cells.lif
# → format: Leica LIF (lif) v2  size: 16.0 MiB  images: 1  planes: 2
# →   [0] PEI_laminin_35k  2048x2048 z=1 c=2 t=1  uint16  px=0.3250 µm
# →       objective: HC PL FLUOTAR L 20x/0.40 DRY

# Is it complete?
openreadout check partial-copy.lif
# → error  truncated       block chain runs past end of file
# → error  missing_planes  geometry needs 16777216 bytes but only 8969789 are stored

# Integrate the peaks of a chromatogram
openreadout analyze peaks gc-run.ch --min-height 1
# → 4 peaks, area in pA·min
# → 1   4.852 min  area 0.2779  25.08 %
# → ...

# Structured JSON for scripts and agents
openreadout info cells.lif --json

{
  "ok": true,
  "schema_version": "2",
  "data": {
    "format": { "id": "lif", "name": "Leica LIF", "vendor": "Leica Microsystems" },
    "images": [
      {
        "size_x": 2048, "size_y": 2048, "size_c": 2,
        "pixel_type": "uint16",
        "physical_size": { "x": 0.325, "y": 0.325, "unit": "µm" }
      }
    ]
  }
}

Formats

The format list lists every format OpenReadout reads, with its known gaps.

Installation

Ships as a single self-contained binary. No Java, no Python, no vendor DLLs -- nothing else to install.

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/openreadout/openreadout/main/scripts/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/openreadout/openreadout/main/scripts/install.ps1 | iex

# Homebrew (macOS / Linux)
brew install openreadout/tap/openreadout

# npm (all platforms; installs the native binary for your platform as a dependency)
npm install -g openreadout

# Rust toolchain
cargo install openreadout --locked

Docker, Nix, cargo-binstall, and the other channels are on the install page.

Verify installation: openreadout --version

AI Integration

MCP Server

Built-in MCP server — register with one command:

openreadout mcp --install claude          # Claude Code
openreadout mcp --install claude-desktop  # Claude Desktop
openreadout mcp --install codex           # OpenAI Codex
openreadout mcp --install cursor          # Cursor
openreadout mcp --install vscode          # VS Code / Copilot
openreadout mcp --install gemini          # Gemini CLI

Windsurf, Zed, Continue, and Cline are supported too. The server exposes 28 tools (openreadout_info, openreadout_check, openreadout_preview, openreadout_export, openreadout_peaks, ...) over JSON-RPC, so the client doesn't need shell access.

Claude Code Plugin

Installs the MCP server and the skill together:

/plugin marketplace add openreadout/agent-plugins
/plugin install openreadout@openreadout

Gemini CLI Extension

gemini extensions install https://github.com/openreadout/agent-plugins

Codex Plugin

codex plugin marketplace add openreadout/agent-plugins
codex plugin add openreadout@openreadout

Each of these adds the skill and the MCP server from the openreadout/agent-plugins repository. The server runs the openreadout binary from your PATH, so install it first.

Agent Skill

openreadout self skill --install claude   # ~/.claude/skills/openreadout
openreadout self skill --install agents   # ~/.agents/skills/openreadout (Codex, Cursor, Copilot, Gemini CLI)

The skill source is in skills/openreadout.

Built for Agents

• JSON output for every command, with published schemas.
• Fixed exit codes: 0 ok, 1 error, 2 usage, 3 unknown format, 4 corrupt, 5 I/O, 6 unsupported.
• Errors with a hint about what to try next.
• Assurance on every result: whether that kind of file was checked against another reader. --strict refuses anything that wasn't.
• Previews the agent can look at, as PNG.
• Figures from plot: plate grids, dose-response fits, gated dot plots and more, as PNG, SVG or PDF.
• Fast metadata: info reads headers only, so a 100 GB file is as quick as a small one.
• Read-only and offline.

Python and R

Python — pip install openreadout returns metadata as dicts and pixels as NumPy, dask, or xarray arrays, with plugins for bioio and napari. See the Python guide.

import openreadout

with openreadout.File("cells.lif") as f:
    f.images[0]["channels"]     # same keys as `info --json`
    stack = f.to_xarray(0)      # labelled with channel names and µm
    f.preview(composite=True)   # shows itself in Jupyter

openreadout.plot(data={"file": "growth.pda"}, facet="plate").save("plate.pdf")

R — the R package returns arrays and data frames, and draws the same previews and figures. See the R guide.

Comparison

Validation

Each reader is tested against other readers on public instrument files. See how we validate.

The readers were written from public files, published specifications and permissively licensed readers (credited in NOTICE), without vendor SDKs or DLLs. GPL readers such as Bio-Formats are only run as black boxes in tests. See the clean-room policy and the per-format provenance logs.

Documentation

The documentation has guides for every command and format:

• Getting started: Install | Your first file | Reading the JSON output
• Reference: Commands | MCP tools | Formats
• Gallery: previews and figures drawn from public files
• Guides: AI agents | Python | R | Recipes | Batch tables
• A file that does not work: run openreadout report FILE and attach the bundle to a new-variant issue. The bundle contains no data values, sample names, or paths.

Privacy

OpenReadout runs on your computer, makes no network connections and sends no telemetry. See PRIVACY.md.

License

Licensed under either the Apache License 2.0 or the MIT license, at your option. OpenReadout is not affiliated with any instrument vendor; see TRADEMARKS.md.

Bug reports and contributions are welcome on GitHub Issues. See CONTRIBUTING.md, and read the clean-room policy before working on a reader.

Demo files and README images come from the public test corpus (corpus/manifest.toml), used under their licences, and are credited in .github/assets/gallery/CREDITS.md. demo.tape regenerates the terminal demo.

If you find OpenReadout useful, please give it a star on GitHub — it helps others discover the project.