Skip to content

Claude Code Reference

Editions: OSS, Cloud, Enterprise. Unless stated otherwise, everything on this page ships in OSS.

How to onboard Claude Code (Anthropic's agentic coding CLI) into Preloop's Safety Layer with the preloop CLI.

Overview

Preloop governs Claude Code on two planes:

  • Tool calls: a managed preloop MCP server entry routes governed tools through the Preloop MCP Firewall, where access rules (allow / deny / require_approval) and approval workflows apply.
  • Model traffic: onboarding can rewrite Claude Code's environment so model calls go through the Preloop Gateway using a managed model alias, giving you cost analytics and budget controls.

Optionally, Preloop can also install a native tool-approval hook so Claude Code's own tool calls (shell commands, file edits) that would normally prompt you in the terminal are routed to Preloop mobile/watch/web approvals instead.

Prerequisites

curl -fsSL https://preloop.ai/install/cli | sh

The installer discovers local agents, walks you through login/signup, and offers to onboard everything it found. See the CLI quickstart for the full flow.

MCP servers missing in Claude

If claude mcp list connects to Preloop but /mcp inside Claude reports no servers, check for CLAUDE_CODE_SIMPLE enabled (1, true, yes, or on) in ~/.claude/settings.json, the project's .claude/settings.json or .claude/settings.local.json, or your shell environment. Simple mode disables automatic MCP discovery and hooks. Older Preloop CLI versions set this during model onboarding.

With a CLI version containing the simple-mode fix, re-onboard Claude Code to remove the setting, then restart Claude. With an older CLI, remove CLAUDE_CODE_SIMPLE from the settings manually and unset it in your shell; re-onboarding with that CLI can reintroduce it. Verify /mcp shows Preloop and its tools inside the restarted application. A successful gateway probe or claude mcp list alone does not verify that the application loaded its tools. Re-onboarding repairs the managed settings file; remove any overrides in other settings files or your shell manually.

Subscription credential recovery

Preloop refreshes an onboarded Claude subscription automatically. Re-onboarding reuses a working server credential even when the local access token has not yet expired: access-token expiry does not prove a rotating refresh token is usable. The server also rejects re-imports of refresh tokens it has recently consumed.

One refresh lineage, two holders

Onboarding with --from-local copies the Claude Code login (the macOS Keychain entry Claude Code-credentials, or ~/.claude/.credentials.json on Linux) into Preloop and leaves the local login signed in. Both copies sit on one single-use refresh lineage: a long-running Claude Code process can renew its login on its own, and the Preloop gateway renews its stored copy. Whichever holder refreshes second with the already-consumed token gets invalid_grant.

The Preloop hooks keep both copies aligned. At SessionStart, on each UserPromptSubmit, and before tool calls (PreToolUse/PermissionRequest), the hook pushes the local login when its expiresAt is newer than the stamp in the local enrollment state, so the gateway holds the live token before the first model call. About every two minutes it also reads Preloop's rotation marker (no token material) and, when Preloop's copy is newer and a local login exists, writes it back into the same store, preserving fields Preloop does not hold. When both changed, the copy that expires later wins. Each attempt is bounded to 3 seconds and backs off for a minute after a failure; a failure is logged once and never changes a hook decision. Flow runs with an execution-scoped credential are skipped. The gateway refreshes 10 minutes before expiry, ahead of the client's own refresh window, so a pulled bundle normally reaches the local login before Claude Code would refresh it.

To reconcile by hand (no hooks installed, or after a gateway refresh error):

preloop agents sync-credentials "Claude Code"

It prints which direction ran and never prints tokens. If the enrollment's Claude Code models point at more than one stored credential, the sync refuses (one rotating token must live in one place) and asks you to run preloop agents reconnect "Claude Code" --from-local, which merges them. Sync cannot revive a lineage that the provider has already revoked on both sides: if the local login is also signed out, sign in again and reconnect as below.

Reconnect after revocation

If Anthropic rejects the grant with invalid_grant and sync-credentials does not recover it, obtain a fresh subscription authorization without rebuilding the enrollment:

preloop agents reconnect "Claude Code"

This opens Claude's subscription sign-in and replaces only the server credential. If you already signed in with claude auth login --claudeai, use preloop agents reconnect "Claude Code" --from-local. Identity, policy, gateway configuration and backups are preserved. Update the Preloop CLI if the command is missing from your installed release.

Independent hosts or Preloop instances should authorize separate provider grants. Copying a login bundle between them creates competing refresh owners. Refresh locks coordinate workers within one Preloop instance; they cannot coordinate a native client or a separate instance holding a copy of the same provider grant. Provider revocation still requires a new sign-in; transient refresh failures can be retried without reconnecting.

Onboard Claude Code

Step 1: Discover

preloop agents discover

This scans standard configuration paths without mutating anything. For Claude Code it reads ~/.claude/settings.json (primary) or ~/.claude/mcp-servers.json (legacy fallback) and lists any MCP servers already configured there. Fresh or lightly-used installs are detected too: ~/.claude.json or a claude binary on PATH count as install markers, and onboarding bootstraps the canonical ~/.claude/settings.json.

Step 2: Onboard

preloop agents onboard "claude code"

Or run preloop agents discover and accept the interactive onboarding prompt. Onboarding:

  1. Creates (or locates) the managed agent identity in your Preloop account and issues a durable credential for it.
  2. Backs up your existing Claude Code config next to the original so you can roll back at any time.
  3. Adds a managed preloop MCP server entry to ~/.claude/settings.json.
  4. Configures supported Claude Code model routes through the Preloop Gateway (sets env.ANTHROPIC_BASE_URL to your Preloop gateway's /anthropic endpoint, env.ANTHROPIC_API_KEY to the managed credential, and lets stock Opus/Sonnet/Haiku selectors follow Claude Code defaults).
  5. Sends a direct gateway route/accounting probe using managed configuration (disable with --skip-live-validate). It does not launch Claude Code or verify that Claude Code consumed its configuration.

Useful flags (see preloop agents onboard --help):

Flag Effect
--dry-run Preview the planned account and config changes without writing anything
--yes / -y Skip confirmation prompts
--all Onboard every discovered agent
--approvals Also install the native tool-permission hook (see below)
--pin-model-families Persist explicit stock family pins for API-key accounts or gateways with family autoregistration disabled
--skip-live-validate Skip the post-onboarding direct gateway probe
--tags key=value Add key-value tags to the enrolled agent

Stock families follow Claude Code defaults. With subscription OAuth and Claude family autoregistration enabled, new Anthropic releases need no manual refresh: after a Claude Code update, the gateway registers first-used identifiers against the agent's subscription credential. Custom models retain explicit mappings.

Fable follows the same rule on Claude Code 2.1.321 and later, the first build with a built-in fable default: with subscription OAuth and no --pin-model-families, onboarding and refresh write no ANTHROPIC_DEFAULT_FABLE_MODEL pair and no Fable custom model option, so /model fable asks for Claude Code's own newest Fable id and the gateway registers it on first use. On older Claude Code builds, API-key accounts, or with --pin-model-families, the Fable pair is kept; preloop agents refresh moves it to the newest Fable release the agent may use and prints a warning when a newer release exists that is not yet in the account catalog or the agent's allowed models.

If the agent's allowed models name an older release of a Claude family (for example anthropic/claude-fable-5-1), refresh and onboarding add the newer release they bind and print the addition. An allowed-models list that does not name the family is left alone. The gateway does not change allowed models on its own; a request for a newer release of an allowed family is denied with a 403 that names the allowed release and suggests preloop agents refresh.

Anthropic API-key credentials do not support this automatic registration. For API-key accounts, pass --pin-model-families on onboard or refresh to retain catalog-backed stock family pins, or run preloop models sync to populate new identifiers before selecting them. Use the same flag when gateway family autoregistration is disabled. The choice persists across later runs; preloop agents refresh "claude code" --pin-model-families=false clears it. With explicit pins enabled, refresh verifies family upgrades against the live provider list.

What gets written

After onboarding, ~/.claude/settings.json contains a managed entry like:

{
  "servers": {
    "preloop": {
      "url": "https://preloop.ai/mcp/v1",
      "transport": "http-streaming",
      "headers": {
        "Authorization": "Bearer <managed credential>"
      }
    }
  }
}

Configuration file location

Preloop treats ~/.claude/settings.json as Claude Code's primary configuration file. ~/.claude/mcp-servers.json is only read as a legacy fallback when settings.json is absent. When the claude binary is on PATH, the CLI registers the managed server through claude mcp add --scope user instead of editing files directly.

Step 3: Check configuration and gateway evidence

preloop agents status "claude code"     # local + remote enrollment state
preloop agents validate "claude code"   # config validation
preloop agents validate "claude code" --live  # plus a direct gateway route/accounting probe
preloop agents list                     # all managed agents in your account

A successful direct probe verifies the gateway route and accounting; application behavior remains unverified. Only calls routed through the managed MCP entry reach Preloop.

You can also open https://preloop.ai/console/agents: Claude Code appears as a card with its onboarding state (Fully onboarded, MCP proxy only, Model gateway only, or Incomplete).

Pro/Max subscriptions (OAuth) work too

If your Claude Code runs on a Pro/Max subscription instead of an API key, onboarding stores the OAuth credential and the gateway proxies that traffic byte-faithfully: Anthropic requires the exact Claude Code request shape, so Preloop forwards it untouched while still applying budgets, governance tool-stripping, and usage recording. Message-level context optimizations do not apply to this traffic, and the credential is bound to this agent's model: other agents cannot use it. If the post-onboarding live check is throttled or refused upstream, the agent shows an unverified badge until preloop agents validate "claude code" --live passes. Details: Model Gateway → Subscription OAuth Passthrough.

Native tool approvals (PreToolUse hook)

Claude Code has powerful native tools (shell, file edits) that never pass through an MCP server. To govern those too, onboard with:

preloop agents onboard "claude code" --approvals

(Interactive onboarding also offers this as a Route Claude Code's native tool calls ... through Preloop approvals? prompt.)

This installs a PreToolUse hook entry in ~/.claude/settings.json that runs preloop agents permission-hook --source claude_code before each tool call, plus a per-agent credential under ~/.preloop/agents/. Because Claude Code's PreToolUse fires on every tool call, the hook first evaluates your own Claude Code permission settings and only escalates calls that would have prompted you, those become Preloop approval requests you can answer from the mobile apps, watch, or web console. Calls your own config already allows proceed untouched.

Using governed tools

Once onboarded, tools exposed through the managed preloop MCP server are subject to your account's access rules and approval workflows. When Claude Code invokes a tool that requires approval, the call blocks until you approve or deny it (dashboard, email, or mobile), then the result is returned to the agent as usual.

Multi-step workflows behave the same way: each governed tool call in the sequence creates its own approval request as your rules dictate.

The always-available request_approval tool lets the agent explicitly ask for human sign-off with custom context, see Built-in Tools.

Rollback and offboarding

Onboarding always backs up the original config, so you can undo everything:

preloop agents restore "claude code"    # restore the most recent local backup
preloop agents offboard "claude code"   # restore config and remove managed enrollment

offboard also removes the approvals hook and its credential if they were installed, and can optionally clean up the managed model and MCP servers in your account (--remove-model, --remove-mcp-servers).

Export a managed hook overlay

For an already onboarded device, operators can generate a reviewable, secret-free hook overlay offline:

PRELOOP_DISABLE_TELEMETRY=true preloop agents managed-config claude-code \
  --output ./review-bundle --platform darwin \
  --cli-path /opt/preloop/bin/preloop --timeout 300

The output parent must already exist. The command creates only the requested output directory and its managed-settings.json, manifest.json, and preview.txt. Existing artifacts require --overwrite; symlink artifacts and managed system target directories are refused. It does not read discovered configuration or credentials, authenticate, contact a server, emit telemetry, check for updates, enroll a device, or install the overlay. The command accepts darwin, windows, and linux targets independently of the exporting host. Use an absolute executable path on the target device; Windows requires a local .exe path and the documented PowerShell hook support. The host timeout must exceed the separately provisioned approval wait budget plus process headroom; the exporter accepts 30–3600 seconds and does not query account defaults.

The overlay emits only hooks.PreToolUse, with matcher *, invoking the existing agents permission-hook --source claude-code adapter. Provision each executing user/device's hook credential separately through the current preloop agents onboard "Claude Code" --approvals workflow under an approved credential-custody policy. Do not package a token or capture a subscription OAuth credential for unattended rollout. Missing credentials deny under the existing hook contract; this artifact supplies no model route, MCP allowlist, permission rules, OTel settings, enrollment, Codex adapter, or Desktop bootstrap.

The vendor documents these file locations and hook behavior:

Target Managed settings location
macOS /Library/Application Support/ClaudeCode/managed-settings.json
Linux / WSL /etc/claude-code/managed-settings.json
Windows C:\Program Files\ClaudeCode\managed-settings.json

Review the managed-settings delivery and precedence documentation and command hook reference against your pinned app version. Lower user/project settings cannot remove managed hooks, but another managed source can supersede this file. The manifest records vendor semantics separately from runtime verification, which remains unverified. Restart the application, inspect its effective managed source, and test harmless allow/deny actions, missing/revoked credentials, outage behavior, conflicts, alternate routes and rollback in staging before expanding rollout.

Synthetic export and adapter tests do not prove live application enforcement on any OS or plan. Managed configuration is not device attestation: ordinary local software remains controllable by local administrators. Protected resources need independent enforcement when that threat is in scope.

For staged Jamf, Fleet, Intune and Kandji delivery, use the MDM recipes and review the coverage boundaries.