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:
On Windows, add the Scoop bucket:
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:
- First run on a machine trains a cache before running your command: a
throwaway
spectre --helprecord 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 corruptspectre mcp's protocol stream and--jsonoutput), so every command behaves identically whether or not a cache exists yet; if training fails for any reason, the command simply runs uncached. - Later runs launch with
-XX:AOTCache, skipping class loading/linking and replaying method profiles. In local measurements this roughly halves cold CLI startup (for examplespectre --helpfrom ~330 ms to ~135 ms before the small bootstrap launcher's overhead). - 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:
- 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 launchspectre mcp.
What it can do¶
For a typical session:
- Find a running JVM with
ps, or launch one withspectre launch -- <command>. - Attach it and retain the returned session ID (or hold the launch session open).
- Inspect windows, the semantics tree, or nodes (test tag, text, waits).
- Use a current node key to click, type, swipe, scroll, or press keys, then inspect again.
- Capture a screenshot, atomic capture, or recording when useful.
- 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 |
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:
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.
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):
record_stopif recording is active- Finish or abandon long
wait_for_*calls detachthatsession_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.
captureandrecord_*write on the daemon host filesystem. Paths in tool results are local to that machine (often$TMPDIR/spectre/captures/…whenout_dir/output_pathare 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=trueoncaptureorscreenshotwithfullscreen=truewhen 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¶
psandattachrequire JDK 21+ for the CLI and the daemon it spawns, and JDK 21+ in the target JVM. The CLI needs a full JDK withjdk.attach. A JRE lacks the required attach module.- Target shape (two paths, one attach command):
- Preferred — preinstalled
spectre-coreon 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
attachcommand supports occasional inspect → detach sessions. High-frequency CI attach loops require preinstalled core. See Agent attach — injection. - Start the target JVM with
-XX:+EnableDynamicAgentLoadingto 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-nodeagain. On reload-aware sessions, keys are also invalidated afterwait --reload-settledcompletes. spectre wait --reload-settledis meaningful only under Compose Hot Reload; otherwise it fails closed withhotReloadUnavailable. See Compose Hot Reload awareness.- Platform capture/recording needs helpers and permissions on the host that runs the daemon
(see Recording). macOS:
permissions check/requestfor Screen Recording. Linux Wayland:permissions requestonce for the portal grant.
For the underlying attach model and its security boundary, see Agent attach.