Create a fact-intent graph (like sapper init --goal).

Project + frontier summary text (like sapper status).

Dump the whole graph. format=json gives the structured view, format=text renders the CLI text form.

Integrity-check the graph; returns a list of errors (empty = valid).

List open intents that are ready to work (dependencies met, confirmed). Claimed intents come first.

Pick the next intent to work (like sapper pick).

Record a confirmed fact (like sapper fact).

Add an intent - a unit of work derived from existing facts (like sapper intent --from f001,f002).

Add or list human hints for the agents (like sapper hint).

Show project | fact | intent as JSON.

Read or write a node's detailed doc (title=gist, doc=detail).

sapper_doc(id) returns the doc; pass set or set_file to write.

Find prior facts/intents similar to a free-text gist; read the top hit's doc with sapper_doc to reuse what was learned.

Claim an open intent for a worker.

Release a claimed intent back to open.

Conclude an intent with the fact it produced (atomic, like sapper done <id> --fact "...").

Mark the project goal satisfied, justified by the given facts (like sapper complete --from f001,f005).

Confirm an intent that was created with confirm=True.

Record a captured flag (deduped). With submit=True also sends it via the arena API and updates the fact's status (recorded -> submitted/rejected).

Competition platform bridge (TSecBench-style API).

Actions: init write .sapper/arena.json config template challenges list all challenges start start challenge_id stop close challenge_id submit submit flag for challenge_id hint request hint for challenge_id (may cost score)

Config: env BENCHMARK_BASE_URL + BENCHMARK_TOKEN, or .sapper/arena.json.

Shared offline knowledge base (like sapper kb).

Actions: add target=title; description/detail/tags/commands/source opts search target=query (first tag filters; limit applies) show target=kb id (e.g. kb001) -> full entry list browse entries (tags filter) import target=.md file or dir -> one entry per file root print the kb root dir

Run one commander/executor step via the agent CLI (like sapper dispatch <target>).

Drive a graph toward its goal autonomously: reason -> explore -> optional verify, looping until max-steps, the goal, or the deadline (like sapper auto).

Pick one brainstorm option; siblings from the same batch are concluded with a rejection fact (like sapper brainstorm-pick).

Run any bundled sapper CLI command verbatim (escape hatch).

Opt a project IN: create .sapper/ + register Claude Code hooks in <project_dir>/.claude/settings.json (like sapper setup).

Remove sapper hooks + its AGENTS.md from a project. purge=True also deletes the .sapper/ graph data (destructive).

Discover tmux panes and manage user-authorized AI peers (like sapper peers).

Send a message to a user-authorized tmux peer via load-buffer/ paste-buffer (like sapper send <peer> <msg>).

Capture recent output from an authorized tmux peer (like sapper capture).

Manage the tmux worker fleet (like sapper fleet).

action: init | up | down | status | hire | fire | workers hire/fire take target=; hire also minutes/max_steps/ extra_args.

Field commander loop: LLM allocates the next work slice across per-challenge graphs under root (like sapper command). Runs until deadline/stop - use background=True for real campaigns.

Round-robin driver: every challenge graph under root gets minutes_per of sapper auto per round until deadline (like sapper sweep). Requires minutes or deadline.

TSecBench end-to-end driver: list -> start -> solve -> submit -> close per challenge (like sapper bench). The hosted-mode entrypoint. Use background=True for real runs.

Render the interactive HTML graph visualization (like sapper view). Writes a self-contained snapshot file; set return_html=True to also get the HTML in the response.

One-line status per challenge graph under root - the commander's board (flags sub/rec, intel counts, open intents, last activity).

Generate a markdown engagement report from the graph: summary, flag ledger, typed findings (hosts/services/creds/vulns/loot), work log, timeline, hints. Writes out (default /../sapper-report.md) and returns the markdown.

Run a shell command and return stdout, stderr and exit code.

Run a program with an argument list (no shell interpretation).

Safer than run_command for arguments containing shell metacharacters.

Start a persistent interactive PTY session and return its id.

With command=None spawns an interactive shell. With a command, runs shell -c <command> inside the PTY - ideal for long-running apps, debuggers (gdb), REPLs, or anything needing a TTY. Use write_to_session / read_session_output to interact.

Write input to a PTY session's stdin.

Read output from a PTY session.

Returns only new output since the last read unless all_output=True.

List all active PTY sessions.

Terminate a PTY session (SIGTERM then SIGKILL).

List directory contents with type, size, mode and mtime per entry.

Read a text file by lines.

Read a (binary) file as base64. Capped at 20MB by default.

Write text to a file. Creates parent dirs by default.

Write base64-decoded bytes to a file.

Copy a file or directory tree.

Move/rename a file or directory.

Delete a file or directory. Directories need recursive=True. Destructive: cannot be undone. Protected system paths are refused.

