# Connect your AI tools

> Connect Claude Code, Cursor, Codex and Gemini CLI to Cloak Watch with hooks, the local gateway or telemetry, see the exact settings change first, and undo it.

Source: https://docs.subcloak.com/cloak-watch/ai-activity/connections/

The Connections tab in AI Activity lists each AI tool on your Mac and how Watch can see it: through its **hooks**, through Watch's local **gateway**, through **telemetry**, or on the **network**. You turn each one on per tool. Watch always shows the exact change to the tool's settings file before it writes anything, and can undo it.

*[Screenshot: The Connections tab: a table of Claude Code, Cursor, Codex, Gemini CLI, Claude, GitHub Copilot and a node script, with Hooks, Gateway, Telemetry, Network and Can stop columns, and Claude Code selected with its hooks, gateway, telemetry and network each described, Undo buttons, and What Watch can't see]*

## The Connections table

| Column | Values |
|---|---|
| **Tool** | Claude Code, Cursor, Codex and Gemini CLI, with their versions; Claude (the desktop app), ChatGPT and GitHub Copilot when installed; other apps the network extension saw talking to AI providers |
| **Hooks**, **Gateway**, **Telemetry**, **Network** | **On**, **Off**, **Check** (needs attention) or **—** (not available for this tool) |
| **Can stop** | **Yes** when a connected way can stop things, **Not set up**, or **No** |

Select a tool to see, for each way: whether it's connected, what it adds, what it can stop, and **Set Up…** or **Undo…**. **What Watch can't see** lists that tool's blind spots, such as requests Claude Code sends straight to Anthropic even with the gateway on.

| Tool | Hooks | Gateway | Telemetry | Network |
|---|---|---|---|---|
| Claude Code | Yes | Yes | Yes | Yes |
| Cursor | Yes | — | — | Yes |
| Codex | Yes | Yes | Yes | Yes |
| Gemini CLI | Yes | Not yet | Not yet | Yes |
| Claude, ChatGPT, GitHub Copilot, other apps | — | — | — | Yes |

## Set up a connection

1. Open **AI Activity › Connections** and select the tool.

2. Click **Set Up…** next to **Hooks**, **Gateway** or **Telemetry**. (With nothing connected yet, the Activity tab's **Connect Claude Code…** button sets up Claude Code's hooks.)

3. Read the sheet. At the top, Watch says what it will keep: **Watch keeps what Claude Code sends and receives** (prompts, model requests, tool input and output, for 7 days, secrets masked). Turn off **Keep prompts and content** to keep only tool names, timings and hosts. Below that, the sheet lists what changes in plain sentences, **What you'll be asked** by the tool afterwards, any warnings, and the file with a diff of exactly the lines Watch adds and removes. Nothing is written until you click **Apply**.

   *[Screenshot: The Turn on hooks for Claude Code sheet: Adds Watch's local hook for 9 events, What you'll be asked about trusting folders, and a diff of ~/.claude/settings.json adding an http hook to 127.0.0.1:47318]*

4. Click **Apply**. Watch keeps a copy of the old file next to it, named `<file>.cloak-watch-backup`, then writes exactly what the diff showed. If the file changed after the preview, Watch shows a new preview instead: **The settings file changed after the preview. Review the new preview before applying.**

Watch refuses to edit a settings file that isn't valid JSON.

## What each connection writes

**Claude Code**

All three ways go in `~/.claude/settings.json` (or `settings.json` in `$CLAUDE_CONFIG_DIR`).

**Hooks** adds one `http` hook for each of `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `SessionEnd`, `ConfigChange` and `InstructionsLoaded`, pointing at `http://127.0.0.1:47318/cloak-watch/hooks/claude-code` with a 5-second timeout and a private `X-Cloak-Watch-Token` header (masked in the diff). No command runs, and Claude Code carries on if Watch is closed. Guard rules you set to fail closed add hooks with `onFailure: "block"`.

What you'll be asked: Claude Code runs hooks in a folder only after you've trusted that folder once; folders you already trust work at once.

**Gateway** sets `env.ANTHROPIC_BASE_URL` to `http://127.0.0.1:47319/claude-code`. Requests still go to where they went before, after Watch checks them (see [the local gateway](#the-local-gateway)). If you use an HTTPS proxy, Watch also adds `127.0.0.1` and `localhost` to `NO_PROXY`. Watch refuses when Claude Code uses Amazon Bedrock, Google Vertex or Microsoft Foundry (`CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, `CLAUDE_CODE_USE_FOUNDRY`). It works with API keys, gateway tokens and claude.ai logins.

**Telemetry** adds these `env` keys, so Claude Code reports usage to Watch on this Mac. `OTEL_LOG_USER_PROMPTS` is only added while Watch keeps content; with metadata only, Claude Code isn't asked for prompt text.

```json title="~/.claude/settings.json"
{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/json",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://127.0.0.1:47318/cloak-watch",
    "OTEL_EXPORTER_OTLP_HEADERS": "X-Cloak-Watch-Token=…",
    "OTEL_LOG_TOOL_DETAILS": "1",
    "OTEL_LOG_USER_PROMPTS": "1"
  }
}
```

If Claude Code's telemetry already goes somewhere else, Watch leaves it alone and says so.

If your organization's managed settings (`/Library/Application Support/ClaudeCode/managed-settings.json`) allow only managed hooks, Connections says **Your organisation allows only managed hooks** and offers no setup for hooks.

**Cursor**

**Hooks** writes `~/.cursor/hooks.json` (with `"version": 1`), adding command hooks for `beforeSubmitPrompt`, `beforeShellExecution`, `afterShellExecution`, `beforeMCPExecution`, `afterMCPExecution`, `beforeReadFile`, `afterFileEdit`, and `preToolUse` for writes and deletes. Each runs Watch's hook script, which asks Watch on this Mac and answers within a few seconds. Guard rules set to fail closed add `failClosed: true`.

What you'll be asked: nothing. Cursor reloads its hooks file on its own. Watch warns if Cursor's **Include third-party configs** setting affects which hooks load.

Cursor has no gateway or telemetry connection: its model requests go from Cursor's own servers. The network extension still sees Cursor's traffic.

**Codex**

**Hooks** writes `~/.codex/hooks.json` for `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `SessionStart` and `SessionEnd`, each running Watch's hook script with a 10-second timeout. What you'll be asked: approve Cloak Watch's hooks in Codex with `/hooks`, and again whenever Watch updates them.

**Gateway** edits `~/.codex/config.toml`. It sets the top-level provider and adds a provider table:

```toml title="~/.codex/config.toml"
model_provider = "cloak-watch" # Cloak Watch (was: openai)

[model_providers.cloak-watch]
name = "Cloak Watch gateway"
base_url = "http://127.0.0.1:47319/codex/v1"
wire_api = "responses"
requires_openai_auth = true
```

If you already use a custom provider, Watch copies its settings into the new table and chains to its `base_url`; it refuses when that provider has no `base_url`. Works with API keys and ChatGPT sign-in.

**Telemetry** appends an `[otel]` table pointing at Watch. If one already exists, Watch leaves it alone and says so. Watch can't remove it for you: delete the table by hand to turn Codex telemetry off.

*[Screenshot: The Codex gateway sheet showing the diff to ~/.codex/config.toml]*

**Gemini CLI**

**Hooks** adds hooks named `cloak-watch` to `~/.gemini/settings.json` for `BeforeAgent`, `BeforeTool`, `AfterTool`, `SessionStart` and `SessionEnd`, with a 10-second (10000 ms) timeout.

Gateway and telemetry aren't available yet: Watch's gateway speaks the Anthropic and OpenAI formats.

The Cursor, Codex and Gemini CLI hooks run a small script Watch writes to `~/Library/Application Support/Cloak Watch/AI/hooks/watch-hook`, with its token in a file next to it that only you can read.

## The local gateway

The gateway is a small forwarder inside Cloak Watch, listening on `127.0.0.1:47319`. A tool that uses it sends its model requests to Watch; Watch checks them against your [Guard](https://docs.subcloak.com/cloak-watch/ai-activity/guard/) secrets rule, records them, and forwards them to the real destination.

- **It chains, it doesn't replace.** The upstream is whatever the tool used before. For Claude Code, that's the previous `ANTHROPIC_BASE_URL` from its settings or your shell profile (which Watch reads but never edits), or `https://api.anthropic.com`. For Codex, the previous provider's `base_url`, `https://api.openai.com/v1`, or ChatGPT's Codex backend when you sign in with ChatGPT. If you already use a company gateway, requests still reach it.
- **Your login passes through untouched.** API keys, auth tokens and claude.ai or ChatGPT logins are forwarded as they are and never stored. Watch reads only their shape, to label the login type.
- **Responses are never changed.** Streamed replies pass through as they arrive.
- **It speaks** Anthropic Messages, OpenAI Chat Completions and OpenAI Responses.
- **Only secrets rules run here.** Guard replaces each secret in what you or a tool wrote with `[REDACTED: type]`, or blocks the request. The system prompt, tool definitions and earlier assistant turns are flagged, not changed. Tool rules run in hooks, not here.
- **It only listens on this Mac** and refuses requests from web pages.

The Connections inspector shows, for example, **Gateway on 127.0.0.1:47319 · 412 requests · adds 0.6 ms**.

If Subcloak turns the gateway off from the signed feed because of a problem, it stops and tools that used it go direct; Watch says so in a bar and in Settings › About.

> **The gateway needs Watch running:**
> A tool pointed at the gateway can't reach its model while Cloak Watch is closed, or if another app holds port 47319 (Connections then shows the gateway needs attention). Quit a tool's gateway connection with **Undo…** before you quit Watch for good. Hooks and telemetry don't have this problem.

## The local receiver

Hooks and telemetry report to a second small server inside Watch, on `127.0.0.1:47318`. It accepts only requests that carry Watch's private token (`X-Cloak-Watch-Token`) and refuses requests from web pages. It never listens beyond this Mac.

## When Watch isn't running

| Connection | What happens |
|---|---|
| Claude Code hooks | Claude Code can't reach the hook and carries on (fails open). |
| Cursor, Codex and Gemini CLI hooks | The hook script gives up after 5 seconds and allows the action. |
| A Guard rule set to fail closed | The action is blocked instead. |
| Gateway | The tool can't reach its model until Watch is running again. |
| Telemetry | The tool's reports are lost; it keeps working. |

## Undo a connection

1. Open **AI Activity › Connections** and select the tool.

2. Click **Undo…** next to the connection. The sheet (**Turn off …**) shows the diff. Watch removes only its own lines.

   *[Screenshot: The Turn off the Watch gateway for Claude Code sheet: Points Claude Code back at https://llm.example.net, with a diff restoring ANTHROPIC_BASE_URL in ~/.claude/settings.json]*

3. Click **Remove**.

If the file is still exactly as Watch left it, Undo puts back the whole file as it was before Watch changed it. If you've changed it since, Undo removes only Watch's entries, and for the gateway, restores the previous base URL. The `.cloak-watch-backup` copy stays next to the file. Codex telemetry is the exception: remove its `[otel]` table by hand.

## Related

  - [AI Activity](https://docs.subcloak.com/cloak-watch/ai-activity/): Read sessions, events and content.
  - [Guard rules](https://docs.subcloak.com/cloak-watch/ai-activity/guard/): What hooks and the gateway can stop.
  - [Network extension](https://docs.subcloak.com/cloak-watch/ai-activity/network-extension/): See every app's AI traffic, no setup per tool.