Plugin Development & Implementation

Control Plugins

Control plugins add custom action buttons to the left side of the bottom Control Bar in the preview window, enabling quick operations and external tool integrations for the active file or folder.

Build a Control Plugin with an AI Agent

Replace the placeholder below, then give the complete instruction to your coding agent:

Read and follow the Seer control plugin development guide at https://raw.githubusercontent.com/ccseer/Seer-Controls/refs/heads/main/plugin_development_guide.md. Treat it as the source of truth for architecture, plugin.json, implementation, validation, and packaging. If the guide is unavailable, stop and report that before proceeding.

Before doing any work, inspect the Requirement below. If it is missing, unchanged placeholder text, or too ambiguous to implement, ask one clarifying question and wait. Do not infer the missing requirement.

Once clear, implement a complete, installable control plugin adhering to the Canonical v1 process contract in the current workspace. Do not modify Seer itself or stop at a plan or code snippets.

Follow every applicable validation step in the guide and report the actual results.

Requirement: [REPLACE THIS PLACEHOLDER with your control plugin requirement, e.g. open VS Code in the current directory or copy absolute path to clipboard]

Architecture & Contract

• Process Model: Implements the Canonical v1 process contract (backend: "process", capabilities: ["control"]). Seer executes the helper via CLI.
• Return Status & Error Reporting:
  • Success: The process exits with code 0 (or matches success_exit_codes). If "close_after_success": true is configured, Seer automatically closes the preview window after execution succeeds.
  • Failure: The process exits with a non-zero code. Anything written to standard error (stderr) is captured by Seer and shown as an in-app Toast failure notification.
• UI & Interaction: Control plugins do not draw persistent main windows of their own. Typical helpers run background tasks, copy text to the clipboard, or invoke native Windows system dialogs (e.g. Open With, Properties, Share).

Command-Line Placeholders

A control helper receives the target path only — ${input_file} plus the universal placeholders (${use_backslash}, ${seer_dir}, ${seer_exe}, ${7z}) listed in the shared Placeholders & Matching Tokens section below.

plugin.json Examples (Control)

Example 1: Folder Action (Terminal Here)

The official Terminal Here plugin configuration:

{
  "schema_version": 1,
  "id": "io.1218.seer.terminal-here",
  "name": "Terminal Here",
  "description": "Opens a terminal window in the current folder.",
  "version": "1.0.0",
  "appMinVersion": "4.5.10",
  "backend": "process",
  "capabilities": [
    "control"
  ],
  "extensions": [
    "${type_folder}"
  ],
  "command": "terminal_here.exe",
  "arguments": [
    "--input",
    "${input_file}"
  ],
  "close_after_success": false,
  "timeout_ms": 150000,
  "success_exit_codes": [
    0
  ]
}

Example 2: File Action (Explorer Open With)

The official Explorer Open With plugin configuration:

{
  "schema_version": 1,
  "id": "io.1218.seer.explorer-open-with",
  "name": "Open With",
  "description": "Opens the Windows Open With dialog for the current file.",
  "version": "1.1.0",
  "appMinVersion": "4.5.10",
  "backend": "process",
  "capabilities": [
    "control"
  ],
  "extensions": [
    "${type_file}"
  ],
  "command": "shellopenwith.exe",
  "arguments": [
    "--input",
    "${input_file}",
    "${use_backslash}"
  ],
  "timeout_ms": 30000,
  "success_exit_codes": [
    0
  ]
}

For official control plugin source code, see: ccseer/Seer-Controls.

Property Plugins

Property plugins extend Seer's metadata inspection engine. When a user presses Ctrl + I on a previewed file or folder (or opens the Properties window), matching property plugins extract and display structured metadata and graphical scopes/charts.

Build a Property Plugin with an AI Agent

Replace the placeholder below, then give the complete instruction to your coding agent:

Read and follow the Seer property plugin development guide at https://raw.githubusercontent.com/ccseer/Seer-Properties/refs/heads/main/plugin_development_guide.md. Treat it as the source of truth for architecture, plugin.json, implementation, validation, and packaging. If the guide is unavailable, stop and report that before proceeding.

