Skip to main content
AI tutorials

CG Claude Tutorial: Detect, Configure, and Safely Restore Your Local Claude Code Environment

This tutorial explains how to install and use CG Claude to run 31 environment checks, configure settings with one click, scan projects, edit local connections, perform two-way translation tests, and back up and safely restore configuration snapshots.

About 33 min read
CG Claude Tutorial: Configure and Restore Claude Code Locally

What Is CG Claude

CG Claude is a configuration and inspection workbench for the local Claude Code environment, available as an Electron desktop app and a local browser app. It checks the system, terminal, browser, proxy, TLS, Claude configuration, and project overrides, and helps repair configuration through previews, backups, and snapshots.

The tool includes 31 environment checks and runs three consecutive checks by default. It does not infer account status from environment results; account sessions, service region, quota, payment, web privacy, and some network conditions still require manual review.

Key capabilities

  • Check system and browser time zones, terminal TZ, proxies, DNS, IPv6, TLS, authentication sources, and the Claude configuration directory.
  • Execute configuration through 13 workflow nodes. Each node retries up to three times after its first failure, then skips and continues with later nodes.
  • Show a preview before changes and create a backup before writing; the first configuration node also saves a complete configuration snapshot.
  • Scan project permissions, Hooks, MCP, proxies, TLS, credential declarations, and dependency lock files.
  • Edit local Claude connection settings, including proxies, gateways, NO_PROXY, and extra CA paths.
  • Save and restore file contents, permissions, missing-file states, detection preferences, and recorded time zone and TZ values.
  • Configure OpenAI-compatible Chat Completions or Anthropic Messages and test Chinese-English translation in both directions with fixed examples.
  • Provide Chinese and English interfaces, light, eye-care, and dark color themes, reduced motion, and manual version checks.

CG Claude statically parses only supported configuration files. It does not execute startup scripts, project scripts, Hooks, MCP, or dependency installation, and it does not automatically clean up the keychain, Claude sessions, Skills, or Hooks.

Install the Desktop Version

Desktop installers are recommended for most users. Version 1.2.7 installers are in the Release attachments under release/1.2.7/. Node.js is not required after installation.

  • macOS Apple Silicon: CG-Claude-1.2.7-macos-arm64.dmg
  • macOS Intel: CG-Claude-1.2.7-macos-x64.dmg
  • Windows x64: CG-Claude-1.2.7-windows-x64-setup.exe
  • Linux x64: CG-Claude-1.2.7-linux-x86_64.AppImage or CG-Claude-1.2.7-linux-amd64.deb

After downloading, use SHA256SUMS.txt to verify file integrity. The macOS build is not yet signed or notarized; Windows and Linux desktop interactions have not yet been verified on physical machines.

When the desktop window is closed or minimized, it usually hides in the menu bar or system tray while tasks continue running. To end the service completely, choose “Quit CG Claude” from the tray menu. The program waits for detection, configuration, or restore transactions to finish before releasing the service lock.

The desktop and browser services cannot use the same record directory at the same time. Quit one instance before starting the other to avoid concurrent writes.

Start from Source

Prepare the Environment

Running from source requires Node.js 22.12 or later. Enter the project directory, install the locked dependencies, and start Electron:

npm ci
npm run desktop

On macOS, you can also double-click 启动工具.command; on Windows, double-click 启动工具.cmd. Linux users should run npm run desktop in the project directory.

The preparation script downloads Electron at the locked version and reuses binaries that are already installed. The download uses the existing HTTP/HTTPS proxy environment but does not rewrite the user's proxy configuration.

Start the Browser Version

npm run build
npm start

After startup, visit http://127.0.0.1:4318. The service listens only on the loopback address and can be stopped with Ctrl+C. Linux users can also run:

./scripts/start.sh

First Detection: Establish an Environment Baseline

  1. Set detection preferences. Choose the actual network mode, service method, target time zone, and privacy preferences. The default time zone check uses Taipei as a recommendation; you can also choose the current egress or specify one manually.
  2. Confirm optional network checks. By default, detection primarily reads local configuration. To query the public egress or collect WebRTC data, select the additional options; the external services involved will see the connection IP.
  3. Start detection. Click “Start Detection.” The tool runs three consecutive checks by default to reduce false results caused by transient conditions.
  4. Filter by status. Use the top “Passed,” “Needs Attention,” or “Pending Confirmation” entries. These entries clear old searches and category filters, then expand and focus the first result.
  5. Review evidence and boundaries. Results are grouped as passed, needs attention, requires action, pending confirmation, and not checked. For account, region, payment, web privacy, phone time zone, and location service items, confirm manually as prompted.

