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/cloudwego/hertz 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.

GO — Healthy across the board

• Last commit 1w ago
• 15 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 55% of recent commits

_{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 cloudwego/hertz repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/cloudwego/hertz.

What it runs against: a local clone of cloudwego/hertz — 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 cloudwego/hertz | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 38 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of cloudwego/hertz. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/cloudwego/hertz.git
#   cd hertz
#
# 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 cloudwego/hertz and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "cmd/hz/app/app.go" \\
  && ok "cmd/hz/app/app.go" \\
  || miss "missing critical file: cmd/hz/app/app.go"
test -f "cmd/hz/generator/handler.go" \\
  && ok "cmd/hz/generator/handler.go" \\
  || miss "missing critical file: cmd/hz/generator/handler.go"
test -f "cmd/hz/generator/model.go" \\
  && ok "cmd/hz/generator/model.go" \\
  || miss "missing critical file: cmd/hz/generator/model.go"
test -f "cmd/hz/generator/layout.go" \\
  && ok "cmd/hz/generator/layout.go" \\
  || miss "missing critical file: cmd/hz/generator/layout.go"
test -f "cmd/hz/config/argument.go" \\
  && ok "cmd/hz/config/argument.go" \\
  || miss "missing critical file: cmd/hz/config/argument.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 38 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~8d)"
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/cloudwego/hertz"
  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).

Hertz is a high-performance Go HTTP framework built on the Netpoll network library, designed for microservices with strong extensibility. It originated as a fasthttp fork, blends ideas from gin and echo, and is battle-tested across ByteDance's infrastructure. The framework supports HTTP/1.1 and ALPN protocols natively while prioritizing both usability and performance through a layered architecture. Monorepo structure with cmd/hz as the code generator (CLI tool for Thrift/Proto IDL scaffold), changelog/hz and changelog/ tracking version histories separately, .github/workflows/ managing CI/CD, and likely core framework code in the root or pkg/ directories (not fully visible in file list). The hz tool depends on thriftgo, protoreflect, and sprig for template-based code generation.

Go microservice developers at high-scale organizations (especially those at ByteDance) who need sub-millisecond latency, high throughput (superior QPS vs Go net), and deep customization hooks. DevOps engineers and framework maintainers also use hz (the code generator in cmd/hz) to scaffold services from Thrift IDLs.

Production-ready and actively maintained. The project shows 100k+ GitHub stars, spans 2.4M lines of Go code, maintains detailed changelogs through v0.10.4, runs comprehensive CI workflows (unit-tests.yml, pr-check.yml, vulncheck.yml), and is widely deployed inside ByteDance. The framework has evolved through 40+ releases with stable API contracts.

