> For the complete documentation index, see [llms.txt](https://docs.kyvvu.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kyvvu.com/integrations/claude-code.md).

# Claude Code

**What you'll learn:** How to add Kyvvu compliance monitoring 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 at the infrastructure level via hooks, so it works with any Claude Code session without code changes.

## Installation

```bash
pip install kyvvu-claude
```

## Quick start

```bash
# 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](https://platform.kyvvu.com))
* Python 3.10+ on macOS or Linux

After init, every Claude Code session is automatically monitored.

## 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` = monitor only                                    |
| `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.):

```bash
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:

```bash
kyvvu-claude refresh
```

### Agent not appearing in dashboard

Clear the registration cache and re-initialize:

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

### Hooks not firing

Check that hooks are installed:

```bash
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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kyvvu.com/integrations/claude-code.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.