The 31 checks cover system and browser time zones, TZ, system proxies, virtual interfaces, DNS, IPv6, process and startup-file proxies, npm and Git proxies, API addresses, the Claude configuration directory, privacy, CLI, TLS, proxy compatibility, authentication sources, custom CA/mTLS, and optional public egress and browser consistency.

Run One-Click Configuration

After detection finishes, do not write changes immediately. First read the change preview and confirm the target values, affected files, and operations requiring system authorization.

  1. Click “One-Click Configuration” and complete the network mode, service method, and privacy preferences. Cleaning the default custom API address is unchecked by default.
  2. Review the system time zone and terminal TZ nodes, which are selected by default; clear them if you do not want to modify them.
  3. Read the write preview and confirm the fields, files, and permissions that will be changed.
  4. Start configuration. The tool runs 13 nodes in order, saving a backup before each write and a complete snapshot at the first node.
  5. When configuration finishes, use the remaining-items panel to open settings, copy commands, or start a terminal and complete steps that cannot be automated.
  6. Reopen the terminal and Claude client, then run three verification passes. Terminals that are already open do not automatically refresh environment variables when files change.

The tool can configure shell, npm, and Git proxies; shell and Claude custom API addresses; Claude privacy variables; and npm TLS verification. It can also configure the system time zone and terminal TZ during the one-click workflow.

Supported configuration locations include:

  • .zshrc, .zprofile, .zshenv
  • .bashrc, .bash_profile, .bash_login, .profile
  • .npmrc, .gitconfig, .config/git/config
  • .claude/settings.json

Changing the system time zone on macOS requires administrator authorization; Windows uses UAC; Linux depends on an available polkit agent. If automatic time zone detection is enabled on macOS and its status can be read, one-click configuration attempts to disable it after authorization and read back the result.

Edit Local Claude Connections

Open “Local Configuration” at the end of the navigation to choose whether to keep, set, or remove connection parameters individually. This feature writes only the following fields in ~/.claude/settings.json:

  • HTTPS_PROXY
  • HTTP_PROXY
  • NO_PROXY
  • ANTHROPIC_BASE_URL
  • NODE_EXTRA_CA_CERTS

A preview is shown before saving, and a complete snapshot of the previous state and the original file backup are recorded. Other fields, Hooks, permissions, and credentials are preserved, and the final JSON uses two-space indentation. Normalization of same-name lowercase proxy entries is also shown in the preview.

Extra CA files must be readable, non-empty, absolute local paths. The tool does not read certificate contents or make connectivity requests for this purpose. If a custom CLAUDE_CONFIG_DIR is detected, the connection editor is disabled to avoid writing to the wrong directory.

Scan Project Configuration

Open “Project Scan” and select a local project directory. The scan covers configuration overrides, permissions, command sandboxing, Hooks, MCP, proxies, TLS, credential declarations, dependency lock files, and local Git commits.

Project scanning reads only fixed configuration and metadata files. It does not execute project scripts, Hooks, MCP, or dependency installation. For dotenv files, the tool checks only whether they exist and does not read their contents; credential fields are reported without displaying their values.

Project scanning cannot replace source vulnerability, dependency vulnerability, or build correctness checks. Use the corresponding security, dependency, and build tools for those issues.

Restore Backups and Complete Snapshots

In “Backup & Restore,” select an existing complete snapshot and click “Restore Previous Configuration Snapshot.” The restore can include file contents, original permissions, the state of files that originally did not exist, detection preferences, and recorded system time zone and TZ values.

  1. Select the target snapshot and review the restore preview.
  2. Confirm that file contents, permissions, and time zone status still match the preview baseline.
  3. Run the restore. The tool first saves the current state separately, then restores the target snapshot.
  4. Reopen the terminal and client to verify environment variables and Claude configuration.

If file contents, permissions, or the time zone change after the preview, restoration is blocked to avoid overwriting new changes. A snapshot covers only the eleven supported user configuration locations, detection preferences, and readable time zone and TZ values. It does not include translation settings, the complete ~/.claude directory, the keychain, or historical sessions.

