# kosa8 hooks install

Install kosa8's hook into Claude Code or Cursor

## Usage

```
kosa8 hooks install claude-code|cursor
```

Adds kosa8's hook to the agent's settings, keeping everything else in the file
as it was (other hooks included). The file is backed up to ~/.kosa8/hooks/backups
first; installing again replaces kosa8's entries, and uninstall takes them out.

  claude-code  --scope user     ~/.claude/settings.json
               --scope project  .claude/settings.local.json (not committed)
  cursor       --scope user     ~/.cursor/hooks.json
               --scope project  .cursor/hooks.json

Claude Code: PreToolUse on Bash, PowerShell, Monitor, Read, Edit, MultiEdit, Write,
NotebookEdit, WebFetch, WebSearch and every MCP tool, with "onFailure": "block"
(Claude Code 2.1.295 or later); SessionStart, Stop and SessionEnd are recorded.
Cursor: beforeShellExecution, beforeMCPExecution, beforeReadFile and preToolUse
(Write, Delete) with "failClosed": true; afterFileEdit, sessionStart, stop and
sessionEnd are recorded.

--mode sandbox runs the agent's shell commands in a kosa8 sandbox with the project
mounted at /work (Claude Code's Bash; Cursor's Shell).

Plans: Solo and up; --cloud needs Team and up.

## Flags

| Flag | Type | What it does | Default |
|---|---|---|---|
| `--cloud` | bool | send each decision to kosa8 Cloud's audit log and webhooks (Team plan and up) |  |
| `--image` | string | the image sandbox mode runs shell commands in (default node:22-slim) |  |
| `--mode` | string | check (decide each call) or sandbox (also run shell commands in a kosa8 sandbox) | `check` |
| `--print` | bool | print the settings file as it would be written, and write nothing |  |
| `--project` | string | the project folder, for --scope project and sandbox mode (default: current directory) |  |
| `--scope` | string | user (every project) or project (this folder) | `user` |

---
Source: https://docs.kosa8.com/reference/hooks-install/
