On this page

Third-Party Compatibility & IPC Integration

Integrate Seer with an AI Agent

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

Read and follow the Seer SDK IPC integration guide at https://raw.githubusercontent.com/ccseer/Seer-sdk/refs/heads/main/IPC_PROMPT.md (and use the matching raw headers/examples referenced inside it when needed). Treat IPC_PROMPT.md as the source of truth for transports, Win32 commands, JSON-RPC methods/events, security checks, and constraints. 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 about the target app's language/framework or integration goal, ask one clarifying question and wait. Do not infer the missing requirement.

Once clear, implement a complete, runnable Seer IPC integration in the current workspace using the mechanism that fits the requirement (Named Pipe JSON-RPC 2.0, WM_COPYDATA 6000/6001, Dynamic Explorer 4002/4003 + 4000/4001, or legacy WM_COPYDATA 5000-5010). Do not invent undocumented parameters/fields, do not modify Seer itself, and do not stop at a plan or rough snippets.

Apply every applicable contract from the guide: for Named Pipe clients, use access 0x0012018B, SECURITY_SQOS_PRESENT | SECURITY_IDENTIFICATION, PIPE_READMODE_MESSAGE, server session/owner SID verification, and FILE_FLAG_OVERLAPPED + a reader thread if subscribing to events; for file-manager Spacebar hooks, register topHwnd dynamically, handle SEER_CORE_READY restarts, and reply synchronously to 4000 -> 4001 within 150 ms; always handle Seer not running, invalid/relative paths, and error responses cleanly.

Run the project's available build or verification checks and report actual results; if live Seer runtime testing was not performed, state that explicitly.

Requirement: [REPLACE THIS PLACEHOLDER with your target app/language and integration goal, e.g. add Spacebar Quick Look integration to our C++/Win32 file manager, or open/control Seer previews and subscribe to close events from our Python launcher]

Developer Guide

