Claude Code

What you'll learn: How to add Kyvvu agent security to Claude Code sessions using the kyvvu-claude package.

---

Overview

kyvvu-claude is a standalone Python package that integrates Claude Code into the Kyvvu ecosystem via Claude Code's native hook system. Every tool call (Bash, Read, Write, Edit, etc.) is evaluated against Kyvvu policies before execution, and all tool calls are logged as an immutable behavioral audit trail.

Unlike the SDK integrations (LangChain, CrewAI), kyvvu-claude does not wrap your code — it operates via Claude Code's hook system, so it works with any Claude Code session without code changes.

Installation

pip install kyvvu-claude

Quick start

# Interactive setup — connects to API, registers agent, installs hooks
kyvvu-claude init

You'll need:

• A Kyvvu API key (create one at platform.kyvvu.com)
• Python 3.10+ on macOS or Linux

After init, every Claude Code session is automatically governed.

Architecture

Claude Code                          kyvvu-claude (hook process)
    |                                     |
    +-- SessionStart ──────────────> Fetch policies, start task
    +-- PreToolUse (per tool) ─────> Evaluate policies → allow / deny
    +-- PostToolUse (per tool) ────> Record step in audit trail
    +-- SessionEnd ────────────────> Flush trace to API, end task

Each hook invocation is a separate short-lived process. There is no long-running daemon. Session state (task ID, step history, policy cache) is persisted to ~/.kyvvu-claude/ between invocations.

Policy evaluation flow

1. SessionStart: Fetch policies from the Kyvvu API (filtered by this agent's key). Cache to disk.
2. PreToolUse: Load policies from disk cache. Replay session history into the engine for path-dependent rules. Evaluate the intended tool call. Return allow or deny.
3. PostToolUse: Record the completed tool call in session history. Capture LLM calls from the transcript.
4. SessionEnd: Record task.end. Flush the full behavioral trace to the API.

Enforcement

When a policy blocks a tool call:

1. kyvvu-claude returns permissionDecision: "deny" to Claude Code
2. Claude Code shows the block reason to the user/model
3. The blocked step is recorded in the audit trail with output.status = "blocked"
4. An incident is posted to the Kyvvu API
5. The model continues reasoning (it may try alternative approaches)

Tool blocks deny the specific tool call but do not stop the session. This is consistent with how Claude Code handles permission denials from users.

Tainted-path enforcement

When Claude Code reads a secret file (.env, .pem, .key, etc.), kyvvu-claude classifies it with data.classification: secret. Tainted-path policies then block subsequent dangerous actions:

• No exec after secret read — blocks all Bash after a secret file read
• No network after secret read — blocks file reads outside the project after a secret file read

The taint is permanent within the session. Use /clear in Claude Code to start a new session and reset.

Recommended manifest

Assign the Claude Code Safety manifest to your agent:

manifests/developer/claude-code-safety.yaml

9 policies covering credential exfiltration, destructive commands, scope containment, runaway prevention, and PII scanning. All policies are severity critical (= block).

Configuration reference

All settings are in ~/.kyvvu-claude/config.json, configured during kyvvu-claude init:

Setting	Default	Description
api_url	https://platform.kyvvu.com	Kyvvu API URL
log_location	(same as api_url)	Where logs go: URL, file path, stdout, or none
log_format	kv	Log format: kv, json, or otlp
incident_location	(inherits trace sink)	Where incidents go. Same vocabulary as log_location; empty inherits the trace sink
incident_format	(inherits log_format)	Incident format: kv, json, or otlp. Empty inherits log_format
enforce	false	true = block violations, false = observe only (warn, don't block)
flush_threshold	100	Flush logs every N steps (0 = session end only)

OTLP export

To send traces to an OpenTelemetry collector (Jaeger, Grafana Tempo, etc.):

kyvvu-claude init
# Log location: http://localhost:4318
# Log format: otlp

CLI reference

Command	Description
kyvvu-claude init	Interactive setup
kyvvu-claude install-hooks	Install hooks into Claude Code
kyvvu-claude uninstall-hooks	Remove hooks
kyvvu-claude status	Show configuration and status
kyvvu-claude policies	Display cached policies
kyvvu-claude refresh	Force policy refresh

Compatibility

Works with all Claude Code surfaces:

• Claude Code CLI
• VS Code extension
• JetBrains plugin
• GitHub Actions (anthropics/claude-code-action)

Not supported: Claude Desktop (uses MCP, not hooks).

Troubleshooting

"Policies: 0 loaded" but policies are assigned

The policy cache may be stale. Run:

kyvvu-claude refresh

Agent not appearing in dashboard

Clear the registration cache and re-initialize:

rm -f ~/.kyvvu/registrations/claude-code-*.json
rm -rf ~/.kyvvu-claude
kyvvu-claude init

Hooks not firing

Check that hooks are installed:

grep "kyvvu-claude" ~/.claude/settings.json

If not present, run kyvvu-claude install-hooks.

LLM calls missing from trace

LLM calls are captured from Claude Code's session transcript. In very short sessions (<10 seconds), the transcript may not be flushed to disk before the hook reads it. This is a known limitation.