Use Node >=22 to run the installer. Native app control needs macOS, Python 3 and the separately installed cua-driver. Follow the driver precautions before granting system permissions.
npx lean-computer-use
npx lean-computer-use --uninstall
The first command previews its changes and asks for one confirmation.
The second is the removal alias; npx lean-computer-use uninstall is equivalent.
The installer copies the skill and runner to ~/.claude and the desk tools and hooks to ~/.local/share/lean-computer-use.
The brief template is installed with the skill at ~/.claude/skills/lean-computer-use/desk-brief.md.
It does not install the driver or perform a vendor login.
Preview a custom target without writing:
npx lean-computer-use install --dir <host-dir> --share <share-dir> --dry-run --yes
--dry is an alias for --dry-run.
Use --yes for an unattended install after reviewing the plan.
LEAN_COMPUTER_USE_HOME sets the share root when --share is absent.
A differing existing file needs --yes to replace it; the installer keeps a .bak copy.
Optional hooks
npx lean-computer-use install --with-hooks
This merges marked registrations into <host-dir>/settings.json after a backup.
Other settings and hooks remain in place.
Repeated installation keeps one copy of each registration.
Without this flag the installer prints the installed settings-snippet.json path and merge instructions.
For a manual merge, replace the hook-directory placeholder as instructed, append the snippet's event entries to the matching hooks arrays, and retain existing entries.
Restart the host after changing hooks, then run npx lean-computer-use doctor.
Activate
Start a fresh host session so it can discover skills/lean-computer-use/SKILL.md and agents/desk-runner.md.
Ask: "Use lean-computer-use. Give desk-runner one Calculator task, verify the saved filtered read, and report cleanup."
Review the brief template before handing an agent an app task.
Other hosts
Copy skills/lean-computer-use/ to the host's documented skill directory and point its runner at the desk tools.
Copy briefs/desk-brief.md into that skill directory as desk-brief.md.
The automatic installation target is Claude Code.
Remove
npx lean-computer-use uninstall --dry-run
npx lean-computer-use uninstall
Removal uses the install manifest and preserves user-edited files. Read the installer contract for manifest recovery and manual hook cleanup.
Read the source: docs/cua-driver-install.md
Install cua-driver carefully
The upstream driver controls native Mac apps through macOS permissions. Use trycua/cua's README for its current installation command and supported release. This package does not bundle or install cua-driver. The vendor release, checksum and command behavior below are UNVERIFIED for your installed version until you check them locally.
Verify the download
Compare the downloaded artifact with a checksum published by the upstream project when one is available. Confirm the signature's identity against upstream release information. For the app bundle, use Apple's signature and notarization checks:
codesign --verify --deep --strict /Applications/CuaDriver.app
spctl --assess --verbose /Applications/CuaDriver.app
Resolve a failed assessment before granting permissions. These commands verify the local artifact; a successful check alone does not establish that it is the release you intended to download.
Check telemetry and permissions
Inspect the commands offered by your installed version:
cua-driver --version
cua-driver telemetry --help
cua-driver telemetry status
cua-driver permissions status --json
Disable telemetry with the installed version's supported command (cua-driver telemetry disable when listed), then check cua-driver telemetry status again.
The exact disable subcommand is UNVERIFIED until confirmed by your local help output.
Grant Accessibility and Screen Recording deliberately:
cua-driver permissions grant
cua-driver permissions status --json
cua-driver status
Confirm that accessibility and screen_recording are true.
Review macOS System Settings if the permission command opens a settings pane.
Keep credentials and other sensitive content out of app briefs.
Use and close
desk starts CuaDriver through LaunchServices with open -g -a /Applications/CuaDriver.app --args serve so macOS attributes Accessibility and Screen Recording to com.trycua.driver. It snapshots live driver PIDs before launch and polls for exactly one new PID, recording its start time and command for cleanup. Rounded start times never decide ownership. Readiness timeout keeps a discovered new PID leased; absent or ambiguous new PIDs leave all drivers unleased and running. Verify permissions against your installed vendor build.
After a run, call desk-clean <bundle> --app-name <Name>.
Add --launched-by-run only when the initial snapshot showed the app closed and this run launched it.
This requests a gentle quit, removes owned desk state and stops a provably leased driver when no live sessions remain. A driver started independently stays running.
An app that remains running is a pending cleanup result; keep its unsaved work safe and report it.
Use npx lean-computer-use doctor to check the installation and receive one-line fixes.
On other platforms the driver checks are warnings and package checks still run.
Read the source: docs/INSTALLER.md
Installer contract
Commands
| Command | Behavior |
|---|---|
npx lean-computer-use | Preview an install and ask for confirmation. |
npx lean-computer-use install --yes | Apply the previewed install without a prompt. |
npx lean-computer-use install --with-hooks | Also merge marked native hook registrations. |
npx lean-computer-use install --with-hooks --no-stop-gate | Merge the hooks without the touch and stop gate entries. |
npx lean-computer-use keep --reason <text> | Hold the session's desktop control for the user; see the stop gate. |
npx lean-computer-use install --dir <path> --share <path> | Use explicit host and share roots. |
npx lean-computer-use uninstall | Remove unchanged files recorded in the manifest. |
npx lean-computer-use --uninstall | Alias for uninstall. |
npx lean-computer-use install --dry-run | Show the same action plan with no writes. |
npx lean-computer-use uninstall --dry | Preview removal; --dry equals --dry-run. |
Default host root: ~/.claude.
Default share root: ~/.local/share/lean-computer-use.
LEAN_COMPUTER_USE_HOME overrides the default share root; --share takes precedence.
--dir and --share may name absolute target roots.
Recorded paths inside each root must remain relative, contained and free of symlinks.
Install ownership
The installer writes the skill under skills/lean-computer-use, the runner under agents/desk-runner.md, and desk tools and hook files under the share root.
It copies packaged briefs/desk-brief.md to <claude dir>/skills/lean-computer-use/desk-brief.md as an owned skill file, with the same hash, backup and removal rules.
It replaces __DESK_DIR__ in the runner with the installed desk directory.
Desk scripts are executable.
It records paths, file hashes and created directories in <share>/install-manifest.json.
Before changing backups or payloads, it writes a pending manifest and updates ownership before each file write.
The pending manifest records each staging path before creating it.
File and manifest replacements are atomic, so a failed write keeps the prior file intact.
An interrupted install remains pending: run uninstall with the same --dir and --share roots, then install again.
Recovery removes matching installed files, restores recorded originals and keeps user edits and earlier backups for review.
An upgrade records the previous installed hash until completion, so recovery also recognizes files it had yet to replace.
Recovery removes complete or partial staged bytes only when they match the recorded package payload or original backup source.
A changed staging source keeps the temporary file, reports its exact path for review and lets recovery continue.
Changed staging contents with a matching source keep the pending manifest for review.
The installer previews before mutation and asks y/N unless --yes is supplied.
A non-interactive install requires --yes.
A differing existing file is preserved unless replacement is approved with --yes; replacement keeps a .bak.
The manifest records enough ownership information to preserve or restore prior content on removal.
The installer never installs third-party tools, runs vendor logins, or changes global settings without confirmation.
Hook merge
--with-hooks backs up settings.json, preserves all other keys and registrations, and adds marked entries idempotently, including the cleanup entries for SubagentStop, Stop and SessionEnd and the stop gate entries (see cleanup). The manifest records whether the stop gate was chosen, and doctor expects that set.
MCP native tools and Bash have separate matchers.
The Bash handler checks that the first word of a command segment is desk, desk-read or desk-clean before it applies native behavior.
Uninstall removes only entries carrying this install's marker.
If the snippet was pasted manually, inspect the printed manual steps and remove only those pasted entries yourself.
Safe removal
Uninstall reads the manifest and rechecks each target before unlinking it. 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. Traversal, absolute recorded paths and symlink targets are refused. It removes a directory only when this install created it and it is empty. The manifest is removed last. Backups of replaced content are restored according to their recorded ownership.
--dry-run performs the same validation and reports the same planned actions without writing.
With no manifest, uninstall exits 2 and names the missing manifest path.
Restore the manifest from your backup or follow its reported manual cleanup steps after reviewing each file.
Do not delete a shared skill directory or an entire settings file as a substitute.
Verification
test/installer.test.mjs exercises temporary roots, dry runs, replacement backup, settings merge, edited-file preservation and install/uninstall restoration.
npx lean-computer-use doctor --json compares installed files with the package and reports optional hook registration.
For a custom installation, pass the same --dir and --share values to doctor.
All tests use temporary paths and fake commands.