> ## Documentation Index
> Fetch the complete documentation index at: https://www.osohq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Deploy Oso across your organization via MDM.

Running the installer as root writes to system-level paths that apply to all users on the machine and take precedence over any user-level configuration:

| Component             | Deployment method                                                            |
| --------------------- | ---------------------------------------------------------------------------- |
| Claude Code           | File: `/Library/Application Support/ClaudeCode/managed-settings.json`        |
| Cursor                | File: `/Library/Application Support/Cursor/hooks.json`                       |
| Codex                 | File: `/etc/codex/managed_config.toml`                                       |
| Chrome                | File: `/Library/Application Support/Google/Chrome/policies/managed/oso.json` |
| Claude Desktop Plugin | Manual upload (see [below](#claude-desktop-plugin))                          |

## Claude Desktop Plugin

The Claude Desktop Plugin cannot be deployed via a managed file path. Instead, it must be built and uploaded as an **enterprise plugin** through the Claude Desktop UI.

<Warning>
  The `oso-hook` binary must be present at `/usr/local/bin/oso-hook` on each user's machine for the plugin hooks to fire. The install script must run on every device before or alongside plugin enrollment.
</Warning>

**How it works:**

When the installer runs and Claude Desktop Plugin is selected, it packages a `.plugin` file at `/tmp/oso.plugin`. The plugin contains:

* `.claude-plugin/plugin.json` (plugin metadata)
* `hooks/hooks.json` (hook configuration that invokes `oso-hook` on every session event)

**To deploy to your organization:**

1. Run the installer on any machine to produce the plugin package:
   ```sh theme={null}
   curl -fsSL https://install.osohq.com/install.sh | sudo sh -s -- \
       --env YOUR_ENVIRONMENT_ID \
       --email admin@example.com \
       --force
   # Plugin packaged at /tmp/oso.plugin
   ```
2. Open **Claude Desktop → Customize → Plugins**.
3. Upload `/tmp/oso.plugin` as an enterprise plugin.
4. Mark the default access as `Required` to force install for all users.

## Claude Code

The installer writes Oso hooks to `/Library/Application Support/ClaudeCode/managed-settings.json`, which Claude Code reads as managed policy on every device. This is the standard deployment path and works for most organizations.

```sh theme={null}
curl -fsSL https://install.osohq.com/install.sh | sudo sh -s -- \
    --env YOUR_ENVIRONMENT_ID \
    --email user@example.com \
    --force
```

### If your organization uses claude.ai server-managed settings

If your organization manages Claude Code settings centrally through **claude.ai → Settings → Claude Code**, you should add the Oso hooks there instead of relying on the local `managed-settings.json`.

**The install script must still run on every device** to install the `oso-hook` binary and register the device with Oso.

After running the installer, add the following to your organization's claude.ai managed settings:

```json theme={null}
{
  "hooks": {
    "UserPromptSubmit":   [{"matcher": "", "hooks": [{"type": "command", "command": "/usr/local/bin/oso-hook", "timeout": 5}]}],
    "PreToolUse":         [{"matcher": "", "hooks": [{"type": "command", "command": "/usr/local/bin/oso-hook", "timeout": 5}]}],
    "PostToolUse":        [{"matcher": "", "hooks": [{"type": "command", "command": "/usr/local/bin/oso-hook", "timeout": 5}]}],
    "PostToolUseFailure": [{"matcher": "", "hooks": [{"type": "command", "command": "/usr/local/bin/oso-hook", "timeout": 5}]}],
    "Stop":               [{"matcher": "", "hooks": [{"type": "command", "command": "/usr/local/bin/oso-hook", "timeout": 5}]}],
    "SubagentStop":       [{"matcher": "", "hooks": [{"type": "command", "command": "/usr/local/bin/oso-hook", "timeout": 5}]}]
  }
}
```

For help deploying Oso across your organization via MDM, [contact us](https://www.osohq.com/meet-oso).

## Uninstalling

```sh theme={null}
sudo /usr/local/bin/oso-setup uninstall
```

Reverses a managed install. For shared config files (Claude Code, Cursor, Codex), only
Oso's entries are removed, while other settings are left intact. Files Oso owns outright
(Chrome and Firefox native-messaging manifests, the GitHub Copilot hook, etc.) are removed
entirely. Also removes the identity file, debug logs, and the `oso-hook` and `oso-setup`
binaries from `/usr/local/bin`. It's safe to run more than once.

For the Claude Desktop Plugin, you must separately remove the enterprise plugin through
**Claude Desktop → Customize → Plugins**.

Pass `--keep-logs` to retain debug logs for troubleshooting before uninstalling:

```sh theme={null}
sudo /usr/local/bin/oso-setup uninstall --keep-logs
```