DeckProbe

ffprobe for documents, built for agents.

Ask for the facts you need. Get structured JSON with confidence, evidence, and measured I/O cost.

Install · Quickstart · Runtime role · Agent skill · MCP server · npm package · Execution modes · Examples · Formats · CLI reference

DeckProbe is the probing engine of the DeckFlow Runtime. It performs low-cost preflight inspection and returns structured evidence that callers can use before more expensive parsing, OCR, rendering, uploading, or model ingestion.

Available as a target-driven Rust engine, native CLI, and browser SDK, DeckProbe inspects untrusted PDF, Microsoft Office, and modern Apple iWork documents without rendering them or starting a desktop office suite. Instead of eagerly unpacking everything, it chooses the cheapest probe path that can satisfy the targets and confidence you requested.

$ deckprobe --pretty -t slide_count deck.pptx
{
  "driver": { "id": "powerpoint", "profile": "pptx" },
  "results": {
    "<target>": {
      "status": "resolved",
      "value": 31,
      "confidence": "high",
      "path": "<selected-path>"
    }
  },
  ...
}

User-facing examples use short target names; reports retain stable canonical keys for machine consumers.

Where DeckProbe fits

DeckFlow is the Document Runtime for Agents. Its product model has three engine responsibilities:

DeckProbe can run independently. In a larger Runtime workflow, its report helps the calling agent or application decide whether to parse, render, reject, or use another path. DeckProbe provides the evidence for that decision; it does not automatically choose or execute downstream actions.

DeckProbe is not a general-purpose parser, renderer, OCR engine, editor, or complete security product.

Why DeckProbe

The native CLI needs no Python, JVM, Microsoft Office installation, or external PDF library at runtime. The browser SDK runs the same engine locally through WebAssembly and does not upload document bytes.

Quickstart

Install from source

Requires Rust 1.88 or newer and Git. This builds the CLI on the user's machine and installs it in the Cargo user directory, so it normally does not require administrator privileges:

cargo install --git https://github.com/deckflow/deckprobe --locked deckprobe

Install a prebuilt release

The installers choose the matching CPU and platform archive and install into the Cargo user directory. Installing there does not require administrator privileges. Use an elevated shell only when deliberately installing into a system directory.

macOS (Apple Silicon or Intel)

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/deckflow/deckprobe/releases/latest/download/deckprobe-installer.sh | sh

Linux (x86-64 or ARM64; GNU or musl)

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/deckflow/deckprobe/releases/latest/download/deckprobe-installer.sh | sh

Windows (x86-64, MSVC)

powershell -ExecutionPolicy ByPass -c "irm https://github.com/deckflow/deckprobe/releases/latest/download/deckprobe-installer.ps1 | iex"

If the PowerShell installer updates the user Path, restart the shell before running deckprobe.

Every release contains platform archives, per-archive SHA-256 files, a consolidated checksum file, and GitHub build-provenance attestations. The shell installer verifies its embedded checksum when sha256sum is available. For a manual verification, download the matching archive and checksum from the same GitHub Release and use shasum -a 256 on macOS, sha256sum on Linux, or Get-FileHash -Algorithm SHA256 on Windows.

The checksum protects against accidental corruption and the provenance attestation records how the artifact was built. They are not the same as an OS code signature: this project does not currently publish macOS Developer ID notarization or Windows Authenticode signatures. macOS Gatekeeper or Windows SmartScreen may therefore ask for an explicit confirmation for a downloaded binary. A source-built binary is also not project-signed, but a locally built executable normally does not carry the quarantine marker attached to browser downloads.

The one-line installer commands are a convenience for trusted environments. For a controlled or offline installation, download the installer and archive from the GitHub Release, inspect them locally, verify the checksum and (where required) the build-provenance attestation, then run the installer.

At runtime DeckProbe does not need root or administrator access. It needs execute permission on the binary and read permission on the document being inspected; output is written to standard output. Hardened environments can still impose additional noexec, SELinux/AppArmor, or enterprise execution policies.

See the installation guide for custom install locations, upgrades, and uninstallation.

Verify the installation and probe a file:

deckprobe --version
deckprobe --pretty report.pdf

The default metadata probe returns common metadata plus useful format-specific facts. For a focused query, name one or more targets:

deckprobe --pretty \
  -t format,slide_count \
  deck.pptx

Target options are repeatable and unambiguous short names are resolved after format detection:

deckprobe -l m -t title -t slide_count -p deck.pptx
deckprobe -t @summary,@security --view values deck.pptx

Optional zero-additional-path values and per-target confidence are explicit:

deckprobe -t slide_count -o orientation,aspect_ratio \
  -C slide_count=x deck.pptx

Probe one raw document from stdin by supplying the logical filename used for format routing:

cat report.pdf | deckprobe -n report.pdf -

Process multiple paths or named base64 payloads as JSONL. DeckProbe writes one compact schema-v2 result for each non-empty input line:

printf '%s\n' \
  '{"path":"report.pdf"}' \
  '{"path":"deck.pptx"}' | deckprobe --jsonl -t @summary

Use from a coding agent

DeckProbe ships an Agent Skill that teaches an agent the target vocabulary, the report contract, and the exit-status handling, so it stops guessing flags and stops falling back to unzipping documents by hand.

If you already have the CLI, install the skill for whichever agents this project uses:

deckprobe install --skills                     # every agent present in this project
deckprobe install --skills --agent claude -g   # ~/.claude/skills/deckprobe/
deckprobe install --skills --dry-run --pretty  # preview first

If you do not, install it straight from this repository:

npx skills add deckflow/deckprobe

Claude Code users can instead take it as a plugin:

/plugin marketplace add deckflow/deckprobe
/plugin install deckprobe@deckflow

All three deliver the same bytes from skills/deckprobe/. Note that npx skills add and the plugin install the instructions only — the skill's first step checks for the CLI and falls back to npx -y @deckflow/deckprobe when it is missing. See Installing agent assets for the agent/directory table and the overwrite policy.

MCP server

An agent with no shell — Claude Desktop, an IDE chat pane, a hosted agent — reaches DeckProbe through deckprobe-mcp-server, which serves this engine over MCP as four typed tools: probe, probe_batch, list_formats, and list_targets.

claude mcp add deckprobe -- npx -y @deckflow/deckprobe-mcp

// Claude Desktop, Cursor, VS Code, Zed — any client reading mcpServers
{ "deckprobe": { "command": "npx", "args": ["-y", "@deckflow/deckprobe-mcp"] } }

It spawns the same native binary this repository ships, returns schema-v2 reports unmodified, and validates tool arguments before the engine runs. It is listed in the MCP Registry as io.github.deckflow/deckprobe.

The skill and the MCP server teach the same vocabulary. Use the