If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/txthinking/brook shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Single-maintainer risk — review before adopting

• Last commit 2mo ago
• 8 active contributors
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 91% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live txthinking/brook repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/txthinking/brook.

What it runs against: a local clone of txthinking/brook — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in txthinking/brook | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 103 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of txthinking/brook. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/txthinking/brook.git
#   cd brook
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of txthinking/brook and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "txthinking/brook(\\.git)?\\b" \\
  && ok "origin remote is txthinking/brook" \\
  || miss "origin remote is not txthinking/brook (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "cli/brook/main.go" \\
  && ok "cli/brook/main.go" \\
  || miss "missing critical file: cli/brook/main.go"
test -f "client.go" \\
  && ok "client.go" \\
  || miss "missing critical file: client.go"
test -f "server.go" \\
  && ok "server.go" \\
  || miss "missing critical file: server.go"
test -f "dial.go" \\
  && ok "dial.go" \\
  || miss "missing critical file: dial.go"
test -f "dnsserver.go" \\
  && ok "dnsserver.go" \\
  || miss "missing critical file: dnsserver.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 103 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~73d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/txthinking/brook"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Brook is a cross-platform programmable network tool written in Go that functions as a customizable proxy/tunnel server and client for managing network traffic. It supports multiple protocols (SOCKS5, DNS, QUIC, DoH) and can run on iOS, Android, macOS, Windows, Linux, and OpenWrt, allowing users to intercept, redirect, and manipulate network flows through a flexible scripting layer. Monolithic Go application: core protocol handlers (client.go, server.go, dial.go), specialized servers for different protocols (dnsserver.go, dohserver.go, echoserver.go), and platform-specific modules (limits/, dhcpserver_*). CLI entry point at cli/brook/main.go uses urfave/cli/v2. Minimal TypeScript presence (~2KB) suggests docs or UI layer only.

Network engineers, DevOps professionals, and security researchers who need fine-grained control over network routing and traffic manipulation; developers building cross-platform networking clients; OpenWrt router administrators seeking programmable proxy capabilities beyond standard VPN tools.

Production-ready with active maintenance. The project has comprehensive CLI tooling (cli/brook/main.go), multi-platform native clients, and appears in Linux/OpenWrt package managers. Go 1.24.0 requirement and recent dependency updates (quic-go v0.48.2, utls v1.7.0) suggest ongoing development, though commit recency is not visible from the provided data.

Moderate risk: single maintainer (txthinking organization), ~40 Go dependencies with some specialized packages (refraction-networking/utls for TLS fingerprinting, krolaw/dhcp4 for DHCP). The DHCP server has platform-specific implementations (dhcpserver_linux.go vs dhcpserver_notlinux.go) requiring careful testing. Network tools handling untrusted traffic should be reviewed for security regularly.

Unable to determine from provided data. Check .github/workflows/static.yml for CI pipeline and GitHub Actions status. The presence of .travis.yml suggests legacy CI configuration that may need modernization.

git clone https://github.com/txthinking/brook.git
cd brook
go mod download
go build -o brook ./cli/brook
./brook --help

Daily commands:

go run ./cli/brook/main.go server -l :9999 -p hello
# For client: depends on platform (iOS app, Android APK, or binary builds)
go run ./cli/brook/main.go client -s 127.0.0.1:9999 -p hello

• cli/brook/main.go — Entry point for the CLI tool; defines all command-line interfaces and orchestrates the server/client initialization
• client.go — Core client implementation handling proxy connections; critical for understanding the main protocol flow
• server.go — Core server implementation accepting connections; foundational for all server-side operations
• dial.go — Abstracts dial mechanisms with plugin support; determines how outbound connections are established
• dnsserver.go — DNS server implementation; core component for domain resolution interception and routing
• go.mod — Dependency manifest; essential for understanding external libraries (quic-go, utls, socks5) used throughout

Add a new dialing strategy plugin

1. Create a new plugin directory under plugins/ (e.g., plugins/dialwithproxy/) (plugins/dialwithproxy/)
2. Implement the dialer interface matching the pattern in plugins/dialwithnic/dialwithnic.go (plugins/dialwithnic/dialwithnic.go)
3. Register the plugin in the dial.go dial function or use init.go to load it dynamically (dial.go)
4. Add documentation in plugins/dialwithproxy/readme.md (plugins/readme.md)

