verify-networking-plugin: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

cargo build --release          # build the binary
cargo clippy                   # lint
./install.sh                   # build + install binary + add shell wrapper to RC file

To test the binary directly:

./target/release/verify-networking; echo "exit: $?"

# Test daemon mode (starts proxy, Ctrl+C to stop)
./target/release/verify-networking --daemon

# Test daemon mode with custom port
./target/release/verify-networking --daemon --port 9999

Makefile targets

make          # debug build
make release  # release build
make test     # run tests
make lint     # clippy
make fmt      # format source
make clean    # remove build artifacts
make install  # build + install + patch shell RC
make hooks    # install git pre-push hook

Architecture

The plugin is a Rust binary installed at ~/.claude/plugins/verify-networking. install.sh adds shell wrapper functions to the user's RC file that intercept every claude (and codex, if installed) invocation before the process starts:

claude() {
    local checker="$HOME/.claude/plugins/verify-networking"
    [[ -x "$checker" ]] && { "$checker" claude || return 1; }
    command claude "$@"
}

codex() {
    local checker="$HOME/.claude/plugins/verify-networking"
    [[ -x "$checker" ]] && { "$checker" codex || return 1; }
    command codex "$@"
}

The tool name (claude / codex) is passed as the first argument so the binary knows which API endpoint to probe. This ensures the network check runs before either tool makes any outbound requests.

Checks (src/checks.rs): All three run concurrently via tokio::join!. Targets differ by tool. The exit IP comes from a trace endpoint on the target service itself, because split routing can send a third-party IP echo service and the target service through different outbounds. A trace without both an egress IP and a country is reported as Warn, so the region check never passes on an unknown region.