# Claude Code

Kind

guide

For

developer · operator

Verified against

@veritio/claude-code@0.4.7 · @veritio/core@0.4.7 · @veritio/storage@0.4.7

The published adapter captures Claude Code through out-of-band hooks. Every invocation writes minimized evidence to the local file store first; an optional ingest target receives the same redacted event and edge inputs.

## Install

[Section titled “Install”](#install)

The adapter runs its published hook with Bun:

Terminal window

```sh
bun add --dev @veritio/claude-code@0.4.7
```

The package pins compatible `@veritio/core@0.4.7` and `@veritio/storage@0.4.7` releases.

## Register all supported hooks

[Section titled “Register all supported hooks”](#register-all-supported-hooks)

Add this to the repository’s `.claude/settings.json`:

```json
{
  "hooks": {
    "SessionStart": [{ "hooks": [{ "type": "command", "command": "bun ${CLAUDE_PROJECT_DIR}/node_modules/@veritio/claude-code/dist/hook.js" }] }],
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "bun ${CLAUDE_PROJECT_DIR}/node_modules/@veritio/claude-code/dist/hook.js" }] }],
    "PreToolUse": [{ "matcher": "Edit|Write|MultiEdit", "hooks": [{ "type": "command", "command": "bun ${CLAUDE_PROJECT_DIR}/node_modules/@veritio/claude-code/dist/hook.js" }] }],
    "PostToolUse": [{ "hooks": [{ "type": "command", "command": "bun ${CLAUDE_PROJECT_DIR}/node_modules/@veritio/claude-code/dist/hook.js" }] }],
    "PostToolUseFailure": [{ "hooks": [{ "type": "command", "command": "bun ${CLAUDE_PROJECT_DIR}/node_modules/@veritio/claude-code/dist/hook.js" }] }],
    "Stop": [{ "hooks": [{ "type": "command", "command": "bun ${CLAUDE_PROJECT_DIR}/node_modules/@veritio/claude-code/dist/hook.js" }] }],
    "SessionEnd": [{ "hooks": [{ "type": "command", "command": "bun ${CLAUDE_PROJECT_DIR}/node_modules/@veritio/claude-code/dist/hook.js" }] }]
  }
}
```

Review the file before enabling it. `${CLAUDE_PROJECT_DIR}` is expanded by Claude Code at runtime; do not replace it with an untrusted path from hook input.

## Configure the process boundary

[Section titled “Configure the process boundary”](#configure-the-process-boundary)

Variable

Default

Responsibility

`VERITIO_LOCAL_DIR`

`~/.veritio/claude-code`

Always-written local evidence directory

`VERITIO_TENANT_ID`

`local`

Tenant on every record

`VERITIO_ACTOR_ID`

`local_developer`

Stable enforcing-human ID

`VERITIO_AGENT_ACTOR_ID`

`agent_claude_code`

Stable agent ID

`VERITIO_ENVIRONMENT`

`development`

Environment scope

`VERITIO_WORKSPACE_ID`

unset

Optional workspace scope

`VERITIO_INGEST_URL` and `VERITIO_INGEST_KEY`

unset

Optional secondary delivery target; both required

`VERITIO_INGEST_TIMEOUT_MS`

`10000`

Upper bound for one ingest POST. Must be an integer from 1 to 30000; values above the ceiling throw at startup

`VERITIO_SPOOL_HARD_BATCHES`

`250`

Hard ceiling on queued delivery batches

`VERITIO_SPOOL_HARD_BYTES`

`50000000`

Hard ceiling on queued delivery bytes

Keep secrets in the host’s secret manager or shell environment, never in `.claude/settings.json` or repository files.

## What is captured

[Section titled “What is captured”](#what-is-captured)

-   `SessionStart`: session event and link to the enforcing human.
-   `UserPromptSubmit`: prompt hash only.
-   `PreToolUse`: pre-image content hash cached for matching edit completion.
-   `PostToolUse` / failure: tool outcome plus before/after hashes for supported edits.
-   `Stop`: git-status scan for Bash-driven file changes missed by edit hooks.
-   `SessionEnd`: final per-session state.

Raw prompts, tool inputs, commands, MCP arguments, file content, and diffs are not persisted by the adapter.

## Outages and backpressure

[Section titled “Outages and backpressure”](#outages-and-backpressure)

The local store is written before optional ship-out. The durable queue lives under `<localDir>/spool/` with `pending`, `held`, and `quarantine` states, and remote delivery has three outcomes:

-   **`retry`** — transport failures, `429`, and legacy `5xx` responses stay in the pending queue.
-   **`pause`** — an explicit server pause (including recognized legacy quota codes) opens a sticky circuit and moves the whole queue to held. Later hooks append locally and make **zero** remote attempts.
-   **`reject`** — permanent failures move to quarantine with the redacted payload intact. They are never silently deleted.

Ordinary hook invocations **never replay a backlog**. Recovery requires a separate operator command, and every replay epoch is bounded by batches, records, encoded bytes, and elapsed time — so an endpoint recovery or quota upgrade cannot turn routine hooks into an uncontrolled egress drain.

The hard ceiling is 250 batches or 50 MB (`VERITIO_SPOOL_HARD_BATCHES` / `VERITIO_SPOOL_HARD_BYTES`). At the ceiling, **existing entries are retained**, pending entries move to held, and the **newest** remote-delivery copy is refused with a visible stderr signal — evidence already captured is never dropped to make room. The hook exits `0`, so capture is deliberately fail-open for the coding session.

Local evidence may exist even when the hosted destination is behind. Inspect and control delivery with the operator CLI shipped in this package:

Terminal window

```sh
veritio-claude-code-spool status
veritio-claude-code-spool pause --reason "provider transfer alarm"
veritio-claude-code-spool quarantine
```

## Query through MCP

[Section titled “Query through MCP”](#query-through-mcp)

Register the read-only MCP server against the same directory:

```json
{
  "mcpServers": {
    "veritio-provenance": {
      "command": "bun",
      "args": ["/absolute/path/node_modules/@veritio/claude-code/dist/mcp.js"]
    }
  }
}
```

It exposes `veritio.list_sessions`, `veritio.get_session`, and `veritio.export_session`. Start with a test repository, inspect one session, and verify the exported bundle before enabling optional remote delivery.

For the event model and privacy checklist, read [Agent events](/docs/ai/agent-events/).

[Edit page](https://github.com/getveritio/veritio-website/edit/main/src/content/docs/docs/ai/claude-code.md)

Last updated: Aug 23, 2026

[Previous  
AI gateway](/docs/ai/gateway/)[Next  
Codex](/docs/ai/codex/)

Veritio provides evidence support, not legal advice or automatic compliance.

This site uses cookieless, anonymous analytics (Umami) by default. With your consent, we also enable Google Analytics, which sets cookies and sends usage data to Google. [Privacy Policy](/legal/privacy/)