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

# What Kontext installs

> Kontext hook files for Claude Code and Codex, commands to manage them, and doctor checks.

Self-serve setup and MDM packages install the same hooks for Claude Code and Codex. The Kontext CLI manages their contents. Hooks only work when their agent is on the endpoint. Kontext does not install agents when it writes hooks.

## Hook files

Self-serve setup writes the user's Codex configuration. MDM packages write the system Codex configuration. `~` is the home folder of the person running setup.

| Deployment                  | Codex files                                          |
| --------------------------- | ---------------------------------------------------- |
| Self-serve, `user` scope    | `~/.codex/hooks.json` and `~/.codex/config.toml`     |
| MDM package, `system` scope | `/etc/codex/hooks.json` and `/etc/codex/config.toml` |

Kontext writes hooks to `hooks.json` and sets `[features].hooks = true` in `config.toml`.

Claude Code uses one system-wide drop-in for both deployment types:

```text theme={"system"}
/Library/Application Support/ClaudeCode/managed-settings.d/20-kontext.json
```

Claude Cowork uses the same drop-in where it supports hooks. Cowork has no separate hook set. Kontext cannot yet observe Cowork sessions in Anthropic's cloud.

MDM packages place the binary, call the CLI to install hooks, then start the daemon.

Kontext preserves unrelated hooks and settings. Before changing a Codex hook or configuration file, Kontext saves a backup beside it with the suffix `.kontext-setup-backup-<timestamp>`. If another file exists at Kontext's Claude Code drop-in path, Kontext preserves it and reports an error.

## Install or remove hooks

Use `--scope user` or `--scope system` to select the Codex paths in the table. Claude Code uses its system path for both scopes.

```bash theme={"system"}
kontext hooks install --scope user --binary /usr/local/bin/kontext
sudo kontext hooks install --scope system --binary /usr/local/bin/kontext
```

Set `--binary` to the Kontext executable's absolute path. System scope requires root. For user scope, Kontext may request administrator access to write the Claude Code drop-in. The user-scope command uses an absolute `CODEX_HOME` override for Codex files. `kontext setup` always uses `~/.codex`.

Add `--dry-run` to print the planned changes without writing files. You can run a system-scope dry run without root:

```bash theme={"system"}
kontext hooks install --scope system --binary /usr/local/bin/kontext --dry-run
```

To remove the hook set for a scope, run `kontext hooks remove`. It defaults to user scope and also accepts `--dry-run`:

```bash theme={"system"}
kontext hooks remove --scope user
sudo kontext hooks remove --scope system
```

Kontext preserves other hooks and settings during removal. It disables the Codex hooks feature only if Kontext enabled it. These commands leave the agent and the rest of Kontext installed.

## What doctor reports

`kontext doctor` passes the hook check for an agent absent from the endpoint. For an agent on the endpoint, doctor requires valid hooks and an executable Kontext binary. Codex also requires its hooks feature enabled.

On a healthy MDM-managed endpoint, the hook lines look like this:

```text theme={"system"}
Claude Code hooks: installed (/Library/Application Support/ClaudeCode/managed-settings.d/20-kontext.json; binary /usr/local/bin/kontext)
Codex hooks: installed (/etc/codex/hooks.json; binary /usr/local/bin/kontext)
Codex hooks feature: enabled (/etc/codex/config.toml)
```

On a self-serve endpoint, doctor shows the user's Codex paths. For an agent absent from the endpoint, doctor prints:

```text theme={"system"}
Codex hooks: not installed (agent not present)
```

Doctor treats this result as healthy even if an unused hook file exists. Doctor uses the same wording when Claude Code is absent.

For an agent with missing or broken hooks, doctor prints `<Agent> hooks: <error> (<path>)` and marks the check unhealthy. For a missing or disabled Codex hooks feature, doctor prints `Codex hooks feature: <error>`. Doctor also marks system hooks unhealthy if the user's Codex configuration disables hooks.

The endpoint drawer on [Home](/home/overview) shows each agent's hook state as **Installed**, **Missing**, or **Not detected**. To repair hooks on a self-serve endpoint, rerun `kontext setup`. For an MDM-managed endpoint, redeploy the package.

Doctor checks configuration. It cannot check whether Codex trusts the hooks or whether a hook ran. To confirm Kontext receives events, run one tool call and find it in [Explore](/explore/overview).