Claude Cowork Integration

Pre-GA — not yet generally available. The Claude Cowork card under Integration → Connectors stays disabled until a Cowork-specific canary proves the connector on main. The npm package is published, so the install command below works — but latest tracks main, which can sit behind the fixes already on the integration branch.

Prerequisites. A VisIQ account (sign in) with a harness key from Settings → Harness Keys, and the Claude desktop app. This harness governs Cowork’s own agent, so no separate model key is needed here. Hitting an error? See Troubleshooting.

@visiq/claude-cowork-harness brings VisIQ governance to Claude Cowork, the agent surface in the Claude desktop app.

Read this before you rely on it. Cowork runs a session in one of two places, and the difference decides what governance is possible. VisIQ covers both, but not equally — and the harness reports which is which rather than averaging them into one reassuring number.

The two surfaces

Surface	Where it runs	What VisIQ does	How
Host-local	The desktop app spawns its own `claude` natively on the machine	Enforcement — action + retrieval governance; a `deny` stops the tool call before it runs	Claude Code hooks (`SessionStart`, `PreToolUse`, `PostToolUse`)
VM sandbox	The session runs inside the app’s Linux guest	Monitoring — every tool call, its arguments, the model, and the sandbox’s own allow/deny answer for each call	Tailing the host-side per-session audit stream

A sandboxed session’s configuration lives inside the guest and carries no settings.json, so no host hook can fire for it. The audit stream VisIQ tails for those sessions is written after a tool has already run. VisIQ therefore never reports a block on the sandbox surface, and status says so explicitly.

If an AI coding agent is doing this install

These are its rules — the same guardrail VisIQ prepends to every setup prompt the platform generates. They are here because this page is one an agent gets pasted, and because a step below really can fail: latest tracks main, so it can lag the fixes already on the integration branch. Improvising around a failed step is how an agent ends up building a CLI from source and patching the very harness it was sent to install. Rules for the AI agent running this setup — read these first:

Apply ONLY the changes this prompt explicitly shows: its commands, its environment/config values, and its exact code snippet(s), if any. Nothing else may be written, edited, or patched — not code, not packages, not configuration.
Never improvise a workaround when something fails: no building from source, no packing tarballs, no PATH shims or alternative registries, and no debugging or patching the VisIQ software itself.
If any command fails, is unavailable, or produces output that differs from what this prompt describes, STOP and report the exact command plus its full output back to your operator. A partial install is a safe no-op by design — leaving it unfinished is always correct; an unauthorized fix never is.
Do the steps below IN ORDER, and after each one run the Check: command it shows and confirm the output before moving on. NEVER report the setup complete based on what you intended to do — only on what a check actually showed. If a check does not show what it describes, the step is not done.
Reading is always in scope. Inspect these commands, the URLs they call and the integrity checks they run BEFORE executing anything, and tell your operator what you found. These rules bound what you may CHANGE, never what you may examine — if something here looks wrong, refusing to run it and saying why is the correct outcome, not a failed setup.

Install

Install the harness

# Install BOTH: the Cowork harness, and the Claude Code harness whose
# `visiq-claude-code` binary owns the shared credential command used in step 3.
# The cowork package depends on it, but a dependency does not put a binary on
# your PATH — only a direct global install does.
npm install -g @visiq/claude-cowork-harness @visiq/claude-code-harness

Check: run visiq-claude-cowork status. Its dispatcher: line must end in a real path — → NOT FOUND on PATH means only one of the two packages landed, and every tool call will run ungoverned.

Wire the hooks (host-local enforcement)

visiq-claude-cowork install

This writes the governance hooks into ~/.claude/settings.json.Check: visiq-claude-cowork status now reads hooks: installed — <your settings.json>. not installed means the write did not happen.

Set credentials

visiq-claude-code configure --api-key <harness-key> --agent-id <agent-id>

Credentials are shared with @visiq/claude-code-harness — mint the key under Settings → Harness Keys.Check: visiq-claude-cowork status now reads credentials: resolved and shows the agent id: you passed. While it reads MISSING the hooks are wired but every one of them silently no-ops.

Point at your control plane (optional)

