Skip to main content
Each endpoint gets one set of hooks, depending on how you installed Kontext. Self-serve setup writes files in the home folder. An MDM package writes system files. Kontext changes only its own entries in these files and keeps other hooks and settings. Hooks only work when their agent is on the endpoint. Kontext does not install agents.

​
Self-serve

kontext setup writes these files in the home folder (~) of the person running it. It never asks for a password. For Codex, Kontext writes the hooks to hooks.json and sets [features].hooks = true in config.toml. Codex runs the hooks only after you trust them. Run codex, open /hooks and trust each Kontext hook. Before setup changes a file, it saves a backup beside it with the suffix .kontext-setup-backup-<timestamp>. With a Homebrew install, the daemon checks these files every minute. It restores removed Kontext hooks and, after an update, adds hooks for newly supported agents. To turn Kontext off, run kontext setup --uninstall. Claude Cowork reads only the system Claude Code settings, so a self-serve install does not govern Cowork. Setup, doctor and the endpoint’s agent list show Cowork as not governed. To install or remove these hooks yourself:
user is the default scope. --binary defaults to the Homebrew path of the running kontext. These commands write Codex files to an absolute CODEX_HOME if one is set. kontext setup always uses ~/.codex.

​
MDM package

An MDM package places the binary, installs the hooks in these system files, then starts the daemon. Claude Cowork reads the system Claude Code settings, so an MDM package governs Cowork. If another file exists at Kontext’s Claude Code drop-in path, the install keeps it and reports an error. To install or remove these hooks yourself:
System scope requires root. --binary defaults to /usr/local/bin/kontext.

​
Hook commands

Add --dry-run to kontext hooks install or kontext hooks remove to print the planned changes without writing files. A system-scope dry run does not need root. Removing hooks keeps other hooks and settings. It turns off the Codex hooks feature only if Kontext turned it on. The agent and the rest of Kontext stay 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 paths in the home folder and a Cowork line. 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.

​
Upgrading from an earlier setup

Self-serve setup before CLI 1.17.0 wrote the Claude Code and Cursor hooks to the system files. Those files stay after an upgrade, and the Claude Code drop-in keeps governing Cowork. To remove them, run sudo kontext hooks remove --scope system. kontext setup --uninstall also prints this command.