Skip to main content
@visiq/claude-code-harness wires the 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.
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.

​
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): 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).

​
Interactive setup

Install the harness globally, wire the hooks, and provide your credentials:
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.

​
Automated / CI setup

For pipelines and containers, skip configure and supply credentials via the environment — the hooks read them directly:
Optional:
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, 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.

​
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.