On this page
Plugin Development & Implementation
Seer provides a modular plugin architecture that allows developers to extend its capabilities across multiple surfaces. Select a plugin capability below to explore its development specifications:
Preview Plugins (Viewers)
Preview plugins extend the spacebar preview window. They support two implementation architectures: Convert Plugins and DLL Plugins (SDK v3).
Build a Preview Plugin with an AI Agent
Replace the placeholder below, then give the complete instruction to your coding agent:
Read and follow the Seer plugin development guide at https://raw.githubusercontent.com/ccseer/Seer-Plugins/refs/heads/master/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, choose Convert or DLL and briefly justify the choice, then implement a complete, installable plugin 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. Run an in-app Seer preview test when possible; otherwise explicitly state that runtime verification was not performed.
Requirement: [REPLACE THIS PLACEHOLDER with your preview plugin requirement, e.g. render mermaid diagrams in markdown preview]
Convert Plugins
Seer treats convert plugins as external command-line executors. When a user presses Space on a supported file, Seer launches the configured program, passing file paths via placeholders. The program converts the file into a format natively supported by Seer (HTML, JSON, TXT, images, etc.), which Seer loads and renders once the process exits.
Placeholder Variables
| Placeholder | Description | Example |
|---|---|---|
${output_file} |
Base output file path; append the target extension in arguments. | ${output_file}.html |
${no_cache} |
Disables conversion caching and stores output in the auto-delete directory, which is purged when preview windows close. | ${no_cache} |
Convert plugins also accept the universal placeholders (${input_file}, ${use_backslash}, ${seer_dir}, ${seer_exe}, ${seerviewer_exe}, ${7z}, ${theme}, ${lang}, ${screenshot}) and do not use the ${type_*} matcher tokens, because they declare their matches in formats rather than extensions. Both are covered in the shared Placeholders & Matching Tokens section below.
Supported Executables & Script Runtimes
- Scripts: PowerShell scripts (
.ps1, supported out-of-the-box via PowerShell). For Python (.py), Node.js (.js), or batch (.bat), compile into a standalone.exe(e.g. with PyInstaller) or bundle the interpreter inside the package. - Custom Binaries: Standalone CLI executables compiled from C/C++, Rust, Go, or C#.
plugin.json Example (Convert)
{
"name": "ipynb",
"version": "1.2.0",
"type": "convert",
"roles": [
"viewer"
],
"entry": "ipynb.ps1",
"args": [
"-i",
"${input_file}",
"-o",
"${output_file}.html"
],
"formats": [
"ipynb"
],
"appMinVersion": "4.1.3",
"author": "ccseer"
}
DLL Plugins (SDK v3)
For maximum rendering performance, deep interactivity, or streaming views, Seer supports native C++/Qt dynamic link libraries loaded directly into the viewport via QPluginLoader.
- Technical Specifications: C++17, Qt 6.8, MSVC 2022 (x64), CMake 3.22+.
- Essential Interfaces: Inherit
ViewerBase(widget implementation) and implementViewerPluginInterface(IID"seer.plugin.interface.preview/3"). - Minimum App Version: SDK v3 plugins must declare
"appMinVersion": "4.2.9".
Reference Projects
| Project | Purpose |
|---|---|
| F3DViewer | 3D model rendering and panoramic view |
| OfficeViewer | Office documents and CAD drawings |
| FontViewer | Font glyph inspection and rendering |
| JsonTreeViewer | High-performance interactive JSON tree |
| Collections | All official and community preview plugins |
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 resolves arguments and launches the helper detached (startDetached). - Execution & Error Reporting:
- Once launched, Seer does not observe the helper's exit code, capture its
stdout/stderr, or enforce a process timeout. - An in-app Toast failure notification is shown only if the process fails to start (for example, missing executable or launch failure).
- Any post-launch error, confirmation, or status feedback that the user needs to see must be presented by the helper itself (such as copying results to the clipboard or showing its own dialog).
- Exit codes and
stderrare useful for your helper's own tests and diagnostics, not for host-side UI reporting.
- Once launched, Seer does not observe the helper's exit code, capture its
- UI & Interaction: Control plugins do not draw persistent main windows of their own inside the host. 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 plus the universal placeholders (${input_file}, ${use_backslash}, ${seer_dir}, ${seer_exe}, ${seerviewer_exe}, ${7z}, ${theme}, ${lang}, ${screenshot}) listed in the shared Placeholders & Matching Tokens section below.
${output_dir}, ${output_file}, and ${no_cache} are rejected in a control manifest. A control that needs a scratch location must resolve one itself: its own executable directory first, then the system temp directory.
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
]
}
To automatically close the preview window upon success, set "close_after_success": true in the manifest.
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.
- The host expands
- Exit Code Policy:
- Expected domain results (e.g. unsigned file, not a git repository, empty metadata) must exit with code
0and 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).
- Expected domain results (e.g. unsigned file, not a git repository, empty metadata) must exit with code
Command-Line Placeholders
| Placeholder | Description | Example |
|---|---|---|
${output_file} |
Host-assigned base path with no extension; the result must be written to ${output_file}.json. |
C:\Users\...\request_dir\md5_hash |
${output_dir} |
Host-assigned request directory for attachments (charts, images). | C:\Users\...\request_dir |
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.
Placeholders & Matching Tokens
Seer expands these tokens in arguments. Which placeholders a capability may use is validated by the host when the manifest loads — an unsupported token is a manifest-loading error, not a runtime warning.
Available to Every Capability
| Placeholder | Description | Example |
|---|---|---|
${input_file} |
Absolute path of the previewed file or folder. | C:\Docs\sample.pdf |
${use_backslash} |
Optional directive flag to format path separators using Windows native backslashes (\). Must be passed as a standalone argument (e.g. "${use_backslash}"), never concatenated with other text. |
${use_backslash} |
${seer_dir} |
Directory containing Seer.exe. |
C:\Program Files\Seer |
${seer_exe} |
Absolute path to Seer.exe. Can be passed as an argument, or used directly as the command or Executable field. |
C:\Program Files\Seer\Seer.exe |
${seerviewer_exe} |
Absolute path to SeerViewer.exe. Can be passed as an argument, or used directly as the command or Executable field. |
C:\Program Files\Seer\SeerViewer.exe |
${7z} |
Absolute path to 7z.exe bundled with Seer. Can be passed as an argument, or used directly as the command or Executable field. |
C:\Program Files\Seer\plugins\7z.exe |
${theme} |
Current Seer theme, expanded as dark or light. A data placeholder that cannot be used as the entire command. |
dark |
${lang} |
Current Seer language, expanded in BCP-47 format (e.g. en, zh-CN). A data placeholder that cannot be used as the entire command. |
en |
${screenshot} |
Absolute path to a temporary PNG screenshot of the current view (captured on demand, primarily for control plugins; remains literal if view is not ready). A data placeholder that cannot be used as command. |
C:\Users\Username\AppData\Local\Temp\Seer\screenshot\view_1.png |
Capability-Specific Placeholders
| Placeholder | Preview | Control | Property |
|---|---|---|---|
${output_file} |
Base output path; append the target extension, e.g. ${output_file}.html |
Not supported | Base path with no extension; the result must be written to ${output_file}.json |
${output_dir} |
Not supported | Not supported | Request directory for attachments (charts, images) |
${no_cache} |
Disables conversion caching and stores output in the auto-delete directory | Not supported | Not supported |
A Control helper receives the target path only. If it needs a scratch location it must resolve one itself: its own executable directory first, then the system temp directory.
extensions Matcher Tokens
Beyond standard extensions (e.g. ["png", "zip"]), extensions accepts tokens that match broad categories. These apply to plugins that declare extensions (Control and Property); Convert plugins declare formats instead and do not use them.
| Token | Description |
|---|---|
${type_folder} |
Matches directories and folders. |
${type_file} |
Matches all files (including extensionless files). |
${type_all} |
Matches everything (both files and folders). |
${type_image} |
Matches images supported by Seer's native image viewer. |
${type_media} |
Matches audio and video formats. |
${type_web} |
Matches HTML and Markdown web files. |
${type_text} |
Matches text, code and config files. |
${type_pdf} |
Matches PDF documents. |
${type_none} |
Matches files outside the categories above (e.g. archives, executables). |
Packaging and In-App Testing
Once developed, the plugin must be packaged into a standard ZIP archive for installation. This applies to all plugin capabilities.
Packaging Standards
- Package Documentation: Every standalone Control or Property package should include a
PACKAGE_README.md(description plus## Options & Argumentstable), staged asREADME.mdat the package root. - Flat Root Layout: For Control and Property packages (Canonical v1),
plugin.json, the executable/script,README.md, and runtime dependencies must reside directly at the archive root. Do not wrap them inside an extra folder, and never mix flat and nested entries — the host rejects an archive with an ambiguous package root.Legacy Convert plugins installed from the online catalog use the opposite layout: a top-level
<archive-name>/folder wrapping the package files. Follow the Convert plugin guide for that case; the two layouts are not interchangeable. - Maximum Compression: 7-Zip with maximum Deflate compression is recommended:
powershell 7z a -tzip -mx=9 my-plugin-1.0.0.zip .\*
Bundling Custom Syntax Highlighting (syntax/*.xml)
Starting with Seer 4.8.0, any standard Canonical v1 plugin package can bundle custom Kate syntax highlighting definitions:
- Directory Layout: Place syntax XML files directly inside a
syntax/subfolder at the package root (i.e.<packageRoot>/syntax/*.xml). - Activation: When the plugin package is installed or enabled, Seer automatically scans this directory, registers the declared file extensions with the native text viewer, and applies syntax highlighting without restarting or recompiling Seer.
- Validation Rules:
- The package must be a valid plugin with a real executable command and declared capabilities (packages containing only
syntax/without an invocation are rejected at manifest load time). - Each XML file must follow the Kate syntax definition XML format with a
<language ...>root element, and must satisfy the following strict validation checks (failing any check will reject package installation): kateversion: Must be explicitly declared and must not exceed6.30(strictly locked to KSyntaxHighlighting 6.30.0 in Seer 4.8.0).priority: The<language>tag must explicitly declare a positive integer attribute (priority > 0). Missing or non-positive values will abort installation.extensions: Must declare matching file patterns (e.g.*.foo;*.bar), and wildcards must not contain whitespace padding (e.g.*.foo; *.baris rejected; it must be written as*.foo;*.barbecause the syntax library matches tokens verbatim without trimming).name: Must explicitly declare a non-empty language name attribute.- Maximum file size is 512 KB (524,288 bytes) per XML file; each package may contribute up to 64 definition files.
- The package must be a valid plugin with a real executable command and declared capabilities (packages containing only
- Conflict Resolution:
- Same Language Name: If multiple packages or built-in definitions share the same language name, the definition with the higher
versionattribute wins. - Extension Contention: If different language definitions claim the same file extension, the one with the higher integer
priorityattribute in<language>wins.
- Same Language Name: If multiple packages or built-in definitions share the same language name, the definition with the higher
Local In-App Testing
- Open Seer Settings and navigate to the target section:
- Preview Plugins:
Settings > Viewers-> Local tab - Control Plugins:
Settings > Controls - Property Plugins:
Settings > Properties
- Preview Plugins:
- Click + below the list and select the
.ziparchive (orplugin.jsonfrom your local folder). - Seer automatically validates the package and loads it. Verify the settings and click Okay to activate.