Low-to-moderate risk. The codebase is owned by CloudWeGo (ByteDance's open-source org), reducing single-maintainer risk. Dependency surface is reasonable (Masterminds/sprig, thriftgo, protoreflect, urfave/cli in hz alone). Main risks: Netpoll is a custom network library requiring deep understanding; breaking changes may occur between minor versions (v0.x.y semver); limited external ecosystem compared to gin/echo.

Recent releases span v0.10.0–v0.10.4 with active changelog entries. CI workflows (unit-tests.yml, cmd-tests.yml, pr-check.yml, vulncheck.yml) run on every PR. Security scanning (vulncheck.yml) is enabled. The hz tool is being enhanced with thriftgo v0.4.2+ and protobuf v1.28.0 support. ROADMAP.md exists, indicating planned features beyond the current stable feature set.

git clone https://github.com/cloudwego/hertz.git
cd hertz
make  # See Makefile for build targets
# For the hz CLI tool specifically:
cd cmd/hz
go install ./...
hz --help

Daily commands: The framework itself is a library—imported into user code. The hz CLI tool (code generator) runs: hz new --module=github.com/example/svc --idl=./api.thrift. The core Hertz server starts with h := hertz.Default() then h.Run() in user applications. See examples/ directory (inferred from typical Go project structure) for runnable demos.

• cmd/hz/app/app.go — Entry point for the hz code generator CLI tool; orchestrates IDL parsing and code generation workflows.
• cmd/hz/generator/handler.go — Core logic for HTTP handler code generation from IDL definitions; essential for understanding request routing patterns.
• cmd/hz/generator/model.go — Data model generation pipeline that converts IDL types into Go struct definitions; foundational for type safety.
• cmd/hz/generator/layout.go — Project structure templating system that defines the scaffold layout for generated Hertz applications.
• cmd/hz/config/argument.go — CLI argument parsing and validation; critical for understanding how hz accepts configuration from users.
• cmd/hz/generator/client.go — HTTP client code generation for consuming Hertz services; mirrors handler generation for bidirectional communication.
• cmd/hz/generator/model/golang/file.go — Go-specific code generation utilities including imports, package declarations, and file I/O handling.

• CLI & Argument Parser (config/argument.go) (urfave/cli, Go flag parsing) — Accepts user input (IDL paths, output directory, code generation flags) and validates configuration
  • Failure mode: Invalid CLI arguments cause early exit with error message; users must retry with corrected arguments
• IDL Parser (generator/handler.go, model.go) (cloudwego/thriftgo, jhump/protoreflect) — Converts Thrift/Protobuf definitions into an intermediate AST representation
  • Failure mode: Malformed IDL files cause parse errors; generated code is incomplete until IDL is corrected
• Go Code Emitter (generator/model/golang/*) (Go AST primitives, template rendering) — Generates syntactically correct Go code (functions, structs, imports) from AST nodes
  • Failure mode: Code generation bugs produce invalid Go that fails compilation; requires debugging AST traversal logic
• File & Template Engine (generator/layout.go, layout_tpl.go) (Go text/template, filepath operations) — Manages project structure scaffolding and file output; applies user-provided template overrides
  • Failure mode: Missing or corrupt template files cause incomplete project scaffolds; file write errors if disk is full or permissions are denied
• Handler/Model/Client Generators (generator/*.go) (Recursive AST traversal, Go code string concatenation) — Orchestrates code generation for HTTP handlers, request/response models, and client stubs
  • Failure mode: Unsupported IDL patterns (e.g., circular type references) produce incorrect or

Add a new Thrift/Protobuf IDL handler

1. Implement a new handler function in the generator to process Thrift or Protobuf service definitions (cmd/hz/generator/handler.go)
2. Register handler with the main generator pipeline in app initialization (cmd/hz/app/app.go)
3. Add template mappings if handler generates Go-specific code structures (cmd/hz/generator/model/golang/file.go)

Add support for a new code generation feature (e.g., middleware)

1. Define the feature model and configuration options (cmd/hz/config/argument.go)
2. Implement generation logic in the appropriate generator module (handler/model/client) (cmd/hz/generator/handler.go)
3. Add corresponding template files and layout updates (cmd/hz/generator/layout.go)
4. Update project scaffold template if the feature requires new file structure (cmd/hz/generator/layout_tpl.go)

Extend Go code generation for a new language construct

1. Add new AST node type or extend existing definition model (cmd/hz/generator/model/define.go)
2. Implement Go emitter for the new construct (function, type, interface, etc.) (cmd/hz/generator/model/golang/function.go)
3. Wire the new emitter into the code generation pipeline (cmd/hz/generator/model/golang/file.go)
4. Add test cases to validate generated code correctness (cmd/hz/generator/handler_test.go)

Add a new CLI flag or configuration option

1. Define the flag and its validation logic in argument parsing (cmd/hz/config/argument.go)
2. Propagate the flag through the generator context (cmd/hz/app/app.go)
3. Conditionally apply feature logic in handler or model generators based on flag state (cmd/hz/generator/handler.go)

• Thriftgo + Protoreflect — Supports both Thrift and Protobuf IDLs; enables multi-protocol microservice definition
• Go templates (sprig) — Flexible templating for generating project scaffolds and layout variations
• urfave/cli — Robust CLI framework for argument parsing and command routing
• AST-based code generation — Preserves semantic structure and enables precise control over generated Go code quality and idioms

• Monolithic hz tool vs. plugin-based extensibility

  • Why: Simplifies distribution and ensures consistent code generation across all users
  • Consequence: Adding new IDL formats or code generation features requires core repo changes rather than external plugins

• Code generation over runtime reflection

  • Why: Generates explicit, debuggable Go code that integrates naturally with IDE tooling and static analysis
  • Consequence: Users must re-generate after IDL changes; no dynamic route discovery at runtime

• Template-based layout scaffolding

  • Why: Allows customization of project structure without hardcoding assumptions
  • Consequence: Templates can become stale or misaligned with idiomatic Hertz project structure if not maintained

• Does not execute or run generated code; purely a code generation tool
• Does not provide the Hertz HTTP framework itself—only generates boilerplate that consumes it
• Does not support custom IDL languages beyond Thrift and Protobuf
• Does not validate runtime correctness of generated handlers—validation is pre-generation only

The hz tool requires thriftgo and Protocol Buffer compilers installed locally (not bundled in go.mod alone). The framework uses Netpoll, not Go's standard net library, requiring different tuning parameters for high concurrency. semver is loose (v0.x.y means breaking changes can occur in minor versions). No obvious environment variables required, but deployment in ByteDance's ecosystem may assume specific monitoring/config patterns not documented here.

• Netpoll (non-blocking I/O multiplexing) — Hertz's core performance advantage; understanding epoll/kqueue-based multiplexing explains why Hertz outperforms Go net in QPS benchmarks
• IDL-driven code generation (hz tool) — The hz CLI generates boilerplate from Thrift/Protobuf specs; learning how thriftgo and sprig templates work is essential for extending code generation
• Layered architecture with extension interfaces — Hertz's core design philosophy; understanding where middleware, codecs, and protocol handlers plug in enables custom extensions
• ALPN (Application-Layer Protocol Negotiation) — Hertz natively supports ALPN for HTTP/1.1 and protocol upgrades; critical for microservices using h2c or mixed protocol stacks
• Request/response middleware chain pattern — Like gin and echo, Hertz uses middleware chaining for cross-cutting concerns; this is the primary extension point for auth, logging, and observability
• Microsecond-scale latency optimization — Hertz benchmarks focus on sub-millisecond latencies; understanding allocation escapes, buffer pooling, and zero-copy patterns is necessary for core contributions

• cloudwego/netpoll — The underlying high-performance network I/O library that Hertz depends on; understanding netpoll is essential for Hertz optimization
• gin-gonic/gin — Hertz's API design inspiration; gin users will recognize the handler and middleware patterns
• labstack/echo — Another API design inspiration and direct competitor; Echo users may consider migrating to Hertz for higher throughput
• cloudwego/thriftgo — The Thrift compiler dependency for hz; Thrift IDL support in Hertz projects requires thriftgo
• cloudwego/hertz-benchmark — Performance comparison suite referenced in the README; the canonical source for Hertz vs. gin/echo/fasthttp benchmarks

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 comprehensive CI workflow for cmd/hz code generation tool testing

The repo has .github/workflows/cmd-tests.yml but given the complexity of the hz code generator (which handles Thrift, Protobuf, and template generation based on dependencies like thriftgo, protoreflect, and sprig), there's an opportunity to expand CI coverage. The changelog shows numerous hz versions (v0.3.0 through v0.9.1 with separate tracking), indicating this is a critical tool. A dedicated workflow should test code generation across different IDL formats and validate generated code compiles correctly.

• [ ] Review existing .github/workflows/cmd-tests.yml and identify gaps in IDL format coverage (Thrift vs Protobuf generation)
• [ ] Create integration tests in cmd/hz that verify generated code compiles for sample Thrift and Protobuf definitions
• [ ] Extend .github/workflows/cmd-tests.yml to run these integration tests on PRs, validating code generation doesn't break across versions

Add missing documentation for cmd/hz CLI tool in CONTRIBUTING.md

The CONTRIBUTING.md exists but likely lacks specific guidance for contributors working on the hz code generation tool. Given the tool's complexity (handling Thrift IDL parsing via thriftgo, Protobuf via protoreflect, and template rendering via sprig), new contributors need clear setup and testing instructions. The separate changelog tracking for hz/ versions suggests this deserves dedicated documentation.

• [ ] Review CONTRIBUTING.md to identify missing sections on hz tool development workflow
• [ ] Document how to set up development environment with thriftgo, protoc, and test IDL files
• [ ] Add section explaining the template system (sprig v3) and how to test code generation changes

Add vulnerability scanning workflow for transitive dependencies in cmd/hz go.mod

While .github/workflows/vulncheck.yml exists at the repo level, the cmd/hz module has its own go.mod with dependencies like github.com/cloudwego/thriftgo (with a date-stamped pre-release version), google.golang.org/protobuf, and github.com/urfave/cli/v2. These need separate vulnerability tracking since cmd/hz is a distributed tool that users install directly. The current setup likely only checks the root module.

• [ ] Review .github/workflows/vulncheck.yml to confirm it scans cmd/hz/go.mod dependencies
• [ ] If not covered, add a workflow step or dedicated workflow that runs govulncheck ./cmd/hz/... on PRs and pushes
• [ ] Document the vulnerability scanning process in CONTRIBUTING.md for contributors modifying cmd/hz dependencies

• Add integration tests for the hz code generator with Protocol Buffers v1.28.0+ (cmd-tests.yml currently exists but coverage unclear; check for missing test cases in cmd/hz/pkg/codegen or equivalent)
• Document the Netpoll-specific tuning parameters and how they differ from Go net (likely a docs PR adding a 'Performance Tuning' section referencing ROADMAP.md)
• Create examples/ directory examples for common microservice patterns (gRPC interop, middleware chain, graceful shutdown) if not already comprehensive; the README shows performance graphs but no runnable demos

The Hertz HTTP framework codebase shows a moderate security posture with several areas requiring attention. The primary concerns are outdated dependencies (protobuf, golang.org/x/tools) that may contain known vulner

• High · Outdated Protobuf Dependency — cmd/hz/go.mod - google.golang.org/protobuf v1.28.0. The dependency google.golang.org/protobuf v1.28.0 is outdated. Current versions have addressed multiple security vulnerabilities. Version 1.28.0 was released in 2022 and lacks patches for known vulnerabilities in protobuf message deserialization. Fix: Update to the latest stable version of google.golang.org/protobuf (v1.31.0 or later). Run 'go get -u google.golang.org/protobuf@latest' to patch known vulnerabilities.
• High · Outdated golang.org/x/tools Dependency — cmd/hz/go.mod - golang.org/x/tools v0.6.0. The dependency golang.org/x/tools v0.6.0 is outdated and may contain security vulnerabilities. This package is part of the Go standard library ecosystem and receives regular security updates. Fix: Update to a more recent version of golang.org/x/tools. Run 'go get -u golang.org/x/tools@latest' to obtain security patches.
• Medium · Potential YAML Parsing Vulnerabilities — cmd/hz/go.mod - gopkg.in/yaml.v2 v2.4.0. The dependency gopkg.in/yaml.v2 v2.4.0 is used for YAML processing. While v2.4.0 is relatively recent, YAML parsing can be vulnerable to billion laughs attacks and unsafe deserialization. This is particularly concerning if user-supplied YAML is parsed. Fix: Ensure all YAML parsing is restricted to safe inputs. Consider migrating to gopkg.in/yaml.v3 which has improved security. Implement input validation before YAML parsing and disable dangerous YAML features if possible.
• Medium · Outdated CLI Framework — cmd/hz/go.mod - github.com/urfave/cli/v2 v2.23.0. The dependency urfave/cli/v2 v2.23.0 is outdated. While CLI frameworks typically have lower security impact, staying current ensures bug fixes and security patches are applied. Fix: Update to the latest version of urfave/cli/v2. Run 'go get -u github.com/urfave/cli/v2@latest'.
• Medium · Code Generation Tool Dependency Risk — cmd/hz/go.mod - github.com/cloudwego/thriftgo v0.4.2-0.20250604064713-0e1e704080b1. The project uses cloudwego/thriftgo v0.4.2-0.20250604064713-0e1e704080b1 for code generation. Code generators are high-risk components as they directly produce executable code. This version uses a development timestamp which may indicate unstable/unreleased code. Fix: Review the thriftgo version and consider using official releases instead of development snapshots. Validate generated code before deployment. Implement CI/CD checks to scan generated code for vulnerabilities.
• Low · Missing Security Configuration Documentation — README.md. The README snippet does not mention security best practices, vulnerability disclosure policy, or security contact information. Fix: Add a SECURITY.md file with: vulnerability disclosure policy, security contact information, supported versions for security updates, and security best practices for users of the framework.
• Low · No SBOM or Dependency Scanning Documented — .github/workflows/vulncheck.yml (referenced but content not provided). While a vulncheck.yml workflow exists, there is no evidence of automated dependency vulnerability scanning or Software Bill of Materials (SBOM) generation in the visible configuration. Fix: Ensure vulncheck.yml is configured to run 'go list -json -m all' through nancy/gosec. Generate and publish SBOMs for releases. Consider using GitHub's Dependabot for automated dependency updates.

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.