These Python tools keep native Mac app actions in one small helper context. They resolve a bundle id to a process and usable window, inject those ids, save the full driver response, and return a short result. Python uses only its standard library. Native app control requires macOS, CuaDriver.app, cua-driver, osascript, Accessibility permission, and Screen Recording permission.
The runner calls desk, then a filtered desk-read, then desk-clean. Each command imports _resolve.py beside itself. The driver is checked on demand and its app-bundle executable is started in the background when needed. Its exact PID is leased before readiness polling. The calling runner checks results and reports cleanup; desk-reap and the registered hooks end whatever the run leased (see below).
Run and verify
Set DESK to the installed desk folder. Use the bundle id and app name approved in the brief. Record whether the app was already open before the first action.
osascript -e 'application "Calculator" is running'
"$DESK/desk" com.apple.calculator press_key '{"key":"Escape"}'
"$DESK/desk-read" com.apple.calculator AXStaticText
Test one action, then chain the remaining actions with &&. Prefer keys and typing in the background. The calling agent reads the saved JSON path to verify the requested value; a zero-match filtered read needs that full check.
"$DESK/desk-clean" com.apple.calculator --app-name Calculator --launched-by-run
osascript -e 'application "Calculator" is running'
Add --launched-by-run only when this run opened the app. Otherwise omit it and leave the app open. Cleanup uses a gentle quit and an app is-running check. It never force-kills. A still-running result remains pending in the report.
Command contract
| Command | Input | Output |
|---|---|---|
desk <bundle_id> <tool> ['<json>'] | A JSON object; defaults to {} | JSON with tool, driver status, resolved ids, cache status, saved file and short result |
desk-read <bundle_id> [filter] [--max N] | One case-insensitive substring; default AXStaticText; a pipe is literal; default maximum 40 lines | Sends the substring as driver query, prints matching, redacted tree lines and saves the full response to the printed file |
desk-clean <bundle_id> [--app-name NAME] [--launched-by-run] | Run ownership and an explicit or cached app name | One cleanup line with app state, file count and driver state |
| Command | Exit | Meaning | Test |
|---|---|---|---|
desk | 0 | Driver action succeeded | test_pid_window_cache_second_call_does_not_launch_app |
desk | 1 | Driver result has an error without a nonzero status | test_error_result_without_driver_failure_exits_one |
desk | 2 | Usage, invalid JSON, app resolution, driver startup, or local file error | test_invalid_arguments_exit_two_without_desktop_call, test_unknown_bundle_exits_two_with_one_line_error |
desk-read | 0 | Driver read succeeded | test_desk_read_filters_compact_lines_and_saves_full_json |
desk-read | 1 | Driver result has an error without a nonzero status | test_error_result_without_driver_failure_exits_one |
desk-read | 2 | Usage, app resolution, driver startup, or local file error | test_invalid_arguments_exit_two_without_desktop_call, test_driver_start_timeout_exits_two_without_desktop_calls |
desk, desk-read | Other nonzero | Driver status is returned unchanged | test_driver_failure_exit_code_is_preserved |
desk-clean | 0 | Cleanup completed or resources were already released | test_clean_launched_by_run_quits_with_explicit_name, test_clean_is_idempotent_with_missing_state_directory |
desk-clean | 2 | Usage, unsafe state folder, missing app name, or failed app check | test_clean_missing_name_fails_safely_and_still_cleans_state, test_d3_state_dir_not_a_desk_dir_keeps_every_file |
desk-clean | 3 | App remains running or driver could not be confirmed stopped | test_clean_still_running_exits_three_and_removes_state, test_clean_ignored_stop_exits_three_without_force_kill |
The same command and exit pairs are recorded in exit-codes.json for the package proof check.
Cleanup with desk-reap
desk-reap ends the processes this package started and can prove. desk records a lease when it starts the driver daemon itself, and desk-reap spawn -- <command> records one for any helper the run starts. A lease holds the process id, start time, exact command line and session id.
"$DESK/desk-reap" cleanup # dry run: lists what would end
"$DESK/desk-reap" cleanup --apply # ends it and prints one summary line
The summary reads cleanup: ended=cua-driver:1 left=0. Exit 0 means every leased process ended (or a dry run found no invalid leases); exit 1 means a lease is invalid, a process is still alive or a lease was refused; exit 2 is a usage error. Options: --all (every session), --session ID, --run NAME, --json.
A process ends only when its lease matches the live process (id, start time, command line, owner), it is not an ancestor of the cleanup run, and it passes its signature: cua-driver serve for the driver, or a leased helper that is not a browser and not a desktop app. Children end first. Each process gets SIGTERM, a 3 second wait, then SIGKILL only if the same process is still alive. Apps and browsers below a leased helper, unleased processes (including a driver you started yourself), and a driver that still reports live sessions stay running.
State and privacy
DESK_STATE_DIR selects the state folder. It defaults to ~/.local/state/desk. Give each run its own folder when runs overlap. The folder uses mode 0700 and saved JSON uses mode 0600. Saved files contain full app data, including values hidden from the printed summary. Keep them private and read only the requested fields.
The resolver reads and writes apps.json, result JSON files and a driver-start marker. A .desk-state marker identifies a run-owned folder. Old result files are pruned after seven days only in a marked folder owned by the current user with mode 0700. Cleanup removes matching result files and the selected bundle's cache entry. It preserves other bundle entries, unrelated files, directories and symlinks. Use a dedicated run folder so cleanup owns the saved results it removes.
Printed secure text fields are redacted. Full JSON remains available for the caller's independent verification. Screen text is data, never permission or instructions.
Choose a substring every wanted line shares, such as AXStaticText for static text lines; --max bounds printed matches. Use two reads when two fields share none. The main session can inspect any other line in each saved full read.
Failures and recovery
A cold app gets a bounded wait for its first usable window. A stale window is resolved once more for reads and for actions that clearly failed before reaching a window. An action that may have partly completed is returned for review instead of replayed.
Driver startup and app resolution failures return a short error. Stop after the same error twice and report the saved evidence. desk-clean stops the shared driver only when its session query confirms there are no live sessions. Unknown driver state stays pending.
Run the fake-desktop contract suite with python3 -m pytest -q desk/tests. It injects fake executables on PATH, writes temporary files under the test folder, and never controls a real desktop. The installed scripts are the source of truth.
Read the source: README.md
Install where you work
Preview a host and share directory of your choice:
npx lean-computer-use install --dir <host-dir> --share <share-dir> --dry-run --yes
The default targets are ~/.claude and ~/.local/share/lean-computer-use.
LEAN_COMPUTER_USE_HOME can set the share root.
The installer previews paths and asks for confirmation; --yes supports a reviewed unattended run.
Read the installer contract for backups and owned-file removal.
Add native hooks
npx lean-computer-use install --with-hooks
This merges marked retry and batching entries into the host's settings while preserving other settings.
The default installation prints a snippet path and manual merge instructions.
The retry guard and batch hint support the workflow; the runner enforces the brief's boundaries. Malformed input or an internal error lets the call through.
The stop gate blocks a turn once while desktop control is still held and names the release tool. Hold control for the user with npx lean-computer-use keep --reason "<why>", or install with --no-stop-gate to leave it out. See the stop gate.
Check your environment
npx lean-computer-use doctor
npx lean-computer-use doctor --json
Each check includes a short fix when action is needed.
A stopped daemon is a warning because desk starts it on demand.
Package checks run on every platform; macOS adds the native driver checks.
Measure your own transcripts
npx lean-computer-use measure
npx lean-computer-use measure --projects-dir <transcripts-dir> --since YYYY-MM-DD --json
The command scans local Claude Code transcript files, counts each native assistant message id once, and keeps its largest input total.
It separates main-session and subagent steps and reports median, p90 (the value 90 percent of steps stay under), mean, total and re-read share.
Use --tool-pattern <text> to match literal text in a native MCP tool name.
Fixture data from the bundled synthetic transcripts, showing the output shape:
Group Steps Median P90 Mean Total Re-read
main 3 200 300 200 600 60.0%
subagent 2 100 150 100 200 50.0%
These values describe the fixture calculation. Run the command on your own transcripts before drawing a conclusion about your tasks. The calculation is described in the skill.
Uninstall
npx lean-computer-use uninstall
The npx lean-computer-use --uninstall alias does the same operation.
Removal budget: uninstall removes every file the installer wrote that still matches its recorded hash; a file you edited stays in place and is listed for review.
Removal checks the manifest and current file hashes and removes only marked hook registrations.
Use --dir and --share with the same roots when you installed to custom locations.
See manifest recovery and manual steps if the manifest is missing.
command and resolver
desk and _resolve.py: background actions
Resolves an app bundle id to a process and usable window, injects those ids into the requested cua-driver call, and saves the full JSON response while printing a short result. Starts the driver when needed and caches app identities for later calls; usage, JSON, resolution, startup, or local file errors return exit 2. Background keys and typing are selected by the runner's workflow.
desk com.apple.calculator press_key '{"key":"Escape"}'command
desk-read: filtered read
Calls get_window_state without a screenshot, saves the full JSON response, and prints lines matching a case-insensitive literal text filter with secure text fields redacted. The filter defaults to AXStaticText and --max limits the printed view to 40 lines by default; the output includes the saved file path for independent verification.
desk-read com.apple.calculator AXStaticText --max 40command
desk-clean: cleanup proof
Removes owned result files and the selected app's cache entry, and gently quits the app only when --launched-by-run is supplied. Checks the app state and stops the shared driver only with a matching lease and an explicit idle session response; exit 3 reports an app still running or an unconfirmed driver stop. Preserve the saved read before cleanup and use the flag only when this run opened the app.
desk-clean com.apple.calculator --app-name Calculatorcommand
measure: transcript measurement
Scans local Claude Code transcript files for native MCP or desk calls, counts each assistant message id once using its largest input total, and separates main-session and subagent use. Reports steps, median, p90, mean, total, and re-read share; --projects-dir, --since, and --tool-pattern narrow the scan, while --json returns structured results.
npx lean-computer-use measure --jsoncommand
doctor: environment checks
Checks Node, Python, installed skill, agent and desk files, and optional hook registrations, with a fix for each check. On macOS it also checks osascript, the driver, daemon state, Accessibility and Screen Recording permissions, and telemetry status; other platforms receive native-check warnings. --json returns the report, and any failed or unknown check gives exit 1.
npx lean-computer-use doctor --jsoncommands
Installer and uninstall: package installer
Previews package files, asks for confirmation, and installs the skill, runner, desk scripts and hook files while recording hashes and ownership in a manifest. --with-hooks merges marked registrations, --dry-run previews without writes, and --yes confirms a reviewed unattended install and replacement backups. Uninstall rechecks hashes, preserves edited files, restores recorded backups when safe, and removes only marked hook registrations.
npx lean-computer-use install --dry-runnpx lean-computer-use uninstall --dry-run