Add a new Tengo script module for DNS/client logic

1. Create a new .tengo file under programmable/modules/ (e.g., modules/block_custom_domain.tengo) (programmable/modules/block_ad_domain.tengo)
2. Define your custom logic using Tengo syntax and Brook's runtime API (programmable/modules/_header.tengo)
3. Test the script by embedding it in programmable/client/example.tengo or programmable/dnsserver/example.tengo (programmable/client/example.tengo)
4. Register in programmable/gallery.json so it appears in the Brook Script Gallery UI (programmable/gallery.json)

Add a new CLI command

1. Open cli/brook/main.go and add a new urfave/cli v2 Command struct to the app.Commands slice (cli/brook/main.go)
2. Define the command handler (e.g., func cmdNewFeature(c *cli.Context)) and implement using core modules (cli/brook/main.go)
3. If using a new protocol or server type, add the core implementation in a new root file (e.g., newfeatureserver.go) (server.go)
4. Test the command by running brook newfeature --help and verify integration with plugins/logger if needed (init.go)

Add a new metric to Prometheus exporter

1. Open plugins/prometheus/prometheus.go and define a new prometheus.Counter or prometheus.Gauge (plugins/prometheus/prometheus.go)
2. Instrument the relevant core file (e.g., server.go, client.go, dnsserver.go) to record the metric (server.go)
3. Ensure the plugin is initialized via init.go or dynamically loaded (init.go)

• QUIC (quic-go) — Provides low-latency, UDP-based encrypted tunneling with connection multiplexing; more efficient than TCP for high-latency networks
• Tengo scripting — Embedded lightweight scripting language for runtime customization of DNS, client routing, and filtering logic without recompilation
• DNS over HTTPS (dohclient.go, dohserver.go) — Encrypts DNS queries end-to-end, preventing ISP/network-level DNS inspection and manipulation
• utls (refraction-networking/utls) — TLS fingerprint mimicry to evade network-level TLS inspection and blocking
• Plugin architecture (plugins/) — Decouples domain-specific logic (dial strategies, logging, monitoring) from core proxy; enables extensibility without modifying core
• go-cache (patrickmn/go-cache) — In-memory caching for DNS responses, routing decisions, and connection state; reduces latency and upstream load
• Prometheus client (prometheus/client_golang) — Exposes operational metrics (connections, bytes, errors) for monitoring and observability

• Programmable logic via Tengo rather than built-in rules
  • Why: Provides maximum flexibility for user-defined filtering, routing, and geo-blocking without shipping new binary versions
  • Consequence: Users must write and debug scripts; potential security risk if scripts are unt

Platform-specific code: DHCP handling differs between Linux (dhcpserver_linux.go uses netlink) and other OSes (dhcpserver_notlinux.go). Resource limits vary by platform (limits/limits.go vs limits/limits_not.go) and may require elevated privileges. Network protocol handlers expect binary compatibility with the Brook protocol specification (see link.go for protocol framing). No visible test files in provided list—testing strategy is unclear.

• SOCKS5 Proxy Protocol — Brook's primary proxy interface (txthinking/socks5 dependency); understanding SOCKS5 request/response framing is essential to modifying client/server connection handling
• QUIC (HTTP/3 Transport Protocol) — Brook uses quic-go for encrypted tunneling; QUIC provides UDP-based reliability with TLS integration, differing fundamentally from TCP proxies
• DNS over HTTPS (DoH) — dohserver.go and dohclient.go implement encrypted DNS; essential for privacy-focused deployments and understanding HTTP tunneling for non-HTTP protocols
• TLS Fingerprinting — refraction-networking/utls dependency enables evading detection; Brook can mimic browser TLS handshakes to bypass censorship, a non-standard but critical capability
• Nonce (Number Used Once) — nonce.go implements cryptographic nonce generation for replay attack prevention in protocol security; critical for understanding Brook's encryption layer
• Connection Pooling & Multiplexing — exchanger.go and packetserver.go implement connection reuse patterns; essential for understanding performance optimization in network proxies
• DHCP Server Implementation — dhcpserver.go provides network auto-configuration capabilities on OpenWrt; platform-specific netlink handling (Linux) vs. raw socket APIs (other OSes) demonstrates platform abstraction patterns

