OpenReadout

OpenReadout

OpenReadout is an open-source reader for lab-instrument files, designed for AI agents.

Give AI agents full access to raw data from microscopes, mass spectrometers, cytometers, electrophysiology rigs, and 90+ other instrument file formats — in one command.

Open-source. Single binary. No vendor software. No dependencies. No network access. Works everywhere.

OpenReadout makes data stored in proprietary instrument file formats readable: it pulls out the metadata, images, traces, spectra, and tables as structured JSON and renders previews so your agent can see and understand the data. Every format is validated against real data and independent libraries.

[CI] [Docs] [License: MIT OR Apache-2.0]

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

[Sagittal section of a whole mouse, trichrome stained, decoded from a Zeiss CZI slide scan]

A whole-mouse section from a 3.7 GB Zeiss slide scan: 190,309 × 69,378 pixels at 0.22 µm.

—

Microscopy

—

Spectra, Traces, and Curves

Everything above was decoded by OpenReadout from raw files — no vendor software, no conversion.

For AI Agents — Get Started in One Line

Paste this into your AI agent's chat — it will read the skill file and install everything:

curl -fsSL https://raw.githubusercontent.com/openreadout/openreadout/main/skills/openreadout/SKILL.md

That's it. The skill file tells the agent how to install the binary and how to use every command.

For Humans

Option A — Browser: Open the browser demo and drop a file on it. It runs OpenReadout compiled to WebAssembly inside the page; nothing is uploaded.

Option B — CLI: Install the binary (see Installation), then connect it to your agent:

openreadout self skill --install all      # skill for Claude Code, Codex, Cursor, Copilot, Gemini CLIopenreadout mcp --install claude-desktop  # MCP server for Claude Desktop (or cursor, codex, vscode, ...)

Your agent can now open, check, plot, and convert instrument files on your behalf.

For Developers — See It Live in 30 Seconds

# 1. Install (macOS / Linux; other ways below)curl -fsSL https://raw.githubusercontent.com/openreadout/openreadout/main/scripts/install.sh | sh
# 2. See what is in a file — reads headers only, fast on any sizeopenreadout info cells.lif
# 3. Look at it — writes cells.preview.pngopenreadout preview cells.lif --composite
# 4. Convert it — read back and verified before it is savedopenreadout export cells.lif -o cells.ome.tiff

That's it. The same commands work on a CZI, an ND2, a Thermo RAW, an ABF, or any of the other formats.

[Terminal session: openreadout info describes a Leica LIF file, check reports that a truncated copy is incomplete and exits with code 4, export writes a verified OME-TIFF, analyze peaks lists four peaks in a GC chromatogram, and info --json piped to jq prints the pixel size.]

Quick Start

# 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 chromatogramopenreadout 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 agentsopenreadout info cells.lif --json

{  "ok": true,  "schema_version": "1",  "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" }      }    ]  }}

Why OpenReadout?

What used to take vendor software or a different library for every format:

import czifile, nd2, liffile, pyabf, flowio# ... a different API, metadata layout, and set of quirks for each one ...

Now takes one command, for all of them:

openreadout info any-file --json

What OpenReadout can do:

• Inspect images, channels, traces, spectra, tables, and metadata -- in plain text or structured JSON
• Check files for truncation, missing planes, and damaged structure -- 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 -- every export read back and verified
• 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

The format list has all 96 formats and their known gaps.

Use Cases

For Researchers:

• Open instrument files on any computer, without the acquisition software
• Convert a folder of raw files to OME-Zarr, mzML, or NWB for analysis and sharing
• Verify that files copied off an instrument PC are complete

For AI Agents:

• Answer questions about a file: channels, pixel size, objective, acquisition time, scan count
• Extract metadata, traces, spectra, and tables as JSON
• Run documented analyses (peak areas, IC50s, Cq values) and report the method used

For Core Facilities and Pipelines:

