> ## Documentation Index
> Fetch the complete documentation index at: https://docs.visiqlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code Integration

> Govern the Claude Code CLI through VisIQ action governance, retrieval redaction, and the audit trail with three native hooks.

`@visiq/claude-code-harness` wires the [Claude Code](https://claude.com/claude-code)
CLI into VisIQ's action governance, retrieval governance, and audit-trail layers
using Claude Code's own native hooks — no wrapper, no code changes to your agent.

<Note>
  **Early access.** The Claude Code harness is rolling out now and is not yet
  available on the public npm registry — contact your VisIQ team for access. Once
  you have the package, everything below applies unchanged. A guided setup also
  lives on the **Claude Code** card under **Integration → Connectors** in the
  dashboard, which mints a scoped harness key (`vq_test_` / `vq_prod_`) for you.
</Note>

## What it does

`visiq-claude-code install` adds three hooks to your Claude Code `settings.json`,
all invoking one fast dispatcher bin (`visiq-claude-code-hook`):

| Hook           | Behavior                                                                                                                                                                               |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SessionStart` | Registers the agent with VisIQ and pre-warms the content-addressed rule bundle into a local disk cache, so every later decision is evaluated **locally**.                              |
| `PreToolUse`   | Runs action + retrieval governance before a tool executes. **deny** blocks the call, **ask** routes it to a human approval, and an argument **mask** rewrites the tool input in place. |
| `PostToolUse`  | Applies retrieval redaction to a tool's output before it re-enters the model's context (shape-preserving, so nothing leaks around a discarded override).                               |

Decisions evaluate against the cached bundle in-process; registering a human
approval is the only decision-path network call. New agents auto-provision in
**monitor** mode on first contact: every decision is evaluated and recorded
against your tenant's curated default rule catalog — no rule authoring needed —
but nothing is blocked until you switch the agent to enforce (see
[Go from monitor to enforce](#go-from-monitor-to-enforce)).

## Interactive setup

Install the harness globally, wire the hooks, and provide your credentials:

```bash theme={null}
npm install -g @visiq/claude-code-harness   # registry install lands at GA — early access builds come from your VisIQ team (see the note above)

# 1) wire the three hooks into your Claude Code settings.json
visiq-claude-code install               # → ~/.claude/settings.json (this user)
# visiq-claude-code install --project   # → ./.claude/settings.json (repo-shared)

# 2) save your VisIQ credentials (or set the VISIQ_* env vars — see below)
visiq-claude-code configure \
  --api-key <your-api-key> \
  --agent-id <your-agent-id> \
  --base-url https://api.visiqlabs.com

# 3) verify the wiring, credentials, and endpoint
visiq-claude-code doctor
```

<Note>
  `install` only ever adds or removes the **VisIQ** hooks — it never touches any
  other hooks you've configured. Run `visiq-claude-code uninstall` to remove them
  cleanly. The next Claude Code session you start registers the agent with VisIQ in
  monitor mode on first contact.
</Note>

## Automated / CI setup

For pipelines and containers, skip `configure` and supply credentials via the
environment — the hooks read them directly:

```bash theme={null}
export VISIQ_API_KEY=vq_prod_...
export VISIQ_AGENT_ID=my-agent
export VISIQ_BASE_URL=https://api.visiqlabs.com
visiq-claude-code install --project
```

Optional:

```bash theme={null}
export VISIQ_CONFIG_PATH=/etc/visiq/claude-code.json   # alternate JSON config file
export VISIQ_HOME=/var/lib/visiq   # replaces ~/.visiq/claude-code as the state dir
```

`VISIQ_HOME` replaces the state directory verbatim: with the example above, the
config is read from `/var/lib/visiq/config.json` and cached bundles land in
`/var/lib/visiq/bundles/`.

## Credential resolution precedence

The hooks resolve credentials in this order (highest priority first):

1. Environment variables: `VISIQ_API_KEY` / `VISIQ_AGENT_ID` / `VISIQ_BASE_URL` (or `VISIQ_ENDPOINT`)
2. JSON file at the path in `VISIQ_CONFIG_PATH`
3. `~/.visiq/claude-code/config.json` (written by `visiq-claude-code configure`; override the directory with `VISIQ_HOME`)

## Fail-open vs fail-closed

The harness defaults to **fail-open**: a VisIQ-side failure never disrupts your
agent. Set `VISIQ_FAIL_MODE=closed` (or `failMode: "closed"` in the config
file) if you prefer strict blocking when governance cannot run.

* **Unconfigured (missing credentials)**: every hook is a **no-op**. An installed
  but unconfigured harness never breaks Claude Code — it simply runs ungoverned
  until credentials resolve, so you can install ahead of provisioning. Each
  skipped call notes this on stderr. (In `closed` mode, tool calls are blocked
  until credentials resolve.)
* **Governance evaluation errors / VisIQ unreachable**: the tool call
  **proceeds ungoverned**, and the event is reported loudly — a stderr line plus
  a JSON entry in `~/.visiq/claude-code/fail-open.log` — so ungoverned calls are
  always auditable. (In `closed` mode, a `PreToolUse` error blocks the tool and
  a `PostToolUse` error withholds the retrieved content.)
* **Policy decisions**: a rule that says **deny** always blocks, in both modes —
  fail mode governs harness failures only, never policy outcomes.
* **Telemetry / registration errors**: best-effort and never affect the session.

## Verifying the install

Run `visiq-claude-code doctor` to confirm the hooks are installed and the
credentials + endpoint resolve. Then start a Claude Code session and run any
tool. In the dashboard at [app.visiqlabs.com](https://app.visiqlabs.com), the
agent appears under **Harness → Agents** tagged as a CLI Harness, and the
decision appears in the **Harness → Runtime Enforcement** ledger. Governed
decisions feed the audit trail, including
[signed decision receipts](/record/receipts).

## Go from monitor to enforce

New agents start in **Monitor — Log only**: every decision is evaluated and
recorded, nothing is blocked — so you can review a day of real traffic before
turning anything on. When the recorded decisions look right, open the agent
under **Harness → Agents** and switch its mode to **Enforce — Block**. The mode
is server-authoritative and per-agent; the harness picks it up with its next
rule bundle refresh.