--api-key and --agent-id are the two REQUIRED values. The endpoint is optional and defaults to the VisIQ cloud (https://api.visiqlabs.com). If you run a sovereign / self-hosted / on-prem VisIQ, set it — otherwise this harness reports every governed tool call to the VisIQ SaaS control plane rather than your own:

visiq-claude-code configure \
  --api-key <harness-key> \
  --agent-id <agent-id> \
  --base-url https://visiq.internal.example.com   # OPTIONAL (defaults to the VisIQ cloud)

# or via the environment
export VISIQ_BASE_URL=https://visiq.internal.example.com   # OPTIONAL

Resolution is the Claude Code harness’s own, so VISIQ_API_KEY / VISIQ_AGENT_ID / VISIQ_BASE_URL behave exactly as in the Claude Code quickstart.Check: visiq-claude-cowork status still reads credentials: resolved. If you skipped this step, skip the check with it — the default is the VisIQ cloud, which is correct for every VisIQ SaaS account.

Restart the Claude desktop app

Hooks are read when a session starts.Check: nothing to run here — the two coverage lines in the next step are what say whether the restart took effect.

Confirm what is covered

visiq-claude-cowork status

[VisIQ] Claude Cowork harness 0.1.10 — status
  this process:       unknown (cannot enforce)
  credentials:        resolved
  agent id:           agent_01HQ7ZK3M4N5P6R7S8T9V0W1X2
  hooks:              installed — /Users/you/.claude/settings.json
  dispatcher:         visiq-claude-code-hook → /usr/local/bin/visiq-claude-code-hook
  Claude Cowork (host-local): ENFORCED (PreToolUse deny blocks)
  Claude Cowork (VM sandbox): monitor-only — 3 session(s), 5 audit log(s), all observed
  session tree:       /Users/you/Library/Application Support/Claude/local-agent-mode-sessions
  monitor state:      /Users/you/.visiq/claude-cowork/monitor-state.json

That block is not hand-written. packages/visiq-claude-cowork-harness/__tests__/readme.e2e.test.ts builds exactly the state it depicts, runs the built CLI against it, and requires this page — and the package README — to match what came back. Only the four absolute-path values are exempt (they differ per machine and per OS); every label, every count and the version are bound.ENFORCED is claimed only when BOTH are true: a VisIQ hook is wired under PreToolUse and the dispatcher: line resolved to a real executable. Hooks present in settings.json with a dispatcher missing from your PATH mean tool calls run ungoverned, and status says exactly that instead.this process: is the surface the command itself is running on — not a coverage line. Run from a normal shell it reads unknown (cannot enforce), because the visiq-claude-cowork process has no claude binary in its own ancestry to classify; run from inside a sandboxed session it reads Claude Cowork (VM sandbox) (cannot enforce). Neither says anything about whether your Cowork sessions are governed — the two coverage lines below it do.

Monitoring sandboxed sessions

Enforcement is not available inside the sandbox, but visibility is. Run the monitor to report every sandboxed tool call to VisIQ:

visiq-claude-cowork monitor            # long-running, polls every 15s
visiq-claude-cowork monitor --once     # single pass, for a cron/launchd job

Per tool call it reports the tool name (including fully-qualified mcp__* tools), the arguments, the model, session and tool-call ids, sub-agent parentage and the observation timestamp — each stamped with its surface and mode: "monitor". It also reports the sandbox’s own permission decisions. Cowork asks you to approve a tool call and writes both halves of that exchange: the request (tool name and arguments) and your answer — granted, and whether you allowed it once or always. Denials and standing grants are therefore visible, not inferred.

An observed call is not a call that ran

The audit record for a tool call is written when the model issues it — before the permission prompt is answered. A call you refuse still appears in the stream, and on its own it is indistinguishable from one that executed.

Every observation carries cowork.execution so the two are told apart:

value	means
`refused`	you denied it — the tool never ran
`granted`	you approved it
`unconfirmed`	the stream has not said: the call was not gated, or its answer has not been read yet. This is the default, and it is not a claim that the call ran

Already running the Claude Code harness?

Then your host-local Cowork sessions are already governed. Cowork reads the same ~/.claude/settings.json as the Claude Code CLI, so @visiq/claude-cowork-harness installs the same visiq-claude-code-hook dispatcher rather than a second one — two dispatchers over one file would double-evaluate every tool call. Installing this package adds the Cowork surface labelling and the sandbox monitor.

Fail posture

Agent-side, the harness fails open by default: if VisIQ itself cannot answer — no credentials, endpoint unreachable, no rule bundle — the agent keeps working and the failure is reported loudly. A policy deny always blocks. Opt into strict fail-closed with VISIQ_FAIL_MODE=closed.

Commands

Command	Purpose
`install [--settings <path>] [--command <cmd>]`	Wire the governance hooks (host-local enforcement)
`uninstall [--settings <path>] [--command <cmd>]`	Remove them, leaving your own hooks untouched
`status [--settings <path>] [--command <cmd>]`	What is installed, detected, and actually covered
`monitor [--once] [--interval <ms>]`	Tail the sandbox audit stream (monitor-only)

This table is not hand-maintained. packages/visiq-claude-cowork-harness/__tests__/usage.test.ts derives every signature from the CLI’s own flag table and requires this page — and the package README — to match it, so a flag the CLI accepts and this page omits reds a test rather than shipping. It had: status --settings, status --command and uninstall --command are all accepted and acted on, and none was documented.

--settings configures ONE invocation, not a saved preference. After visiq-claude-cowork install --settings /custom.json, a bare visiq-claude-cowork status reads ~/.claude/settings.json — a different file — and truthfully reports it as uncovered. Following that output’s advice with a bare install would write your live config, which is the outcome --settings exists to avoid.So the CLI carries the flag forward. Every command it suggests that accepts --settings is printed with the file already in effect, ready to paste:

visiq-claude-cowork install --settings /custom.json
visiq-claude-cowork uninstall --settings /custom.json
visiq-claude-cowork status --settings /custom.json

monitor does not take --settings — it is suggested bare, because the CLI never prints an invocation it would refuse. These examples are re-derived from the renderer the CLI itself calls by packages/visiq-claude-cowork-harness/__tests__/hints.test.ts, so if the carry-forward ever stopped, this promise would red rather than ship.

Quickstart

Action Governance

Retrieval Governance

Delegation Governance

Unified Rules

Audit Trail

Discovery

Connectors

API Examples

Platform Automation

Partners

Reference

API Reference

Claude Cowork Integration

The two surfaces

If an AI coding agent is doing this install

Install

Monitoring sandboxed sessions

An observed call is not a call that ran

Already running the Claude Code harness?

Fail posture

Commands

​The two surfaces

​If an AI coding agent is doing this install

​Install

​Monitoring sandboxed sessions

​An observed call is not a call that ran

​Already running the Claude Code harness?

​Fail posture

​Commands

The two surfaces

If an AI coding agent is doing this install

Install

Monitoring sandboxed sessions

An observed call is not a call that ran

Already running the Claude Code harness?

Fail posture

Commands