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

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

# Install

Use Node >=22 to run the installer.
Native app control needs macOS, Python 3 and the separately installed cua-driver.
Follow [the driver precautions](https://lean-computer-use.aunysillyme.dev/docs/install/) 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  --share  --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 `/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](https://lean-computer-use.aunysillyme.dev/docs/guides/) 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](https://lean-computer-use.aunysillyme.dev/docs/install/) for manifest recovery and manual hook cleanup.

Read the source: [docs/cua-driver-install.md](https://github.com/aunysillyme/lean-computer-use/blob/main/docs/cua-driver-install.md)

## Install cua-driver carefully

The upstream driver controls native Mac apps through macOS permissions.
Use [trycua/cua's README](https://github.com/trycua/cua) 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  --app-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](https://github.com/aunysillyme/lean-computer-use/blob/main/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 ` | Hold the session's desktop control for the user; see [the stop gate](https://github.com/aunysillyme/lean-computer-use/blob/main/docs/cleanup.md#the-stop-gate). | 

`npx lean-computer-use install --dir  --share ` | 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 `/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 `/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](https://github.com/aunysillyme/lean-computer-use/blob/main/docs/cleanup.md)). 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.
