Skip to main content
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. 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:
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.
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:
To remove the hook set for a scope, run kontext hooks remove. It defaults to user scope and also accepts --dry-run:
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:
On a self-serve endpoint, doctor shows the user’s Codex paths. For an agent absent from the endpoint, doctor prints:
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 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.