Ready-to-run examples (C++, Python, C#, Rust, Go, PowerShell, AutoHotkey) and AI integration instructions are available in the Seer SDK repository.

Seer supports out-of-process integration with third-party applications, scripts, and custom file managers through:

  1. Named Pipe JSON-RPC 2.0 (\\.\pipe\Seer.IPC.v2.<SessionId>) — primary programmatic API for opening/closing/pinning previews, querying session state, registering file manager windows, and subscribing to lifecycle events.
  2. Win32 WM_COPYDATA — dynamic file manager registration (4002 / 4003 + 4000 / 4001 + SEER_CORE_READY), JSON-RPC (6000 / 6001), and legacy fire-and-forget commands (5000–5010).

Connect to \\.\pipe\Seer.IPC.v2.<SessionId> (where <SessionId> comes from ProcessIdToSessionId(GetCurrentProcessId(), ...)), exchange single-line \n-delimited UTF-8 JSON-RPC 2.0 frames (no BOM, max 64 KiB), and switch the client handle to PIPE_READMODE_MESSAGE.

Pipe connection & security requirements:

  • Access mask: Request 0x0012018B (READ_CONTROL | SYNCHRONIZE | FILE_READ_DATA | FILE_READ_EA | FILE_READ_ATTRIBUTES | FILE_WRITE_DATA | FILE_WRITE_ATTRIBUTES). Do not pass GENERIC_WRITE — it includes FILE_CREATE_PIPE_INSTANCE (0x4), which Seer's hardened pipe DACL rejects (ERROR_ACCESS_DENIED).
  • SQOS flags: Pass SECURITY_SQOS_PRESENT | SECURITY_IDENTIFICATION (0x00100000 | 0x00010000) to CreateFileW.
  • Server verification: Immediately verify GetNamedPipeServerSessionId matches your session ID and the pipe owner SID (GetSecurityInfo OWNER_SECURITY_INFORMATION) matches your user SID, BUILTIN\Administrators, or NT AUTHORITY\SYSTEM.
  • Event subscriptions: Clients calling seer.events.subscribe must also pass FILE_FLAG_OVERLAPPED and read on a dedicated background thread so synchronous ReadFile does not block WriteFile.

Available JSON-RPC methods:

Method Params Summary
seer.getInfo {} Returns protocolVersion, appVersion, versionInt, licensed, methods, events (exempt from license/active gate).
seer.app.getState {} Returns {licensed, active, tracking, stayOnTop, subWndCount, mainSessionId} (exempt from license/active gate).
seer.viewers.list {includeDisabled?} Returns {viewers: [{name, displayName, priority, internal, disabled, extensions}]} sorted by priority descending (exempt from license/active gate).
seer.preview.open {path, mode?, ifAlreadyOpen?, rect?, fullscreen?, focus?, seekMs?, viewer?} Opens preview (mode: "main" / "separated" / "pinned" / "standalone"; ifAlreadyOpen for main: "toggle" closes an already-open matching window and discards overrides, use "noop" to apply overrides; optional rect {x, y, width, height} in physical pixels clamped to screen work area, fullscreen bool, focus bool, seekMs int >= 0, viewer type name; rect/focus/viewer rejected on standalone). Returns {sessionId} or {closed: true} ({} for standalone).
seer.preview.close {sessionId?} Closes the main window (default) or target separated window (-32003 if pinned).
seer.preview.getState {sessionId?} Returns {sessionId, visible, pinned, path, viewerType, availableViewers, rect?, fullscreen, inspectorVisible, loadState, sourcePath} (rect only present when visible is true).
seer.preview.list {} Returns {sessions: [{sessionId, visible, pinned, path, isMain, viewerType, availableViewers, rect?, fullscreen, inspectorVisible, loadState, sourcePath}]}.
seer.preview.switchViewer {sessionId?, viewer} Switches an open preview's viewer in place; returns {viewer} (-32602 on unknown/disabled viewer, -32004 if invalid state).
seer.preview.reload {sessionId?} Reloads the active preview ({reloaded: true}); returns -32004 when hidden, unloaded, or not reloadable.
seer.preview.separate {sessionId?} Opens a separated window for the current preview path; returns {sessionId} (-32004 if invalid state, -32008 on open failure).
seer.preview.closeAllSub {} Closes all visible child windows (separated and pinned, excluding main) and returns {closedCount}.
seer.preview.reveal {sessionId?} Reveals the current file in Explorer without changing preview visibility; returns {revealed: true} (-32008 on failure).
seer.preview.openDefault {sessionId?} Opens the current file with the system default app without changing preview visibility; returns {opened: true} (-32008 on failure).
seer.preview.getProperties {sessionId?} Returns {groups: [...]} containing inspector property groups for the active preview (-32004 if unavailable).
seer.preview.listControls {sessionId?} Returns {sessionId, path, controls: [{id, name, closeAfterSuccess, requiresScreenshot}]} for enabled Control plugin actions.
seer.preview.triggerControl {sessionId?, id} Triggers a Control plugin action ({triggered: true, id, sessionId}); hides preview + emits preview.closed if closeAfterSuccess is true and launch succeeds.
seer.window.pin {sessionId?} Pins a visible preview window (always on top).
seer.window.waggle {sessionId?} Triggers the window waggle animation on a visible preview window (-32004 if hidden).
seer.window.setBounds {sessionId?, rect} Applies clamped {x, y, width, height} physical pixel bounds to a visible window (restores maximized state without overwriting persistent geometry); returns applied {rect}.
seer.window.setFullscreen {sessionId?, fullscreen} Sets fullscreen state on a visible window; returns {fullscreen}.
seer.window.setInspector {sessionId?, visible} Shows/hides the inspector panel ({visible}); visible: true requires a loaded valid viewer (-32004 on DT_None/error/resolving), visible: false is idempotent on any visible window.
seer.explorer.register / unregister / suspend {topHwnd, name?} / {topHwnd} / {topHwnd, suspended} Dynamically manage caller-owned file manager HWNDs (topHwnd is uint32 in [1, 0xFFFFFFFF], optional name <= 128 chars).
seer.events.subscribe / unsubscribe {events: [...]} Named Pipe only. Subscribe to preview.opened, preview.fileChanged, preview.loadStateChanged, preview.viewerChanged, preview.closed, window.pinnedChanged, app.stateChanged; returns {events: [...]}.

See seer/ipcv2helper.h, examples/cpp_ipc/main.cpp, and examples/python/seer_ipc.py for C++/Python reference clients and helpers.

Error codes & license/active gate:

  • License / active gate: seer.preview.* and seer.window.* require an active license (-32009 LICENSE_EXPIRED takes precedence over -32001 NOT_ACTIVE when both apply). seer.getInfo, seer.app.getState, seer.viewers.list, seer.explorer.*, and seer.events.* remain available regardless of license or activation state.
  • Domain error codes: -32001 NOT_ACTIVE, -32002 SESSION_NOT_FOUND, -32003 SESSION_PINNED, -32004 INVALID_STATE, -32005 TRANSPORT_UNSUPPORTED, -32006 REGISTRATION_REJECTED, -32007 LAUNCH_FAILED, -32008 OPEN_FAILED, -32009 LICENSE_EXPIRED (plus standard JSON-RPC errors -32700 / -32600–-32603). Full schema and session rules are documented in IPC_PROMPT.md.

Custom File Manager Integration (Spacebar Hook)

Custom file managers register their top-level window handles dynamically at runtime so Seer intercepts the Spacebar keypress when that window is in the foreground and requests the currently selected file path.

Step 1: Register Your Top-Level Window (4002)

Locate Seer via FindWindowW(L"SeerWindowClass", nullptr) and send WM_COPYDATA with dwData = SEER_REGISTER_EXPLORER (4002), fixed 8-byte payload (ULONGLONG holding the low 32 bits of your topHwnd), and wParam set to a valid HWND owned by your process (wParam = 0 is always rejected):

bool registerToSeer(HWND myTopHwnd)
{
    HWND seer = FindWindowW(SEER_CLASS_NAME, nullptr);
    if (!seer || !myTopHwnd) {
        return false;
    }

    ULONGLONG payload = static_cast<ULONGLONG>(static_cast<DWORD>(reinterpret_cast<ULONG_PTR>(myTopHwnd)));
    COPYDATASTRUCT cds{};
    cds.dwData = SEER_REGISTER_EXPLORER; // 4002
    cds.cbData = sizeof(payload);        // fixed 8 bytes
    cds.lpData = &payload;

    DWORD_PTR result = 0;
    if (!SendMessageTimeoutW(seer, WM_COPYDATA, reinterpret_cast<WPARAM>(myTopHwnd),
                             reinterpret_cast<LPARAM>(&cds), SMTO_ABORTIFHUNG, 500, &result)) {
        return false;
    }
    return result != 0;
}

Listen for the RegisterWindowMessageW(L"SEER_CORE_READY") broadcast in your window procedure and re-run registerToSeer(myTopHwnd) so your integration continues working if Seer starts later or restarts. Optionally send SEER_UNREGISTER_EXPLORER (4003) before destroying your window.

If your file manager runs elevated while Seer runs non-elevated, allow messages on your top-level window with ChangeWindowMessageFilterEx for WM_COPYDATA and RegisterWindowMessageW(L"SEER_CORE_READY").

Step 2: Handle Spacebar Press (4000 -> 4001)

When the user presses Spacebar inside a registered foreground window, Seer sends WM_COPYDATA with dwData = SEER_REQUEST_PATH (4000), cbData = 0, and lpData = nullptr.

Seer waits 150ms (SendMessageTimeout) for your synchronous SEER_RESPONSE_PATH (4001) reply before returning from WM_COPYDATA handling so the UI never hangs.

Respond back to FindWindowW(SEER_CLASS_NAME, nullptr) with dwData = SEER_RESPONSE_PATH (4001) carrying the NUL-terminated UTF-16LE absolute path (cbData = (wcslen(path) + 1) * sizeof(wchar_t)). See examples/cpp_explorer/main.cpp for a complete runnable implementation.


Custom App Trigger (Legacy WM_COPYDATA)

Existing integrations using one-shot WM_COPYDATA preview commands (5000–5010) continue to work unchanged (see seer/ipclegacyhelper.h and examples/legacy/):

HWND seer = FindWindowW(L"SeerWindowClass", nullptr);
if (seer) {
    COPYDATASTRUCT cd{};
    cd.cbData = static_cast<DWORD>((wcslen(path) + 1) * sizeof(wchar_t));
    cd.lpData = const_cast<LPWSTR>(path);
    cd.dwData = SEER_INVOKE_W32; // 5000
    SendMessageW(seer, WM_COPYDATA, 0, reinterpret_cast<LPARAM>(&cd));
}

Win32 WM_COPYDATA Reference (SeerCommand)

Defined in seer/ipc.h:

Command Name Value Description
SEER_REQUEST_PATH 4000 Sent from Seer to registered custom explorer requesting the selected file path (reply within 150ms).
SEER_RESPONSE_PATH 4001 Sent from custom explorer back to Seer containing the selected UTF-16LE absolute path.
SEER_REGISTER_EXPLORER 4002 Sent from custom explorer to Seer with 8-byte low-32-bit topHwnd and valid caller wParam HWND.
SEER_UNREGISTER_EXPLORER 4003 Sent from custom explorer to Seer to unregister a previously registered topHwnd.
SEER_INVOKE_W32 5000 Preview in the main window (minimum 200ms interval; legacy WM_COPYDATA).
SEER_INVOKE_W32_SEP 5001 Preview in a separated window (legacy WM_COPYDATA).
SEER_IS_VISIBLE 5004 Check if the main preview window is visible (1 or 0).
SEER_HIDE 5005 Hide the main preview window if visible.
SEER_GET_CURRENT_FILE 5006 Write the currently previewed file path into a named shared-memory mapping.
SEER_GET_VERSION 5007 Query Seer version integer (major * 10000 + minor * 100 + patch, e.g. 40900 for 4.9.0).
SEER_IS_TRACKING_ENABLED 5008 Query if file tracking mode is enabled.
SEER_INVOKE_W32_STANDALONE 5009 Preview in a standalone viewer process (SeerViewer.exe; legacy WM_COPYDATA).
SEER_INVOKE_W32_PIN 5010 Preview and pin the window (always on top; legacy WM_COPYDATA).
SEER_V2_REQUEST 6000 Send a single UTF-8 JSON-RPC 2.0 request (<= 64 KiB, no BOM); wParam must be caller's reply HWND on the sending thread.
SEER_V2_RESPONSE 6001 JSON-RPC 2.0 response sent synchronously by Seer back to wParam.

SeerViewer.exe (SeerViewerWindowClass) handles standalone previews and returns FALSE (0) for 4002, 4003, and 6000.