Create a directory (and parents). mode is octal like '755'.

Check whether a path exists.

Detailed stat info: type, size, owner, permissions, times, symlink target, access flags.

chmod/chown a path.

Search files under a path by name glob and/or literal content.

List running processes with pid, name, cpu%, mem%, status, cmdline.

Detailed info for one pid: exe, cmdline, cwd, threads, memory, cpu times, open files, network connections.

Find processes by name (substring on name/cmdline, or exact match).

Start a detached background process (shell command line).

For interactive processes or output capture, use start_shell_session.

Terminate a process. SIGTERM by default, escalating to SIGKILL after timeout. force=True sends SIGKILL immediately.

Kill all processes matching a name. Returns per-pid results.

Send a signal by name (TERM, KILL, INT, HUP, USR1, STOP, CONT, ...) to a process.

Block until a process exits (or timeout).

Show a process and all its descendants.

Overall system snapshot: OS/distro, kernel, uptime, CPU model and load, memory, swap, root disk, logged-in users.

CPU usage percent (samples over interval seconds).

Memory and swap details (total/available/used/cached/buffers).

Disk usage for the filesystem containing path.

Mounted partitions with fstype, usage and IO counters.

Network interfaces with IPs, state, speed, IO counters, default route and DNS servers.

Listening TCP/UDP ports with owning pid and process name.

Environment variables of the linuxmcp process.

mask_secrets redacts vars whose name contains KEY/TOKEN/SECRET/ PASSWORD/PWD - set False to see raw values.

Hardware details via lscpu, lsusb, lspci, lsblk when available.

List systemd service units with load/active/sub state.

Detailed unit status: ActiveState/SubState, MainPID, memory, enablement, plus last status output lines.

Control a systemd unit.

Journal logs for one unit.

Query the systemd journal (journalctl).

Read a log file. tail=True returns the last lines lines; tail=False reads lines lines starting at offset.

List log files under /var/log (or another dir), newest first.

Search available packages by name (apt-cache search).

Package details: version, dependencies, description, install status, candidate version (apt-cache show/policy).

List installed packages (dpkg). filter = name substring.

Install packages via apt-get install -y (sudo).

Remove packages (apt-get remove -y). purge=True also removes config files.

Refresh package lists (apt-get update, sudo).

Upgrade installed packages (apt-get upgrade -y, sudo). full=True runs dist-upgrade. Potentially long-running.

List files owned by an installed package (dpkg -L).

Which package owns a file (dpkg -S).

Read a gsettings value, e.g. schema org.gnome.desktop.interface, key gtk-theme.

Write a gsettings value. value uses GVariant syntax: true/false, 42, 'quoted-string', ['a','b'].

Reset a gsettings key to its default.

List installed gsettings schemas, optionally substring-filtered (e.g. 'gnome', 'zora', 'desktop').

List keys in a gsettings schema.

Describe a gsettings key and its allowed range/values.

Read a dconf key, e.g. /org/gnome/desktop/interface/gtk-theme.

Write a dconf key (GVariant syntax value).

List keys/subdirs under a dconf path (must end with '/').

Desktop session diagnostics: X11 vs Wayland vs headless, which helper tools are installed (xdotool/wmctrl/xclip/...), and what capabilities are available. Call this first if desktop tools fail.

Capture the whole screen; returns a PNG image.

Capture a screen region (x,y top-left, width/height px); returns a PNG image.

Save a screenshot to a PNG file. Region optional (all four of x/y/width/height required to be used).

Screen pixel dimensions and per-monitor geometry.

List all windows: id, desktop, pid, geometry, wm_class, title. X11 only (wmctrl).

The currently focused window (id, title, geometry). X11 only.

Raise and focus a window by id (0x...) or title substring.

Close a window gracefully by id or title substring.

Move/resize a window by id or title substring.

Maximize a window by id or title substring.

Minimize (iconify) a window by id or title substring.

Unmaximize/restore a window to normal state.

Toggle fullscreen state of a window.

Find windows whose title contains the substring (case-insensitive).

Find windows owned by a pid or process-name substring.

Type text as keyboard input (xdotool/wtype). Focus the target window first if needed.

Press a key or combo (xdotool names: Return, Tab, Escape, F5, 'ctrl+c', 'alt+F4'). See key_reference for valid names.

Send a key combination like 'ctrl+alt+t' or 'alt+F4'.

List valid key names and combo examples for press_key.

Move the mouse pointer to absolute screen coordinates.

Current mouse position (X11 only).

Click a mouse button, optionally at coordinates (moves first). button: left | middle | right

Double-click, optionally at coordinates.

Drag with a button held from (x1,y1) to (x2,y2). X11 only.

Scroll the mouse wheel up/down, optionally at coordinates. X11 only.

Read clipboard text (wl-paste/xclip/xsel).

Write text to the clipboard.