SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsclaude-code-guard

claude-code-guard

Deployment & operations

View repository

Updated 10-16 06:49

About this skill

Claude Code Network Protection Skill

The goal is verifiable routing constraints, not circumventing the terms of service or promising account security. Comply with the applicable service regions and usage rules; do not treat node names, residential IPs, or third-party ratings as official endorsement. For copy steps, see README.md。

Traffic splitting (required)

Only protect Claude Code / Claude CLI HTTP(S) sent to Claude and Anthropic sites：HTTP_PROXY → local gate → dedicated inbound → currently effective one final leaf. By default, a single fixed node; controlled primary/secondary failover is enabled only when the user explicitly specifies two concrete leaves, primary and secondary, and a Selector routing root.

Do not intercept shells, scripts, git, or remote database clients. They usually do not use an HTTP proxy, and Seatbelt should allow real network access, with Clash rule mode sending domestic destinations DIRECT. Only deny processes from modifying the Mihomo control port.

By default, HTTP CONNECT sends genuine Claude traffic through the dedicated inbound. Only company/domestic domain suffixes that the userauthorizes on the spotmay be sent to the rule inbound; do not copy another machine's domain list, and do not loosen the dedicated inbound for databases. After changing the sandbox, Claude must be restarted; old processes still use the old rules.

First determine whether this is maintenance or a fresh install

  1. Maintaining an existing environment takes priority: read the wrapper, Hook, sandbox, startup services, and browser entry point. Do not reinstall just because an installer is included.

  2. First read Maintenance and Deployment Identification. The target machine may use the ~/.claude-guard/ new layout or the ~/.local/claude-guard/ old layout; you must first audit and identify the actual running version, and they must not overwrite each other.

  3. Use a read-only audit to obtain file existence, SHA-256, and limited settings:

    python3 "<SKILL>/scripts/ccg_audit.py"

The audit does not make network calls, does not read cookies/chats/keychains, and does not prove traffic security. To record a browser launcher digest, explicitly pass --browser-launcher "<confirmed script path>". 4. Record the pre-change digest and the user's existing choices, then make the minimal change. When updating only the Skill, change only the Skill source/usage copy, not running scripts, proxies, account profiles, or system settings. 5. If an explicit choice already exists and matches the configuration, use it directly. Ask only when a new outbound has not been chosen, the cleanup scope is unclear, protection needs to be disabled, or a session would be interrupted.

Routing and Node Rules

  • Clash Rule modeAllow domestic development services DIRECT and Claude through an independent upstream. Enabling TUN does not mean all traffic goes through the proxy; the system proxy switch cannot prove the actual outbound. Seatbelt does not intercept shells/scripts/remote libraries.
  • At any momentthere can be only one effective final outbound node, matched exactly by the full leaf name. The default configuration stores only a single expected_node. Primary/secondary is an explicit optional capability: only one primary_node and one secondary_node, both must be specific, distinct, non-DIRECT/REJECT/PASS leaves specified by the user, and the Selector must and can only directly contain these two leaves; the failure threshold is limited to 2-5, and the strict probe interval is limited to 5-60 seconds. It must not be expanded into a node whitelist, load balancing, random selection, or candidate pool rotation. Single-hop and chained proxies are supported; "single-hop" is not Clash DIRECT.
  • Resolve the Selector's now from the proxy of the actual dedicated inbound, then verify the dialer-proxy/entry dependency. The Selector is allowed to be the routing root, but the final egress must equal the current unique expected_node. Loops, missing links, DIRECT/REJECT/PASS, or links that cannot be determined must not be treated as verified.
  • 🤖 AI服务 may point to the Taiwan Selector, but it does not have to be the routing root of the CLI dedicated entry. You cannot rely only on the UI, nor assume the old policy group claude-guard-exit exists.
  • A fixed node does not equal a fixed public IP. A new TW dynamic IP for the same specified node may update the CLI session; no other leaf should be allowed. When primary/backup is not enabled, changing the egress must be explicitly re-specified by the user and replace the old target. When primary/backup is enabled, you may only switch from primary to the pre-specified backup, and must not temporarily add a third node. Node names, flags, and displayed latency are not evidence of region.
  • Short-term retries may only use the current expected_node, and must not fall back to DIRECT, the system proxy, or an unspecified node. When fresh strict verification already exists, a single bounded control-port timeout, trace timeout, or temporary Anthropic unreachability may retain the last verified route and immediately recheck; only consecutive occurrences reaching the threshold close the gate; leaf drift, region mismatch, TUN/IPv6, or primary/backup state inconsistency are still rejected immediately. After the primary node's consecutive failures reach the threshold, the switch process must first set switching=true and close the active tunnel, and only allow traffic after strictly verifying the backup node's actual route, region, and Anthropic reachability. Failures must be read back to confirm rollback; when confirmation is impossible, remain blocked. By default, do not automatically switch back to the primary node.