Before doing any work, inspect the Requirement below. If it is missing, unchanged placeholder text, or too ambiguous to implement, ask one clarifying question and wait. Do not infer the missing requirement.

Once clear, implement a complete, installable property plugin adhering to the Canonical v1 process contract and Schema 1 JSON specification in the current workspace. Do not modify Seer itself or stop at a plan or code snippets.

Follow every applicable validation step in the guide and report the actual results.

Requirement: [REPLACE THIS PLACEHOLDER with your property plugin requirement, e.g. extract and display detailed audio/video codec parameters and bitrate for MP4 files]

Architecture & Contract

• Process Model: Implements the Canonical v1 process contract (backend: "process", capabilities: ["property"], result_schema: 1).
• CLI Invocation: The host passes: --input "${input_file}" --output "${output_file}" --output-dir "${output_dir}"
• Output Publication:
  • The host expands ${output_file} to a base path without an extension (e.g. <requestDir>/<md5>).
  • The plugin must write its JSON result to <output-base>.json (i.e. ${output_file}.json).
  • Visual attachments (charts, histograms, vectorscopes) must be saved into ${output_dir}.
  • Constraint: ${no_cache} is forbidden for property plugins.
• Exit Code Policy:
  • Expected domain results (e.g. unsigned file, not a git repository, empty metadata) must exit with code 0 and describe the status in JSON.
  • Exit non-zero only on fatal errors or invalid invocations (non-zero exits cause the host to wipe the request directory).

Command-Line Placeholders

Plus the universal placeholders listed in the shared Placeholders & Matching Tokens section below, which also covers the ${type_*} matcher tokens. ${no_cache} is rejected for property plugins.

Result JSON (Schema 1) Specification

The result file ${output_file}.json must be valid UTF-8 JSON containing result_schema: 1 and a data object:

1. Flat Rows

Only when the whole result is a single row (e.g. SHA-256):

{
  "result_schema": 1,
  "data": {
    "SHA-256": "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
  }
}

2. Subgroup with an Ordered Array of Single-Key Objects (Default)

Anything that produces more than one row must be published as exactly one subgroup titled after the plugin — loose top-level rows collide with every other plugin's rows, which the Inspector shows in one list. The array order is the render order, so this is the only form that lets the plugin decide the sequence the rows appear in:

{
  "result_schema": 1,
  "data": {
    "Git": {
      "value": [
        { "Repository": "ccseer/Seer-Properties" },
        { "Branch": "main" },
        { "Status": "Clean" }
      ]
    }
  }
}

3. Subgroup with a Value Object

value may also be a plain object, but its rows are rendered in the key order of the parsed object, which the plugin cannot control. Use it only when row order does not matter:

{
  "result_schema": 1,
  "data": {
    "Git": {
      "value": {
        "Branch": "main",
        "Status": "Working tree clean"
      }
    }
  }
}

4. Graphical Charts & Scopes (Image Attachments)

Save generated PNG charts into ${output_dir}, and declare them with {"type": "image", "value": "relative_filename.png"}:

{
  "result_schema": 1,
  "data": {
    "Image Scopes": {
      "value": [
        { "RGB Histogram": { "type": "image", "value": "histogram.png" } },
        { "Luma Waveform": { "type": "image", "value": "waveform.png" } }
      ]
    }
  }
}

plugin.json Example (Property)

{
  "schema_version": 1,
  "id": "io.1218.seer.git-info",
  "name": "Git Info",
  "description": "Reports repository information for the current folder using Git.",
  "version": "1.0.0",
  "appMinVersion": "4.5.10",
  "backend": "process",
  "capabilities": [
    "property"
  ],
  "extensions": [
    "${type_folder}"
  ],
  "invocations": {
    "property": {
      "command": "git_info.exe",
      "arguments": [
        "--input",
        "${input_file}",
        "--output",
        "${output_file}",
        "--output-dir",
        "${output_dir}"
      ],
      "result_schema": 1,
      "timeout_ms": 30000,
      "success_exit_codes": [
        0
      ]
    }
  }
}

For official property plugin source code, see: ccseer/Seer-Properties.