Skip to content
OpenReadout

Connect an assistant

OpenReadout is designed for AI agents. An assistant can use it in two ways: through the skill, a Markdown file that tells an agent with a shell how to run the openreadout command, or through the MCP server (openreadout mcp), which offers the same operations as typed tools to clients without a shell, such as Claude Desktop. Both return the same JSON as --json on the command line.

Connect it

In one line. Paste this into your agent’s chat. The agent reads the skill, which tells it how to install and use the program:

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

There is no packaged release yet, so the install script the skill uses won’t work until there is one. Until then, install with cargo yourself, then connect the program with one of the commands below.

The skill, for agents with a shell (Claude Code, Codex, Cursor, Copilot, Gemini CLI):

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

The MCP server:

Terminal window
openreadout mcp --install claude-desktop   # then restart Claude Desktop

The client names are claude (or claude-code), claude-desktop, cursor, codex, vscode, gemini, windsurf, zed, continue and cline. The command adds an entry with the program’s full path to the client’s configuration file, keeps the other servers, backs up the old file next to it, and leaves the file alone if OpenReadout is already in it:

$ openreadout mcp --install cursor
configured openreadout in /home/you/.cursor/mcp.json (previous file saved as /home/you/.cursor/mcp.json.bak.1790920590)

--project writes the project-level file in the current directory instead (such as .mcp.json), and --config <client> prints the entry without writing it.

The Claude Code plugin installs the skill and the MCP server together (the program must be on your PATH):

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

Codex and Gemini CLI have the same kind of package. See Plugins.

What to ask first

Ask in plain words and give the path:

  • “What is in ~/data/plate7.nd2? Channels, pixel size, how many positions?”
  • “Check every file in /mnt/scope/2026-09-21/ and tell me which ones are truncated.”
  • “Show me what stack.lif looks like, all channels, as a maximum projection.”

Why it suits an agent

  • Stable JSON. Every command takes --json, with published schemas. Keys are not renamed or removed without a schema_version bump.
  • Fixed exit codes: 0 ok, 1 error, 2 usage, 3 unknown format, 4 corrupt, 5 I/O, 6 unsupported feature.
  • Errors with a hint that says what to do next (see below).
  • Assurance with each answer: whether files like this one were validated against an independent reader.
  • Pictures: preview draws images, traces, spectra and plates, so the agent can look at the data.
  • Cheap metadata: info reads headers only, and --only returns just the fields asked for.
  • Read-only inputs and no network access.

When an agent asks for an image that does not exist, the error tells it how to recover:

$ openreadout preview mini.nd2 --image 3 --json
{
  "ok": false,
  "schema_version": "1",
  "tool": { "name": "openreadout", "version": "0.1.0" },
  "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
  }
}

How the assistant sees images

openreadout_preview returns a picture as image content, followed by JSON that says what was drawn. Image previews have rulers labelled in full-resolution pixels and a µm scale bar when the pixel size is known, so the assistant can read a feature’s coordinates off the rulers and ask again for just that region. To measure intensities it uses openreadout_stats, not the picture.

Privacy

  • OpenReadout doesn’t connect to the network. Release binaries contain no networking code.
  • OpenReadout doesn’t modify your files. openreadout_export writes a new file, reads it back to check it, then gives it its final name. It replaces an existing output only if you ask it to overwrite.
  • The server runs as you, so it can open any file your user account can read.

The privacy policy has the details.

More

  • AI agents: every client’s configuration file, npm and Docker setups.
  • MCP tools: every tool and its arguments, resources, prompts and errors.