Canonical: https://lean-computer-use.aunysillyme.dev/docs/commands/

Read the source: [desk/README.md](https://github.com/aunysillyme/lean-computer-use/blob/main/desk/README.md)

# Commands

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   ['']` | A JSON object; defaults to `{}` | JSON with tool, driver status, resolved ids, cache status, saved file and short result | 

`desk-read  [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  [--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](https://github.com/aunysillyme/lean-computer-use/blob/main/desk/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 -- ` 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](https://github.com/aunysillyme/lean-computer-use/blob/main/README.md)

## Install where you work

Preview a host and share directory of your choice:

```
npx lean-computer-use install --dir  --share  --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](https://lean-computer-use.aunysillyme.dev/docs/install/) 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 ""`, or install with `--no-stop-gate` to leave it out. See [the stop gate](https://github.com/aunysillyme/lean-computer-use/blob/main/docs/cleanup.md#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  --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 ` 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](https://lean-computer-use.aunysillyme.dev/docs/guides/#measure-your-transcripts).

## 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](https://lean-computer-use.aunysillyme.dev/docs/install/#safe-removal) 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 40
```

command

### 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 Calculator
```

command

### 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 --json
```

command

### 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 --json
```

commands

### 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-run
```

```
npx lean-computer-use uninstall --dry-run
```