For layering, retries, and acceptance, read protection boundary; for the browser, read Camoufox。

locally confirmed preferences

The following are not the default values for new installations of other clients:

  • Retain rule-based routing, a single effective egress at any moment, dynamic IP compatibility, and session recovery; this machine has fixed primary/backup enabled as specified by the user, and does not expand into a node pool.
  • This machine explicitly chooses the default --permission-mode bypassPermissions; explicit parameters take precedence. It relaxes tool permissions and does not enhance network protection; new installations must not enable it without authorization.
  • Do not set CLAUDE_CODE_DISABLE_MOUSE. For mouse escape codes, first investigate TTY/raw mode, exit cleanup, and background processes reading/writing the terminal; do not disable the mouse to mask the problem.
  • Point the Claude process's BROWSER to claude-camoufox; do not change the macOS global default browser, and do not touch any profile of regular Chrome.
  • Do not automatically clear credentials, chats, cookies, or reset fingerprints because of updating the CLI/Skill; read cleanup boundary。

New environment or migration

First read client and old templates. Probe the system, real clients, proxy/control ports, and existing deployments, and do not copy the author's nodes/ports/paths:

python3 "<SKILL>/scripts/ccg_detect.py" --list

The raw probe JSON may contain controller secrets and must not be published as-is. In a new environment, by default only one complete leaf name is confirmed with the user. Only when the user explicitly requests primary/backup should a backup leaf and a Selector routing root be confirmed; nodes must not be automatically selected from region or speed test results, and Selector members as a whole must not be treated as a whitelist. When only ports can be probed, it must not be claimed that the final node has been verified.

Included ccg_install.py、ccg_guard.py、ccg_gate.py and ccg_failover.py are generic templates,not equivalent to the current local policy. The default remains single-node; only when both --secondary-node and --ai-group are provided is a primary/backup configuration generated. Do not use templates to roll back or overwrite an existing deployment; the installer will refuse to overwrite discovered protected files/existing Hooks. For new environments, first perform a capability gap review, adaptation, and isolation testing, then deploy per authorization.

Acceptance and Delivery

  • Syntax/unit tests → compare files → read-only routing verification → accountless independent denial path testing.
  • Only after the user allows connection impact may nodes be switched, TUN disabled, or network disconnection tests be performed; do not interrupt running tasks.
  • Test wrong nodes, wrong regions, controller disconnection, upstream disconnection, IPv6/DNS, backup loopback proxy, and long connections; when primary/backup is enabled, also test the switch barrier, backup probe failure, rollback failure, active tunnel closure, and that it will not automatically switch back; write "unverified" for anything not tested.
  • --fast does not prove region; the existence of a Hook does not prove that every HTTP request is inspected; the launcher path does not prove that the current process is restricted by a sandbox.
  • Updating the CLI only updates the real binary, preserving the wrapper/Hook/settings/services. Use before-and-after summaries to prove protected files are unchanged; without a pre-existing summary, "hash-proven unchanged" must not be claimed.
  • After updating the Skill, run scripts/test_skill.py. Commit and push that repository only when the user explicitly requests publishing to GitHub.