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.

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.

If Anthropic rejects the grant with invalid_grant, 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. Fable and custom models retain explicit mappings.

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