Configure Two-Way Translation

In “Two-Way Translation” on the left, you can set the protocol, API address, model name, key, and timeout. OpenAI-compatible Chat Completions and Anthropic Messages are supported.

After clicking “Test Two-Way Translation,” the tool sends two fixed examples and displays the Chinese-to-English and English-to-Chinese results separately. The test does not read project content or Claude sessions and does not automatically retry potentially billable requests.

Keys are encrypted with AES-256-GCM, and the master key is stored in the local private record directory. However, this is not the system keychain; anyone with read access to that directory may still be able to decrypt it. Saved keys are not returned to the interface; they must be entered again after changing the service address or protocol.

Passing the translation model test does not mean the native Claude Code terminal has been connected, nor does it automatically enable session interception.

Use Isolated Demo Mode and the CLI

Before modifying real configuration, you can use isolated demo mode:

npm run demo
npm run desktop:demo

demo uses a dedicated temporary configuration directory and port 4319; desktop:demo uses an independent Electron data directory. Demo writes affect only the test directory. The system time zone and TZ use isolated simulations, while platform information and client version are still read from the local machine.

To read detection results automatically, use the CLI:

npm run doctor -- --json

By default, the CLI only detects and does not modify configuration. To enable public network queries from the terminal, add --network:

npm run doctor -- --json --network

Common Runtime Variables

  • CG_PORT: Browser service port, default 4318; Electron uses a random loopback port.
  • CG_HOME: User configuration root, defaulting to the current user's home directory; useful for isolated verification.
  • CG_DATA_DIR: Record directory, defaulting to .claude-guard under the configuration root.
  • CG_DEMO=1: Marks isolated mode; an independent configuration root should also be specified.

Advanced Usage Recommendations

Avoid Using Outdated Previews

If historical reports, detection preferences, or configuration baselines have changed, run a new check before previewing a fix. Old reports can still be read, but should not be used directly as the basis for a new write operation. The tool also verifies file permissions and read status, and refuses to reuse previews that have changed.

Handle Complex Configuration Files Correctly

Startup files are statically parsed only for direct assignments. Complex functions, conditional blocks, multiline expressions, and heredocs are not edited automatically. Configuration text must be strictly UTF-8; files containing invalid UTF-8 or NUL characters are excluded from snapshots and flagged for manual review instead of being interpreted as GBK or another encoding.

Understand the Privacy Boundaries of Public Network Checks

Public network checks may access https://ipinfo.io/json, https://api.ipify.org?format=json, and stun:stun.l.google.com:19302. These services can see the connection IP, but do not receive local configuration or keys. Report exports further hide IP addresses and hostnames by default.

Distinguish Browser Language from Time Zone Settings

The default browser target language is en-US. Although en-CN is also English, it uses a different region. This check is a project extension and is not required by the original text. One-click time zone configuration does not modify the external browser language; follow the Chrome, Edge, Firefox, or Safari instructions provided on the page to configure it manually.

Protect Local Records

The default records directory is ~/.claude-guard/. It stores detection preferences, the 30 most recent reports, backups, snapshots, manual reviews, and workflow status. Backups or snapshots may contain credentials in their original form, so do not copy or commit this directory casually.

On POSIX systems, the records directory has 0700 permissions and record files have 0600 permissions; Windows inherits the user directory ACL. Newly created configuration files use 0600 on POSIX while preserving the original configuration permissions whenever possible.

Development and Packaging

Development mode uses frontend port 5173 and backend port 4318:

npm run dev

Before committing changes, you can run the full checks and formatting validation:

npm run check
npm run format:check

Generate the application directory or an installer package for the current platform:

npm run pack
npm run dist

pack generates the application directory; dist generates a macOS dmg／zip, Windows NSIS／portable package, or Linux AppImage／deb for the current system, using the Electron runtime corresponding to the current system and CPU architecture.

Conclusion

CG Claude brings environment checks, configuration previews, field fixes, project scans, and snapshot restoration together in one local workspace. It is recommended to become familiar with the workflow in demo mode first, then establish a baseline for the real environment; check the preview before every write, reopen the terminal afterward, and run consecutive rechecks. For items such as accounts, regions, payments, phone time zones, and browser privacy that cannot be reliably determined automatically, retain a manual review step.

To view the browser environment configuration plugin, visit the LC-time project.