Skip to content

CLI

Inspecting and recovering the desktop input lease

Experimental control surface

Desktop input coordination and these control commands are experimental. The protocol, output, and recovery workflow may change in any release. See Experimental desktop input coordination.

These commands inspect or change an existing coordinator. They do not start one:

spectre input-lock status
spectre input-lock status --json
spectre input-lock revoke --lease <observed-id> --reason <text>
spectre input-lock revoke --lease <observed-id> --reason <text> --force

Revoke compares the supplied ID with the current lease. Copy the ID from status. A stale ID cannot revoke a new holder. --force waits through a grace period and reports audited unsafeTakeover=true. It does not prove an active native call has stopped.

The spectre command inspects and controls a running Compose Desktop application. Use it to examine the semantics tree, debug interactions, or capture evidence without writing a JUnit test. MCP clients can use the same operations.

The command starts a private local daemon when needed. The daemon keeps sessions open across CLI calls and shares them with spectre mcp.

Built-in guide

The CLI bundles this user guide, including Traps and gotchas, at build time. spectre guide always matches the installed version, works offline, and does not start the daemon:

spectre guide                                   # CLI workflow and the list of topics
spectre guide traps                             # print one topic as Markdown
spectre guide gotchas                           # another name for traps
spectre guide --search "xvfb-run hangs"         # best-matching sections
spectre guide -s "type text does not reach the field" -n 5 --json

Search ranks every heading section, bullet with a bold lead, and table row with BM25. It also matches the alias comments in each page and a small built-in synonym table, so "gotcha" finds "trap" and "stuck" finds "hang". Each result starts with its breadcrumb, for example traps › CI and headless runs › xvfb-run hangs after the tests finish. Output stays within about 4 KB; a cut section names the topic that holds the rest. -n sets the number of results (default 3, at most 20).

With --json, a search prints version, query, results (each with topic, path, breadcrumb, text, score, and truncated), and omitted, the number of results that did not fit. A topic prints version, topic, and text.

Usage errors and daemon errors end with a hint that names the matching guide topic.

Install

On macOS, install the formula from this repository:

brew tap rock3r/spectre https://github.com/rock3r/spectre
brew install rock3r/spectre/spectre

On Windows, add the Scoop bucket:

scoop bucket add spectre https://github.com/rock3r/spectre
scoop install spectre

On Linux, download the matching archive from the GitHub release, extract it, and put its spectre executable on PATH.

Startup and the AOT cache

The CLI runs on JDK 21+. Packaged distributions bundle a Temurin 25 runtime. On JDK 25+ the CLI uses the Project Leyden AOT cache (JEP 483/514/515) to start faster. On JDK 21–24 the CLI and its daemon run uncached: nothing is trained or consumed, and the frontend JVM keeps the JVM's default collector.