• v2ray/v2ray-core — Similar programmable proxy framework with multi-protocol support; directly comparable architecture for protocol extensibility
• txthinking/socks5 — Separate SOCKS5 implementation package that Brook imports—understanding this library is essential to comprehending Brook's proxy mechanics
• txthinking/x — txthinking's utility library imported by Brook for common Go helpers; check here for reusable patterns
• shadowsocks/shadowsocks-go — Alternative encrypted proxy tool in Go; similar use case and architecture patterns for comparison
• quic-go/quic-go — QUIC protocol implementation that Brook depends on; essential for understanding QUIC tunnel functionality

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for core dial and packet handling logic (dial.go, packetconn.go, packetserverconn.go)

The repo has no visible test files despite containing critical network I/O logic in dial.go, packetconn.go, and packetserverconn.go. These are foundational components for a 'programmable network tool' that handle connection establishment and packet routing. Adding tests would catch regressions across platforms (Linux/Windows differences are already abstracted in dhcpserver_linux.go vs dhcpserver_notlinux.go). This is especially important given the cross-platform nature and the existing platform-specific code patterns.

• [ ] Create dial_test.go with tests for dial.go connection logic
• [ ] Create packetconn_test.go for packetconn.go bidirectional packet handling
• [ ] Create packetserverconn_test.go for server-side packet connection management
• [ ] Verify tests run on both Linux and non-Linux platforms using build tags
• [ ] Add test coverage to CI workflows (update .github/workflows/static.yml or create test.yml)

Add GitHub Actions workflow for multi-platform builds and release artifacts

The repo publishes binaries for 6+ platforms (iOS, Android, macOS, Windows, Linux, OpenWrt) per README.md, but .github/workflows/ only contains static.yml. There's no visible CI for building, testing, or publishing the Brook binary across platforms. Given go.mod declares go 1.24.0, a matrix-based workflow could build for all GOOS/GOARCH targets, run tests, and create release artifacts. This prevents broken builds and ensures consistency across cli/brook/main.go outputs.

• [ ] Create .github/workflows/build.yml with matrix strategy for linux, darwin, windows, and android targets
• [ ] Build cli/brook/main.go binary for each platform combination
• [ ] Run go test ./... to verify no regressions
• [ ] Upload artifacts to releases using GitHub Actions (reference go.sum for dependency versions)
• [ ] Document platform-specific build flags needed (e.g., CGO_ENABLED for certain targets)

Add integration tests for DNS and DHCP server components (dnsserver.go, dhcpserver.go, dohclient.go, dohserver.go)

The repo contains sophisticated DNS and DHCP server implementations with platform-specific code (dhcpserver_linux.go vs dhcpserver_notlinux.go), but no visible test coverage. dnsserver.go, dohserver.go, and dhcpserver.go are critical for the server-side functionality advertised in the README. Integration tests should verify DNS query handling, DoH (DNS over HTTPS) client/server behavior, and DHCP allocation on both Linux and non-Linux systems. This prevents subtle bugs in these complex protocol implementations.

• [ ] Create dnsserver_test.go with tests for basic DNS query/response handling
• [ ] Create dohclient_test.go and dohserver_test.go for HTTPS DNS encryption workflows
• [ ] Create dhcpserver_test.go with tests for lease allocation and platform-specific code paths
• [ ] Use build tags to run platform-specific DHCP tests on linux and !linux targets
• [ ] Add integration test runner to CI (can extend .github/workflows/build.yml or static.yml)

• Add unit tests for error.go error types and wrapping behavior—currently no test coverage visible and error handling is central to reliability
• Document the Brook protocol binary format used in link.go and nonce.go with examples—new contributors need to understand wire protocol before extending
• Create integration tests for dnsserver.go + dnsclient.go pair that verify DNS query/response round-tripping through the proxy

Failed to generate security analysis.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.