@visiq/claude-code-harness

VisIQ governance for the Claude Code CLI — real-time action monitoring & pre-execution blocking plus retrieval monitoring, blocking and in-context redaction, wired in through Claude Code's native hooks. No fork, no proxy, no source changes to Claude Code.

It is the CLI-coding-agent analog of the VisIQ SDK harness (@visiq/harness) and OpenClaw plugin: a thin adapter over the shared, tagged decision engine (@visiq/runtime UnifiedRuntime) and the @visiq/redact masking primitive.

Install

npm install -g @visiq/claude-code-harness

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

# 2) provide credentials (or set VISIQ_API_KEY / VISIQ_AGENT_ID in the env)
visiq-claude-code configure --api-key <key> --agent-id <id> --base-url https://api.visiqlabs.com

# 3) verify
visiq-claude-code doctor

Now every Claude Code session on this machine is governed by your VisIQ rules.

How it works

install adds three hooks that all invoke one fast dispatcher bin (visiq-claude-code-hook):

| Hook | Matcher | What it does | |------|---------|--------------| | SessionStart | all | Registers the agent (cli_harness) so it shows connected, and pre-warms the on-disk rule bundle so the first tool call evaluates locally. | | PreToolUse | all tools | The enforcement gate. Evaluates the action (+retrieval) facet and returns allow / deny / ask, or rewrites the arguments (arg masking) via updatedInput. deny blocks the tool before it runs. | | PostToolUse | retrieval tools | Re-evaluates the retrieval facet against the returned content and, on a redact/deny decision, replaces the result the model sees via updatedToolOutput — in-context redaction. |

Decisions are computed locally against a signed rule bundle cached on disk, so the hot path is offline-capable and never blocks the agent on the network. The same bundle + evaluator the backend runs is used client-side, so client and server decisions match by construction.

Capabilities

| Capability | Supported | Mechanism | |---|---|---| | Monitor actions in real time | ✅ | PreToolUse sees every tool call (full args) before exec | | Block an action pre-execution | ✅ | permissionDecision:"deny" (blocks even under bypassPermissions) | | Mask action arguments | ✅ | updatedInput rewrites tool_input before exec | | Monitor retrieval | ✅ | PreToolUse (query) + PostToolUse (result) on WebFetch/WebSearch/Read/Grep/… | | Block retrieval | ✅ | PreToolUse deny (pre-fetch) or PostToolUse withhold | | Redact retrieval in-context | ✅ | PostToolUse updatedToolOutput structurally replaces tool_response |

Configuration

Credentials resolve by precedence (highest wins):

1. Env: VISIQ_API_KEY, VISIQ_AGENT_ID, VISIQ_BASE_URL (or VISIQ_ENDPOINT)
2. VISIQ_CONFIG_PATH JSON file
3. ~/.visiq/claude-code/config.json (written by configure)

State (bundle cache, session markers) lives under ~/.visiq/claude-code/ (override with VISIQ_HOME).

Fail modes

• Unconfigured (no credentials): every hook is a no-op — an installed but unconfigured harness never breaks Claude Code.
• Configured, evaluation error / cold-start with no bundle (enforce mode): fail-closed — actions are denied and retrieval content is withheld (G001).
• Monitor mode: decisions are recorded as telemetry but never block.

Uninstall

visiq-claude-code uninstall     # removes only the VisIQ hooks; leaves yours intact

Caveats

• Each hook is a short-lived subprocess (Claude Code's hook model), so there is a small per-tool process-start cost. A future local-daemon transport (type:"http" hooks) will remove it; the current disk-cached-bundle design keeps evaluation local and correct in the meantime.
• Subagent (Task) internal tool calls are governed by the subagent's own hook scope; main-session hooks cover the main loop.