An AOT cache is only valid for the exact JDK build, OS/architecture, jar path, and jar contents it was trained against, so Spectre never ships one. Instead:

  1. First run on a machine trains a cache before running your command: a throwaway spectre --help record run and a cache-assembly step, both with their output discarded, store the resulting cache in a per-user cache directory, and only then does your command start — against the fresh cache. That first invocation takes a couple of seconds longer than usual. Training never touches your command's input or output streams (a record run appends JVM diagnostics to stdout, which would corrupt spectre mcp's protocol stream and --json output), so every command behaves identically whether or not a cache exists yet; if training fails for any reason, the command simply runs uncached.
  2. Later runs launch with -XX:AOTCache, skipping class loading/linking and replaying method profiles. In local measurements this roughly halves cold CLI startup (for example spectre --help from ~330 ms to ~135 ms before the small bootstrap launcher's overhead).
  3. Upgrades retrain automatically. The cache file name fingerprints the jar's path and contents, the caller's module options, OS/architecture, and runtime identity (version, vendor, and VM build), so a replaced jar plans a fresh training run instead of pointing the JVM at a cache it would reject. Relocating the installation likewise retrains once. At most three caches are retained per user; older ones are pruned when a new cache is promoted.

Cache locations: $SPECTRE_AOT_CACHE_DIR when set, otherwise $XDG_CACHE_HOME/spectre/aot or ~/.cache/spectre/aot on Linux, ~/Library/Caches/Spectre/aot on macOS, and %LOCALAPPDATA%\Spectre\aot on Windows. Deleting the directory is safe; the next run retrains.

The CLI's short-lived frontend JVMs run with an explicit G1 collector and a pinned heap representation: JDK 25's AOT cache does not support the ZGC collector a stock launcher would otherwise select, and the cache is only valid for the representation it was trained with. A cache-consuming daemon runs with that same pinned layout; it only consumes a ready cache and never trains, so its detached start can never race the foreground's training. Because the foreground trains and promotes the cache before running your first command after an install or upgrade, a daemon started afterwards can already consume it; a daemon that starts before any foreground launch has trained simply starts uncached, and later daemon starts are cached. Set SPECTRE_AOT=off to disable caching entirely. AOT options you supply yourself through JAVA_TOOL_OPTIONS, JDK_JAVA_OPTIONS, or _JAVA_OPTIONS also win: Spectre then launches without managing a cache.

Run spectre --help after installation. Each command also supports --help. Use the installed binary's help text for its exact arguments and options. spectre --version, spectre -v, and spectre version print the installed version; add --json for {"version":1,"spectreVersion":"…"}.

Daemon socket location

The CLI talks to a per-user daemon over a Unix domain socket. The socket lives in an owner-only sp-d-<id> directory below a base directory: /tmp on Linux and macOS, and java.io.tmpdir on Windows. Every ancestor of that directory must be owned by root or by you, and must be sticky or not writable by group or others. Otherwise the daemon refuses to start; see troubleshooting.

Set SPECTRE_DAEMON_SOCKET_DIR to use another base directory:

export SPECTRE_DAEMON_SOCKET_DIR="$XDG_RUNTIME_DIR"
  • The value must be an absolute path. An empty value keeps the default.
  • The directory gets the same ownership and permission checks as the default base.
  • The full socket path must fit in 100 bytes. A longer path fails with an error that names the path and its length; Spectre never falls back to another directory.
  • The CLI resolves the path and passes it to the daemon it starts, so they always agree. A CLI run with a different value talks to a different daemon: it starts its own at the new path, and a daemon already running at the old path keeps running until it shuts down. Set the variable everywhere you run spectre, including the environment of MCP clients that launch spectre mcp.

What it can do

For a typical session:

  1. Find a running JVM with ps, or launch one with spectre launch -- <command>.
  2. Attach it and retain the returned session ID (or hold the launch session open).
  3. Inspect windows, the semantics tree, or nodes (test tag, text, waits).
  4. Use a current node key to click, type, swipe, scroll, or press keys, then inspect again.
  5. Capture a screenshot, atomic capture, or recording when useful.
  6. Detach the session (or kill the daemon) when finished.

Launch and attach

End-to-end: existing process

# 1. Discover attachable JVMs (same OS user; daemon/CLI excluded).
spectre ps --json

# 2. Attach and keep the session id.
SESSION=$(spectre attach <pid> --json | jq -r .sessionId)

# 3. Drive and inspect while the session lives in the shared daemon.
spectre windows "$SESSION"
spectre tree "$SESSION" --json
spectre find "$SESSION" save-button --json
spectre click "$SESSION" <node-key>
spectre type "$SESSION" "A short note"

# 4. Release this session (daemon stays up for other sessions / MCP).
spectre detach "$SESSION"

# Or stop the whole daemon and discard every session:
# spectre daemon kill

Session lifetime (attach path):

Action Effect
spectre attach <pid> Creates a daemon session; prints session id (JSON: id, sessionId, pid).
Further CLI / MCP tools Reuse that id against the same per-user daemon.
spectre detach <session-id> Ends that session; reports leftover captures and a prune command when any exist.
spectre daemon kill Stops the daemon and discards all sessions.
Leaving the process attached without detach Session remains until detach, daemon kill, or daemon crash/idle teardown.

Store the session ID. The CLI does not set a current session in the shell.

End-to-end: launch harness

spectre launch starts a command and checks process, JVM, agent, and window readiness. It attaches Spectre and stops the launched process tree when the session ends. Use java -jar, installDist, or a packaged app when possible. Gradle ./gradlew :app:run and hotRun emit warnings. They need --app-name when the Gradle daemon starts the app JVM.

# Prod-like (recommended)
spectre launch --once -- java -jar app/build/libs/app.jar

# Gradle-ish (supported with warnings; name filter recommended)
spectre launch --once --app-name ComposeFixtureMain -- ./gradlew :agent-test-fixture:run

# Hold the session open until Enter / EOF, then detach and tear down the process tree
spectre launch -- java -jar app.jar

Options:

  • -C / --directory — working directory for the launched process
  • --app-name — substring of the app JVM display name (Gradle-ish descendant discovery)
  • --once — exit after readiness succeeds (print window count); the session does not remain open

Session lifetime (launch path):

Mode Lifetime
Default (hold) Prints pids, log paths, and window count; keeps the attach open until Enter, EOF, or interrupt; then detaches and kills the launched process tree.
--once Same readiness attach, then exits immediately after the first window check (still tears down the process tree).
Ctrl-C / JVM exit Shutdown hook tears down any published launch session.

Launch manages its own session. It does not return a daemon session ID for later commands from another shell. Use ps and attach for a long-lived, multi-command session.

Stdout/stderr from the launched process are captured to files; their paths are printed on success. Stage failures print a taxonomy error such as [PROCESS_ALIVE] with exit code and stderr excerpt. See Troubleshooting.

Quick recipe (attach session)

Scripts and agents should request --json where available. The response includes a format version and stable field names. Use the response's session ID and node keys. Text output is intended for people.

spectre ps --json
spectre attach <pid> --json
# … use the returned session ID …

spectre windows <session-id>
spectre tree <session-id> --json
spectre find <session-id> save-button --json
spectre find-text <session-id> "Save" --json
spectre wait-for-node <session-id> --tag save-button
spectre wait-until-gone <session-id> --tag popup-body
spectre wait-for-visual-idle <session-id>
spectre click <session-id> <node-key>
spectre double-click <session-id> <node-key>
spectre long-click <session-id> <node-key> --hold-ms 500
spectre type <session-id> "A short note"
spectre press-key <session-id> Enter
spectre press-key <session-id> Ctrl+S
spectre focus-window <session-id> --window 0
spectre scroll-wheel <session-id> <node-key> 3
spectre swipe <session-id> --from <from-key> --to <to-key>
spectre swipe <session-id> --start-x 100 --start-y 400 --end-x 100 --end-y 100

# Capture modes (see below) — do not conflate them
spectre screenshot <session-id> --fullscreen --output ./desktop.png
spectre capture <session-id> --json
spectre record start <session-id> --window 0 --output ./window.mp4
spectre record status <session-id>
spectre record stop <session-id>

spectre detach <session-id>

Command reference

Most session commands take the session ID first and support --json. Run spectre <command> --help for the installed option list.

Discovery and lifecycle

Command Purpose Important args / defaults
guide [topic] Print the bundled guide, or search it --search/-s <words>, -n, --json
ps List attachable JVM processes --json
attach <pid> Attach daemon to target JVM; print session --json → id, sessionId, pid
detach <session-id> End session; leftover capture report --json includes capturePaths, pruneCommand
launch -- <cmd…> Start process, readiness, attach, teardown -C, --app-name, --once (see above)
daemon status List live daemon sessions --json → sessions[] with id, sessionId, pid
daemon kill Stop daemon; discard all sessions --json
mcp Stdio MCP server over the shared daemon No extra args; must not wrap stdout
version Print the CLI version --json; also --version / -v

attach --json and daemon status --json report the session ID as both id and sessionId. The two keys always hold the same value; sessionId matches record status --json and the MCP tools.

Inspection and waits

Command Purpose Important args / defaults
windows <session-id> Top-level windows and popup roots Indices used by --window on capture/record/focus-window
tree <session-id> Current semantics nodes Keys are ephemeral
find <session-id> <test-tag> Exact Compose test-tag match Single snapshot; does not wait
find-text <session-id> <text> Find by visible/editable text Exact match by default; --substring for contains
wait-for-node <session-id> Poll until tag and/or text match --tag, --text (at least one), --timeout-ms default 5000
wait-until-gone <session-id> Poll until nothing matches tag and/or text --tag, --text (at least one), --timeout-ms default 5000
wait-for-visual-idle <session-id> Wait until consecutive frames are stable --timeout-ms default 5000
wait --reload-settled <session-id> Compose Hot Reload settle only Requires --reload-settled; --timeout-ms default 60000; fails closed when HR is not active

find, find-text, and tree read the UI once. Use wait-for-node when the expected node may appear later.

Without --json, tree, find, and find-text print one line per node, so the output works with grep:

window-0:root-0:node-7 Button tag="save-button" text="Save" parent=window-0:root-0:node-2 [focused] [clickable] @ (412,630 96x40)
window-0:root-0:node-9 TextField tag="title" editable="Draft" desc="Title" parent=window-0:root-0:node-2 [disabled] @ (24,96 560x56)
window-0:root-0:node-11 Checkbox tag="wrap" toggle=On parent=window-0:root-0:node-2 [clickable] @ (24,160 48x48)
window-0:root-0:node-12 Node progress=0.5/0..1 parent=window-0:root-0:node-2 @ (80,182 240x4)

Each line holds the node key and role (Node when the node has none), then any of tag="…", text="…" (one per text), editable="…", and desc="…" (one per content description). Next come toggle= with On, Off, or Indeterminate for a checkbox or switch, and progress=value/min..max for a slider or progress bar, followed by steps= when the range is stepped. Then parent= names the parent node key. The state flags [focused], [disabled], [selected], [clickable], and [hidden] follow, and the line ends with the bounds as @ (x,y widthxheight) in screen coordinates. Empty values are left out. Quotes, backslashes, and line breaks inside values are escaped, so every node stays on one line.

Use --json for the full, stable field set. Each node object has key, testTag, texts, editableText, role, contentDescription, isFocused, isVisible, bounds, isDisabled, isSelected, isClickable, toggleableState, progress (current, min, max, steps), parentKey, childKeys, and boundsInWindow. boundsInWindow is the node's layout bounds within its Compose surface, in Compose (physical) pixels. Use bounds for screen positions. The MCP tree, find, find_text, and wait_for_node tools return the same node fields, plus contentDescriptions.

wait-until-gone is the absence counterpart: it returns once nothing matches, so use it after dismissing a popup, menu, or dialog. It refreshes the tracked windows before every poll, which is what lets it see a Compose popup that took its whole window with it. On timeout it exits 5 and prints the selector, the timeout, and how many matching nodes were still on screen:

Spectre daemon error: Agent reported timeout for waitUntilGone: IllegalStateException: waitUntilGone timed out after 5000ms: 1 node(s) matching tag="popup.body" still present in tracked windows

Input

Attach uses synthetic input by default. Spectre dispatches synthetic events inside the target JVM, so type and press-key work while another app is in the foreground, including after a click. type still needs a focused node, such as a text field you clicked first.

A target that opted into real OS input receives events through the operating system. Those events can change focus and application state. They reach the current pointer or keyboard target. With real OS input, type and press-key fail while the target JVM does not own OS keyboard focus. Run focus-window first when another process owns the foreground.

Command Purpose Important args / defaults
click <session-id> <node-key> Single click at node centre Refresh keys after UI changes
double-click <session-id> <node-key> Double-click Same key rules as click
long-click <session-id> <node-key> Long press --hold-ms default 500
swipe <session-id> Drag node→node or screen coords See Swipe modes
scroll-wheel <session-id> <node-key> <wheel-clicks> Wheel at node centre Positive = down; negative = up
press-key <session-id> <key> Press one key or chord Key name, chord, or AWT code; --modifiers default none; see Keys
type <session-id> <text> Type into the focused node Needs a focused node; real OS input also needs OS focus
focus-window <session-id> Raise and focus a window --window default 0 (index from windows)

Swipe modes

Each swipe call uses either node keys or screen coordinates:

# Node centres (from / to keys from tree / find / wait-for-node)
spectre swipe <session-id> --from <from-node-key> --to <to-node-key> \
  --steps 12 --duration-ms 200

# Screen coordinates (AWT user-space pixels, same space as window bounds)
spectre swipe <session-id> \
  --start-x 100 --start-y 400 --end-x 100 --end-y 100 \
  --steps 12 --duration-ms 200

Defaults: --steps 12, --duration-ms 200. Mixing node keys with coordinates fails.

Press-key AWT codes

press-key takes a key name, a chord, or a java.awt.event.KeyEvent virtual-key integer. Key names are case-insensitive:

Kind Accepted names
Letters and digits A–Z; Digit0–Digit9
Punctuation / . , - = [ ] \ ; ' `
Editing Enter / Return, Tab, Escape / Esc, Backspace, Delete / Del, Insert / Ins, Space
Navigation Up / ArrowUp, Down / ArrowDown, Left / ArrowLeft, Right / ArrowRight, Home, End, PageUp / PgUp, PageDown / PgDn
Function keys F1–F12

A bare number is always a raw key code, as in earlier releases, so 9 is Tab rather than the 9 key. Use Digit9 for the digit key on its own. Inside a chord, a single digit is the digit key (Ctrl+1).

A chord joins modifiers and one key with +: Ctrl+S, Cmd+K, Ctrl+Shift+P. --modifiers takes modifier names separated by commas or +, or an integer java.awt.event.InputEvent modifier mask. Modifiers from a chord and from --modifiers combine. A modifier on its own, such as Shift, is not a key.

Modifier name InputEvent mask
shift 64 (SHIFT_DOWN_MASK)
ctrl, control 128 (CTRL_DOWN_MASK)
meta, cmd, command 256 (META_DOWN_MASK)
alt, option, opt 512 (ALT_DOWN_MASK)

These calls are equivalent:

spectre press-key <session-id> Ctrl+S
spectre press-key <session-id> S --modifiers ctrl
spectre press-key <session-id> 83 --modifiers 128

Driving input lists the same values for the library API. With real OS input, the target needs OS focus for keyboard input. An attach client can keep focus, so run focus-window first. Synthetic input, the attach default, does not need OS focus.

Capture and recording

The three capture commands return different outputs:

Surface CLI Output Targeting notes
Fullscreen screenshot screenshot … --fullscreen Single PNG of the full virtual desktop Attach/CLI supports whole-desktop mode only. Default / --window / --surface fail closed (occlusion/privacy risk). MCP returns inline PNG bytes; no path is returned.
Atomic capture capture Window PNG + full semantics tree on daemon disk (capture.json + screenshot.png) --window defaults to 0. The daemon takes a native still of the window. It finds a Frame or Dialog by its title, so such a window needs a unique, non-blank title, and an untitled JWindow popup by its position and size. It never falls back to a desktop crop. Stdout/MCP returns only a summary (paths + counts). See Atomic capture.
Recording record start / stop / status MP4 path on daemon filesystem The default is tracked window index 0. --fullscreen captures the primary display only; multi-monitor recording is unsupported. Returns paths, never video bytes.
# Full-desktop still (explicit opt-in)
spectre screenshot <session-id> --fullscreen --output ./desktop.png
# Without --output: temp PNG; path printed

# Atomic capture (window still + tree) — default root $TMPDIR/spectre/captures/
spectre capture <session-id> --window 0 --json
spectre capture <session-id> --out-dir ./my-captures --json

# Recording — window (default) vs primary display
spectre record start <session-id> --window 0 --output ./window.mp4
spectre record start <session-id> --fullscreen --output ./desktop.mp4
# Omit --output to allocate under the Spectre capture root (ledger + prune)
spectre record status <session-id> --json
spectre record stop <session-id>

spectre captures list [--all] [--json]
spectre captures prune --keep 20
spectre captures prune --session <session-id>
spectre captures prune --older-than 7d --include-out-dir --force

All three normally write output in screen pixels. A 1600×1000dp window on a 2× display produces a 3200×2000 PNG or MP4. capture.json reports PNG dimensions in window.imageWidth and imageHeight. An oversized --fullscreen still can use logical resolution to fit the attach frame budget. See Atomic capture — Pixel scale. The default budget is 64 MiB. Set --max-frame-bytes or $SPECTRE_MAX_FRAME_BYTES to raise it; see payload limits.

captures list shows size and live/closed status. captures prune supports --keep N, --older-than (30s / 5m / 24h / 7d), --all, --session <id>, --force (override live-session guard), and --include-out-dir (client --out-dir roots are skipped unless set). Prune refuses to run if the daemon cannot report live sessions.

Spectre keeps at most the last 50 closed-session captures under the default root when it applies the lazy cap. It never automatically deletes client --out-dir captures. Detach reports leftover files and a captures prune --session command. The Atomic capture guide links to spectre-capture jq recipes.

Recording and atomic capture need the platform helper on the daemon host (spectre-recording-macos / spectre-recording-linux / spectre-recording-windows as appropriate), plus OS permissions (macOS Screen Recording TCC, Linux portal/X11 display, Windows helper runtimes). See Recording and Recording limitations.

OS permissions

These commands run locally without the daemon. check never opens a dialog. request may, so run it only with a person at the machine.

Platform permissions check permissions request
macOS Screen Recording TCC preflight; exit 1 if not granted May open the system grant flow / helper guide
Linux Wayland Reports the RemoteDesktop portal grant: stored restore token, running session; exit 1 if missing Opens the Share / Allow remote interaction dialog once if no grant is stored, stores it, and keeps the session running. --timeout <seconds> sets the wait for each dialog step (default 300)
Other Not needed; exit 0 Not needed; exit 0
spectre permissions check --json
spectre permissions request

On Linux Wayland, approve once with spectre permissions request; later runs, captures, recordings, and real input open no dialog. Window captures use GNOME Mutter window streams and need no grant of their own. See Linux Wayland consent.

Capture and recording check permission and fail when it is missing. On macOS they never open the grant UI. On Linux Wayland, JUnit test runs never open the dialog themselves. See Recording — macOS TCC.

Unknown commands and options

When a command or option does not exist, spectre exits with code 2 and prints a hint: line on stderr that names the command or syntax that does the job:

Error: no such subcommand sessions
hint: use 'spectre daemon status' to list active sessions, or 'spectre ps' to discover attachable JVMs
hint: run 'spectre --help' to list every command

Common guesses have fixed hints, such as inspect → tree, keys → press-key, daemon stop → daemon kill, and find --text → find-text. Other names are matched against the installed commands.

With --json, a usage error is a JSON object on stderr. hint is null when Spectre has no suggestion:

{"version":1,"error":"no such subcommand inspect","hint":"use 'spectre tree <session>'"}

MCP

Run spectre mcp to give an MCP client access to the UI. Its tools use the same per-user daemon and session IDs as CLI commands.

{
  "mcpServers": {
    "spectre": {
      "command": "/absolute/path/to/spectre",
      "args": ["mcp"]
    }
  }
}

mcp uses standard input and output for protocol messages. Do not wrap it in a command that writes banners or logs to standard output.

If the agent also uses Compose Hot Reload's MCP, see Compose Hot Reload awareness. Use HR MCP to check reload state. Use Spectre to inspect the tree, send input, and capture evidence.

Lifecycle

Step Tool / action
Discover list_processes
Attach attach → retain sessionId
Drive tree / find / input tools / waits
Capture screenshot (inline image), capture (paths on daemon FS), record_* (paths)
Release session detach with session_id ends that session and reports leftover captures, as CLI detach does. Unknown, detached or blank IDs return isError. Other sessions stay attached. Captures remain on disk until explicitly pruned. Use spectre daemon kill only to close all sessions.

MCP sessions remain in the daemon until detach, daemon kill, or daemon teardown. Closing the MCP frontend or its standard streams does not detach a session. Call detach when finished to release session and native resources. The shared daemon remains available for list_processes and new attaches.

Preferred cleanup order (multi-step agents):

  1. record_stop if recording is active
  2. Finish or abandon long wait_for_* calls
  3. detach that session_id

Concurrent tools on a session while detach runs fail closed (actionable errors; no hang). Double-detach is the same fail-closed class as an unknown session.

Tool inventory

Tool inputs use snake_case JSON fields. Successful tools other than screenshot return serialised daemon JSON as text. Errors set MCP isError and include a message.

Tool Required inputs Optional inputs (defaults) Success output shape
list_processes — — { "processes": [ { pid, displayName, … } ] }
attach pid (integer) — { "sessionId", "targetPid" }
detach session_id (non-blank JSON string) — Daemon Detached JSON — see Detach success body below
windows session_id — { "sessionId", "windows": […] }
tree session_id — { "sessionId", "nodes": […] }
find session_id, test_tag — nodes list (exact test tag)
find_text session_id, text exact (default true) nodes list
wait_for_node session_id tag, text, timeout_ms (5000) nodes when matched
wait_until_gone session_id tag, text, timeout_ms (5000) { "sessionId" } completed once nothing matches; isError on timeout, with the selector, timeout, and still-present count in the message
wait_for_visual_idle session_id timeout_ms (5000) { "sessionId" } completed
wait_for_reload_settled session_id timeout_ms (60000) completed; fails if HR inactive
click session_id, node_key — completed
double_click session_id, node_key — completed
long_click session_id, node_key hold_for_ms (500) completed
swipe session_id node pair or coords; steps (12), duration_ms (200) completed
scroll_wheel session_id, node_key, wheel_clicks — completed; positive = down
press_key session_id, key_code modifiers (0) completed; AWT codes as CLI
type_text session_id, text — completed
focus_window session_id window_index (0) completed; only real OS input needs it before keyboard tools
screenshot session_id window_index, surface_id, fullscreen Inline PNG ImageContent; no path is returned. Only fullscreen=true succeeds on attach; window/surface fail closed
capture session_id window_index (0), out_dir, include_image (false) Summary JSON with daemon-local paths (directory, captureJsonPath, screenshotPngPath, counts…). Optional second content part: inline PNG when include_image=true
record_start session_id output_path, window_index (0), fullscreen (false) { "sessionId", "outputPath" } — path only
record_stop session_id — final outputPath
record_status session_id — active, optional outputPath / captureDirectory

Swipe (MCP): pass either from_node_key + to_node_key, or all of start_x / start_y / end_x / end_y. Supplying both forms is invalid.

Example — attach, find, detach:

// tools/call attach
{ "pid": 12345 }

// tools/call find
{ "session_id": "…", "test_tag": "save-button" }

// tools/call press_key  (Ctrl+S)
{ "session_id": "…", "key_code": 83, "modifiers": 128 }

// tools/call screenshot
{ "session_id": "…", "fullscreen": true }

// tools/call capture
{ "session_id": "…", "window_index": 0, "include_image": false }

// tools/call record_start
{ "session_id": "…", "fullscreen": true, "output_path": "/tmp/demo.mp4" }

// tools/call detach  (release session; does not delete files — run pruneCommand if needed)
{ "session_id": "…" }

Detach success body (MCP vs CLI)

MCP detach success content is the daemon’s serialised DaemonResponse.Detached payload (with encodeDefaults, plus the sealed-type discriminator field the codec emits). Field names match the daemon protocol. The CLI human line and CLI --json can have different shapes:

Field MCP detach success CLI spectre detach --json Notes
Session id sessionId id Same value; different key
Leftover count captureCount captureCount Existing ledger dirs for that session only
Leftover bytes captureBytes captureBytes Sum of ledger sizeBytes
Leftover paths capturePaths capturePaths Absolute dirs still on disk
Prune command pruneCommand (when leftovers) pruneCommand e.g. spectre captures prune --session …
Skill hint skillHint (when leftovers) skillHint spectre-capture when leftovers exist

Do not treat MCP text and CLI --json as byte-identical envelopes. CLI human output is a prose line (Detached <id>. plus optional leftover lines). It does not use this JSON shape.

When the session left capture artefacts on disk, captureCount / captureBytes / capturePaths are non-zero and paths are real; pruneCommand and skillHint are populated. Empty sessions report zeros and omit prune/skill. Detach never auto-deletes files. Run the reported prune command (or spectre captures prune …) explicitly. Malformed session_id (missing, empty, whitespace-only, non-string) fails closed at the MCP tool boundary without fabricating a summary.

Full tool row: Tool inventory above. Capture retention and prune flags: CLI capture.

Paths, filesystem, and capture modes (MCP)

  • Screenshot returns image bytes over MCP. Nothing is written for the client to open by path unless the client saves the image itself.
  • capture and record_* write on the daemon host filesystem. Paths in tool results are local to that machine (often $TMPDIR/spectre/captures/… when out_dir / output_path are omitted). They are not automatically transferred over MCP.
  • Shared-filesystem implication: the MCP client process must be able to read those paths (same host, or a shared mount that both daemon and client see). Remote agents without a shared disk only get summaries / inline screenshots. Use include_image=true on capture or screenshot with fullscreen=true when the client needs pixels in-band.
  • Recording never streams video frames over MCP; only the final (or in-progress) path is reported. Ensure spectre-recording-<os> helpers and permissions exist on the daemon host.

The CLI table's capture-mode distinctions also apply to MCP tool names (screenshot vs capture vs record_start).

Requirements and limits

  • ps and attach require JDK 21+ for the CLI and the daemon it spawns, and JDK 21+ in the target JVM. The CLI needs a full JDK with jdk.attach. A JRE lacks the required attach module.
  • Target shape (two paths, one attach command):
  • Preferred — preinstalled spectre-core on the target (instrumented attach). Use this for controlled app builds.
  • Experimental inject — when core is absent and Compose/Skiko is present, the agent runtime can load a nested inject payload. The same attach command supports occasional inspect → detach sessions. High-frequency CI attach loops require preinstalled core. See Agent attach — injection.
  • Start the target JVM with -XX:+EnableDynamicAgentLoading to avoid JDK attach warnings and future incompatibility. The attaching process must be the same OS user as the target.
  • The transport is local-only and trusts the operating-system user account. Use it only for trusted development and test environments.
  • Input commands use the attached target's driver (synthetic AWT events by default; real OS events only if that target opted into RobotDriver()). They can still change application state.
  • Node keys are short-lived. After an interaction changes the UI, run tree / find / find-text / wait-for-node again. On reload-aware sessions, keys are also invalidated after wait --reload-settled completes.
  • spectre wait --reload-settled is meaningful only under Compose Hot Reload; otherwise it fails closed with hotReloadUnavailable. See Compose Hot Reload awareness.
  • Platform capture/recording needs helpers and permissions on the host that runs the daemon (see Recording). macOS: permissions check / request for Screen Recording. Linux Wayland: permissions request once for the portal grant.

For the underlying attach model and its security boundary, see Agent attach.