Skip to content

Claude Code CLI and hook configuration

kyvvu claude report

Replay past Claude Code sessions and show what the manifest would flag.

Reads the transcripts Claude Code keeps under ~/.claude/projects and, for each, replays every tool call through the same mapper and engine the hooks use. It fetches nothing, uploads nothing and changes nothing: the replayed sessions never leave the machine.

  • --since: Replay sessions modified within this window (e.g. 30d, 7d, 12h).

  • --project: Limit to one project directory (default: all).

  • --manifest: Replay against this manifest file instead of the configured source.

  • --json: Emit the report as JSON.

kyvvu claude setup

One-step setup: paste one API key, or --local for no account.

With no flags and no KV_API_KEY, the only prompt is a hidden API-key paste; every other value comes from its flag, an environment variable or the default. --monitor turns enforcement into logging; --local configures the integration with no account at all.

  • --local: Configure without an account, enforcing the bundled Claude Code Safety manifest offline. No registration, fetch or upload.

  • --monitor: Monitor only: evaluate and log violations without blocking (sets enforce=false).

  • --manifest: With --local, enforce this manifest file instead of the bundled Claude Code Safety manifest.

  • --fail-mode: Allow failures (open) or deny PreToolUse on failure (closed).

  • --api-url: Kyvvu API URL. Default: kyvvu auth login, else https://platform.kyvvu.com.

  • --api-key: Kyvvu agent API key (Workspace → API Keys). Default: a single hidden paste prompt. Prefer the KV_API_KEY variable: an option is visible in the process list and shell history.

  • --owner: Email of the workspace member accountable for this agent (EU AI Act owner). Default: the API key owner's email, filled in by the platform.

  • --agent-key: Agent key to register under. Default: claude-code--.

  • --environment: development, qa, staging or production. Default: KV_ENVIRONMENT, else production.

kyvvu claude hooks install

Install Claude Code hooks for compliance monitoring.

  • --project: Write to .claude/settings.json in cwd

kyvvu claude hooks remove

Remove Kyvvu's hooks from Claude Code settings.

  • --project: Remove from .claude/settings.json in cwd

kyvvu claude set

Set one Claude integration option in the saved configuration.

kyvvu claude status

Show current kyvvu claude status.

kyvvu claude policies

Display cached policies as a table.

kyvvu claude refresh

Force policy refresh from the API.

Installed hooks

kyvvu claude hooks install merges the following entries into ~/.claude/settings.json, or .claude/settings.json with --project. The command path shown is illustrative; installation uses the script's absolute path.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/kyvvu-claude-hook",
            "timeout": 10
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/kyvvu-claude-hook",
            "timeout": 10
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/kyvvu-claude-hook",
            "timeout": 30
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/kyvvu-claude-hook",
            "timeout": 30
          }
        ]
      }
    ],
    "SubagentStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/kyvvu-claude-hook",
            "timeout": 10
          }
        ]
      }
    ],
    "SubagentStop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/kyvvu-claude-hook",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Saved configuration

Settings live in ~/.kyvvu/integrations/claude-code/config.json. The file has user-only read/write permissions (0600), inside a 0700 directory.

Setting Default Meaning
api_url 'https://platform.kyvvu.com' Kyvvu API base URL (policy fetch + agent registration).
log_location '' WHERE logs go. Empty = same as api_url. "stdout" = print to stderr. "none" / "off" = disabled. Can also be a URL or file path.
log_format 'kv' HOW logs are formatted: "kv" (Kyvvu batch API), "json" (generic JSON), or "otlp" (OpenTelemetry).
incident_location '' WHERE incidents go. Empty = inherit the trace sink (log_location → api_url). Same vocabulary as log_location (URL, file path, "stdout", "none").
incident_format '' HOW incidents are formatted ("kv", "json", "otlp"). Empty = inherit log_format.
api_key '' Kyvvu API key (KvKey-...).
agent_id None Assigned after registration; None means not initialized.
agent_key Generated at setup; see description above. Stable identifier for this machine+user. Defaults to claude-code-<hostname>-<user>; kyvvu claude setup --agent-key overrides it.
owner_id '' Email of the workspace member accountable for this agent (EU AI Act Article 16), sent as owner_id at registration. Empty leaves it to the platform, which uses the API key owner's email.
enforce True True to block violations; False for monitor-only.
fail_mode 'open' "open" allows hook failures; "closed" denies PreToolUse calls when evaluation cannot complete.
environment Generated at setup; see description above. Deployment environment (development/staging/production). A saved value wins; otherwise KV_ENVIRONMENT, else production (the Python client and engine default).
risk_classification 'limited' EU AI Act risk tier for this agent.
session_idle_timeout_seconds 300 Auto-close task after idle period.
policy_sync_interval_seconds 300 Removed (the session's kyvvu serve refreshes policies on its own schedule/#1044). Still accepted for compatibility with installs whose config.json names it; ignored, and load names a non-default value on stderr.
flush_threshold 100 Removed (the engine in the session's serve owns history and export; the hooks keep no journal). Accepted-but- ignored, as above.
flush_interval_seconds 60 Removed, as flush_threshold.
enforcement_history_limit 10000 Removed (the engine bounds the history it enforces over; no hook-side replay window remains). Accepted-but- ignored, as above.
log_full_content False Export full tool input, output, and derived properties when true. When false, export input/output as byte-count and SHA-256 summaries, with only structural tool properties retained.
policy_file '' Path to a local manifest YAML the runner loads policies from, used by kyvvu claude setup --local. Empty means the platform is the policy source. The engine's own precedence applies: a registered agent (with api_key + agent_key) fetches from the platform and this file is ignored, while an unregistered agent with this set loads policies from it with no network. Switching to the platform later (plain kyvvu claude setup) clears it.
template_file '' Path to a behaviour template YAML that replaces the built-in claude-code.template.yaml. Empty means the built-in. Same semantics as the client's KV_TEMPLATE_LOCATION: the file fully replaces the built-in and is loaded once per process. The Claude-side pre-pass (secret classification, Bash write targets) still runs on top of whichever template is loaded. An unreadable or malformed file fails setup/set with the load error.
serve_idle_exit_seconds 3600 How long the session's kyvvu serve runs without a request before stopping itself (--idle-exit). One serve runs per Claude session, and this is the safeguard for a session that dies without sending SessionEnd. A positive whole number of seconds; default one hour.