# Set up Passlet with your agent

> For AI agents: a documentation index is available at https://passlet.dev/llms.txt

Guide the user through the same four steps as the [human setup guide](https://passlet.dev/get-started/). Passlet gives coding agents temporary, scoped GitHub credentials after the user approves access on their Mac. Agent is an on-demand CLI; Approver is a macOS background service that stores long-lived credentials in Keychain.

Work one step at a time. Reuse an existing installation and completed steps. Explain what you will change before installing software or editing configuration. Browser authorization and Touch ID approval belong to the user: pause at those steps and continue when they confirm completion. Never ask the user to paste credentials, grant contents, or pairing codes into chat.

## 1. Choose the setup

Confirm whether the user uses Claude Code or Codex, and Homebrew or Nix/Home Manager. Check the current machine with `uname -s`, `uname -m`, and, on macOS, `sw_vers -productVersion`. Local setup requires macOS 26 or later on Apple Silicon, a logged-in graphical session, and a GitHub account. Confirm the selected coding tool and package manager are installed. Home Manager plugin options require Home Manager 26.05 or newer.

If you are running remotely or on Linux, do not install Approver there. Have the user complete local setup on their Mac first, then follow [remote Agent installation](https://passlet.dev/docs/getting-started/installation/#install-agent-on-a-remote-machine-or-vm) and pairing.

Check `command -v passlet` and, if present, `passlet --version`. Ask whether GitHub setup and the plugin are already configured before repeating those steps. Do not switch package managers or reset credentials as a repair step. For an existing installation with connection problems, use [troubleshooting](https://passlet.dev/docs/guides/setup/). `passlet doctor` can request native approval, so explain that before running it.

## 2. Install Passlet and the coding-tool plugin

Choose only the user's package manager. Both paths install the local Agent and configure Approver to start at login.

### Homebrew


```sh
brew tap paretosecurity/passlet https://github.com/ParetoSecurity/passlet.git
brew install --cask paretosecurity/passlet/passlet
```

### Nix / Home Manager

Add this input to the user's existing flake:


```nix
passlet = {
  url = "github:ParetoSecurity/passlet";
  inputs.nixpkgs.follows = "nixpkgs";
};
```

In their Home Manager configuration, import the module and enable Passlet with the selected coding-tool plugin. Use only one of these blocks.

#### Claude Code


```nix
imports = [ passlet.homeManagerModules.default ];
programs.passlet.enable = true;
programs.passlet.plugins.claude-code.enable = true;
```

#### Codex


```nix
imports = [ passlet.homeManagerModules.default ];
programs.passlet.enable = true;
programs.passlet.plugins.codex.enable = true;
```

Remove any manually declared Passlet marketplace, plugin entry, or cache link before enabling these options, preserving unrelated plugins.
The `passlet` input must be in scope in that module. Use the configuration's existing module wiring or pass it through `home-manager.extraSpecialArgs`; do not replace the user's flake. Activate with their usual Home Manager or nix-darwin rebuild command from the logged-in Mac session. See [Nix installation](https://passlet.dev/docs/getting-started/installation/#nix--home-manager) for a complete example.

After installation, confirm `passlet --version` works. If installation fails, resolve the error before proceeding.

### Install the coding-tool plugin

For Homebrew installations, use the selected tool’s commands below. Home Manager installs the plugin through the configuration above. The plugin teaches the agent how to request scoped access and reuse approved grants; installing it does not itself grant GitHub access.

### Homebrew installation: Claude Code


```sh
claude plugin marketplace add ParetoSecurity/passlet
claude plugin install passlet@passlet --scope user
```

### Homebrew installation: Codex


```sh
codex plugin marketplace add ParetoSecurity/passlet
codex plugin add passlet@passlet
```

Ask the user to open a new Claude Code or Codex session to make sure the plugin is loaded. Continue with GitHub setup before making the first request.

## 3. Connect GitHub

Run this in an interactive Terminal on the user's Mac, as their normal logged-in user:


```sh
passlet approver github setup
```

If your tool cannot interact with the setup prompts, have the user run the command. Passlet opens the browser to create and install a personalized GitHub App. Guide the user to their personal account for the first setup, review repository access and permissions, and complete GitHub's authorization steps. Organization accounts may need owner approval; follow the setup flow rather than treating a pending request as complete.

Wait for the terminal to report GitHub access enabled and the local Agent paired and connected to this Mac. Local pairing is automatic during successful GitHub setup; do not run a separate pairing flow for it. If setup is cancelled or fails, report that and stop this step. Never infer success from the browser opening alone.

## 4. Make the first approved request

Use this prompt in the session with the Passlet plugin loaded:


```text
Show me the README of my most recently updated private GitHub repository
```

Follow the installed Passlet skill for requesting and using grants. Tell the user what account or repository access is needed and to expect Touch ID or password approval. Discover the latest private repository within the account the user chooses, then request only the permissions needed to read its README. Discovery and reading may require separate approvals. Do not assume a request for one repository covers another.

Reuse a valid scoped grant when it covers the operation. Keep grants in private files and use `passlet exec --grant` as the skill describes. Do not print tokens or fall back to ambient GitHub credentials. If `gh` is unavailable, use the skill's GitHub API fallback. If the Mac is unavailable, approval is denied, or a request times out, stop and let the user decide when to retry.

Confirm completion only after a successful authenticated read. Show which repository was read and its README. If no accessible private repository or README exists, report that accurately and ask the user to choose another repository; do not fabricate a successful example.

## Next steps

- Connect another GitHub organization by running `passlet approver github setup` again and choosing that organization.
- Connect a remote Agent through [Tailscale](https://passlet.dev/docs/guides/setup/#tailscale) or [SSH forwarding](https://passlet.dev/docs/guides/setup/#ssh-forwarding). Install Agent remotely and run `passlet approver pair` on the Mac, following its printed instructions privately.
- Use the Mac's SSH agent for [remote sudo with Touch ID](https://passlet.dev/docs/guides/setup/#using-it-for-sudo-on-linux).
