Claude-Guardian is a Skill for Agents. It hands your Agent the author's and community's real experience, a curated source library and a set of scripts, so the Agent can walk you through preparing your subscription, account, network egress and runtime environment according to your needs and setup. Everyone's system, network, budget and goals differ, so it learns about you first and suggests what fits; high-risk steps are yours to decide.

The Chinese README.md is the source text; where the two differ, the Chinese version wins. The source library under skills/ is in Chinese.

Partners

Don't want to set things up yourself? Try DPCC API — click the image.

Prefer not to set it up yourself? Done-for-you setup and the Skill website are here — click the image.

What it does

Ground rules

• Money and accounts are yours: you pay, sign up, log in, and do KYC and OAuth yourself.
• No credentials needed: you never hand over IPs, subscription links, passwords, UUIDs or full configs.
• No Claude during prep: the client is not started, logged into or contacted.
• Adapted to your environment: the author has used these tutorials and scripts on their own Mac, Windows, VM and VPS. Your system and app versions may differ, so the Agent checks first, adapts to the differences, and rolls back if something goes wrong.
• Nobody can guarantee you won't be banned: prices and access change fast; glance at the official pages before buying.

How it works

flowchart LR
    U["You: needs and environment"] --> A["Agent<br/>understand, judge, explain"]
    S["Skill<br/>experience · sources · rules"] --> A
    A --> Q["Interview state machine<br/>what to ask · which sources to attach · authorization record"]
    A --> R["Source library<br/>S01–S08 · S10 · R01 · R02"]
    A --> X["Scripts and prompts<br/>run by you or after approval"]
    Q --> A
    X --> V["Verification and rollback"]

• Agent-led: understands your needs, picks sources, explains results and decides the next step. The same Skill gives different people different approaches.
• State machine as a backstop: over a hundred interview questions are scheduled by condition; route-specific questions come only after you choose a route, and each assessment lists the sources to attach.
• Scripts run as documented: VM setup, firewall and similar scripts are run by you, or by the Agent once you approve.

Tiered authorization: you don't need to be there for every step

Only the points that really matter need you. Changes fall into three tiers by risk; see authorization tiers:

Approvals and confirmations come from your explicit reply in the conversation and are recorded in the interview state; a route change needs fresh confirmation.

Quick start

1. Install the Skill

Copy the skills/claude-guardian folder from this repository into the Codex Skill directory you use, keeping its internal structure. Keep the root LICENSE when redistributing.

• Requires Codex with Skills support; scripts need Python 3.10+
• The Skill and references can be read directly; you can look things up without running any script
• The project never installs Python, proxy tools or background services by itself; some static YAML features need the optional PyYAML and stop with an explanation if it is missing

On macOS / Linux, run in Bash (skip git clone if you already have the repository):

git clone https://github.com/DUNHKpcc/Claude-Guardian.git
(
  set -eu
  skill_root="$HOME/.codex/skills"
  mkdir -p "$skill_root"
  if [ -e "$skill_root/claude-guardian" ] || [ -L "$skill_root/claude-guardian" ]; then
    printf '%s\n' 'Target exists; stopping. Inspect and back up the existing Skill, then migrate by hand.' >&2
    exit 1
  fi
  cp -R Claude-Guardian/skills/claude-guardian "$skill_root/claude-guardian"
)

You should end up with ~/.codex/skills/claude-guardian/SKILL.md. The command stops on an existing target (including symlinks) to avoid nested copies or overwriting customizations; to update, inspect the diff, back up, and migrate the files you need by hand.

Updates: at the start of each session the Agent runs scripts/update_check.py check (read-only, contacts only GitHub) to compare every file with the repository's main branch and tells you what changed recently. With your approval it backs up the current Skill outside the Skill directory, keeps the files you changed yourself, and switches to the new version; see Skill updates.

On Windows, download or clone the repository, create any missing parent directories in your Codex Skill directory (usually %USERPROFILE%\.codex\skills), and copy the whole claude-guardian folder there. Confirm the result is skills\claude-guardian\SKILL.md; if a same-named target exists, inspect, back up and migrate by hand rather than merging or overwriting.

2. Start a conversation in Codex

$claude-guardian
I'm preparing my first Claude subscription, on a Mac. Compare local and VM first, then decide how to check.

The Agent asks about your stage, system and goal, without repeating questions you already answered; urgent failures and cleanup tasks go straight to their own flows.

3. Pick a route, then check

Say what you want this time → choose local / VM / VPS → describe the network resources you have → confirm the check scope → check → approve the plan by tier

If you only want to understand the subscription or compare options, stop at the explanation stage; your device is left untouched.

Choosing a route

If the target machine already has an Agent, work directly on that machine. OpenSSH, Tailscale, NAT traversal and remote failure drills belong to the optional local-route extension for remote assistance. They are not prerequisites for the local route.

The three routes are parallel choices, not an upgrade path; using a VPS as a network exit is not the same as choosing the VPS route. No proxy or server yet? You can start with an offline pre-check. For the difference between an HTTP/mixed entry and an upstream SOCKS5 exit, see environment entry and route boundaries.

Cleaning Claude data from an old device: macOS has a built-in host, see the cleanup interface guide; Windows uses a PowerShell prompt based on the official paths, Linux has its own Linux cleanup. After a ban, proxy-client logs, VPN logs and IP-lookup commands in shell history are covered by trace cleanup; jailbreak and reverse-proxy-distribution tools installed into Claude are removed per illegal tools cleanup.

For the full rules see contact and authorization boundaries and the network evidence notes.

Examples

python3 skills/claude-guardian/scripts/guardian.py --help
python3 skills/claude-guardian/scripts/interview_cli.py --target-ref laptop-a --account-ref account-a

Documentation

Source originals keep their own attribution and license, and related answers cite them.

Development and verification

python3 -m unittest discover -s tests -v
python3 -m compileall -q skills/claude-guardian/scripts
python3 tools/package_skill.py --help

When packaging, use --output for a new ZIP path in your own temporary directory; tests use synthetic data only. CI runs unit, regression and deterministic packaging checks on Linux, macOS and Windows. What changed is in the CHANGELOG; why is in the decision log.

Real-device verification and feedback: the author verified these tutorials and scripts on their own Mac, Windows, VM and VPS, and the Clash Verge write and rollback and the whole-machine egress ruling on Mac went through item-by-item real-device acceptance (see ADR-039). Tell us which item you used, how it went and what needed adjusting through the device report.

Star History

Community channels

• Telegram channel: https://t.me/+q4D4_Qf_FIs5NDk1
• QQ: 1048450370

Swap experience and share usage in the channel; for problem reports and suggestions use Issues so they are on record.

Feedback and license

Report problems through Issues, or submit docs, synthetic samples and regression tests. Include your system, version, reproduction steps and expected result, and keep accounts, credentials, subscription links and full proxy configs out of it.

Code is licensed GPL-3.0-only. Source originals keep their existing attribution and license notices.