• Index a lab share into searchable Parquet tables with index and search
• Watch instrument directories and flag stalled or damaged acquisitions with watch
• Run in Nextflow, Snakemake, and Galaxy pipelines (integrations/)

Installation

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

# macOS / Linuxcurl -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 — fetches the native binary for your platform)npm install -g openreadout
# Rust toolchaincargo 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 Codeopenreadout mcp --install claude-desktop  # Claude Desktopopenreadout mcp --install codex           # OpenAI Codexopenreadout mcp --install cursor          # Cursoropenreadout mcp --install vscode          # VS Code / Copilotopenreadout mcp --install gemini          # Gemini CLI

Windsurf, Zed, Continue, and Cline are supported too. The server exposes 15 tools (openreadout_info, openreadout_check, openreadout_preview, openreadout_export, openreadout_analyze, ...) over JSON-RPC — no shell access needed.

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-pluginscodex plugin add openreadout@openreadout

The Claude Code plugin, the Gemini CLI extension and the Codex plugin each add the skill and the MCP server. They come from the small openreadout/agent-plugins repository, which each release updates. The server runs the openreadout binary from your PATH, so install it first.

Agent Skill

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

The skill source is in skills/openreadout.

Why your agent will thrive on OpenReadout

• Deterministic JSON output — every command supports --json with published schemas. No regex parsing, no scraping stdout.
• Fixed exit codes — 0 ok, 1 error, 2 usage, 3 unknown format, 4 corrupt file, 5 I/O, 6 unsupported feature. Agents branch on the code, not on the message.
• Self-healing errors — every error carries a hint that says what to do next. Agents self-correct without human intervention.
• Assurance on every answer — each result says whether files like it were validated against an independent reader. Agents know when to double-check.
• Built-in preview renderer — preview writes a PNG the agent can look at. Agents can see the image, trace, or plate they are reasoning about.
• Cheap metadata — info reads headers only, so a 100 GB file costs the same as a small one. --only returns just the fields asked for, saving tokens.
• Safe by default — inputs are opened read-only and nothing connects to the network.

Error Recovery

# Agent asks for an image that does not existopenreadout preview cells.lif --image 3 --json

{  "ok": false,  "error": {    "code": "usage",    "message": "usage error: image 3 not found (file has 1 images)",    "hint": "Indices are zero-based; `openreadout info FILE --json` lists the images, traces (sweep_count, sample_count), tables (row_count) and spectra the file holds.",    "exit_code": 2  }}

The agent follows the hint, lists the images, and picks the right index.

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

R — the R package returns arrays and data frames. See the R guide.

Comparison

Validation

Readers are tested against about 1,500 public instrument files. Each file's geometry, metadata, and plane hashes are compared with independent libraries (czifile, nd2, liffile, Bio-Formats, FlowIO, pyABF, and others), and pixel data must match exactly. See Validation.

Every reader was written from public files and permissively licensed documentation — no vendor SDKs, headers, DLLs, or GPL source code. See the clean-room policy.

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
• Guides: AI agents | Python | R | Recipes | Batch tables
• A file that does not work: run openreadout check --report FILE and attach the bundle to a new-variant issue. It 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.

Images and demo files come from the public test corpus (corpus/manifest.toml), used under their licences: mouse section, Zeiss sample images for Bio-Formats (Zenodo 10577621, CC-BY-4.0); Convallaria lambda scan, Maria Manuela Azevedo (Zenodo 14976703, CC-BY-4.0); BaTiO3 STEM, Rama Vasudevan and Gerd Duscher (Zenodo 8190744, CC-BY-4.0); H&E QPTIFF, PerkinElmer via the OME sample images (CC-BY-4.0); qPCR, the RDML R package (MIT); MS2, ProteoWizard test data (Apache-2.0); HPLC, cheminfo (MIT); EPR, EasySpin (MIT); patch clamp, pyABF (MIT); GC-FID, entab (MIT); terminal demo, Allen Institute for Cell Science (BSD-3-Clause). demo.tape regenerates the demo.

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