Skip to content

CLAUDE.md

Latest commit

 

History

History
140 lines (110 loc) · 5.23 KB

CLAUDE.md

File metadata and controls

140 lines (110 loc) · 5.23 KB
Raw

CLAUDE.md

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

Repository Purpose

hp (formerly hittyping) is a prettyping-style HTTP(S) latency monitor written in Go. It visualizes response times using Unicode block characters with color coding.

Build Commands

just build         # Build binary (~10MB, includes HTTP/3)
just install       # Build and install to /usr/local/bin
just run           # Build and run with default target
just test          # Run tests
just fmt           # Format code
just lint          # Run golangci-lint
just vuln          # Run vulnerability check
just ci            # Local CI (lint, vuln, test)
just clean         # Remove binary

Or directly with Go:

go build -o hp .

Or with Docker:

docker run --rm ghcr.io/colangelo/hp cloudflare.com

Usage

hp                                    # Default: https://1.1.1.1
hp dns.nextdns.io                     # Custom target (https:// auto-added)
hp -c 10 dns.nextdns.io               # Send 10 requests then exit
hp -i 500ms dns.nextdns.io            # 500ms interval (or --interval)
hp -j 200ms cloudflare.com            # Add up to 200ms random jitter to interval
hp -t 3s cloudflare.com               # 3 second timeout (or --timeout)
hp -q dns.nextdns.io                  # Quiet mode (hide header and legend)
hp -Q dns.nextdns.io                  # Silent mode (pure bar output)
hp -k https://self-signed.example     # Skip TLS verification (or --insecure)
hp -1 example.com                     # Use plain HTTP/1.1 (or --http)
hp -2 cloudflare.com                  # Force HTTP/2 (or --http2)
hp -3 cloudflare.com                  # Use HTTP/3 (or --http3)
hp -3 -d example.com                  # HTTP/3 with auto-downgrade on failures
hp -3 -D example.com                  # Auto-downgrade including plain HTTP
hp -b cloudflare.com                  # Braille mode (2x density)
hp -g 100 -y 200 8.8.8.8              # Custom thresholds (or --green, --yellow)
HTTPS_PROXY=socks5://host:port hp cloudflare.com  # Via SOCKS5 proxy

Flags

Short Long Env Var Default Description
-c --count 0 Number of requests (0 = unlimited)
-i --interval 1s Request interval
-j --jitter 0 Max random jitter to add to interval (e.g., 200ms, 3s)
-t --timeout 5s Request timeout
-b --braille false Use braille visualization (2x density)
--legend false Show legend line
--noheader false Hide header line
-q --quiet false Hide header and legend
-Q --silent false Hide header, legend, and final stats
-m --min HP_MIN 0 Min latency baseline (ms)
-g --green HP_GREEN 150 Green threshold (ms)
-y --yellow HP_YELLOW 400 Yellow threshold (ms)
-k --insecure false Skip TLS verification
-1 --http false Use plain HTTP/1.1
-2 --http2 false Force HTTP/2 (fail if not negotiated)
-3 --http3 false Use HTTP/3 (QUIC)
-d --downgrade false Auto-downgrade on 3 failures (secure only)
-D --downgrade-insecure false Auto-downgrade including plain HTTP
-v --version Show version and exit
-h --help Show help and exit

Architecture

Go application using spf13/pflag for POSIX-style CLI flags. Uses latest stable Go (currently 1.26).

Key functions:

  • measureRTT() - HEAD request timing
  • createClient() - Creates HTTP client for given protocol level
  • getURLForProto() - Returns URL with appropriate scheme for protocol
  • getBlock() - Maps latency to Unicode block + color
  • printDisplay() - Live bar and stats rendering with ANSI cursor control
  • printFinal() - Summary on Ctrl+C

Visual Output

HP dns.nextdns.io (HTTPS)
Legend: ▁▂▃<150ms ▄▅<400ms ▆▇█>=400ms !fail
▁▁▂▁▂▃▁▁
0/8 ( 0%) lost; 98/127/203ms; last: 102ms
  • Green (▁▂▃): < green threshold
  • Yellow (▄▅): < yellow threshold
  • Red (▆▇█): >= yellow threshold
  • Red bold (!): Failed request

Git Workflow

Branch protection is enabled on main. Direct pushes are blocked.

IMPORTANT: Never delete the dev branch. It is the main development branch.

Making changes to main

  1. Create a feature branch: git checkout -b fix/description
  2. Make changes and commit
  3. Push branch: git push origin fix/description
  4. Create PR: gh pr create --base main
  5. Wait for CI (lint, test, CodeQL) to pass
  6. Merge PR: gh pr merge --merge --delete-branch (OK to delete feature branches)

Releasing a new version

See docs/release-protocol.md for the complete release protocol.

Quick summary:

  1. just bump [major|minor|patch] - update version
  2. Update docs: CHANGELOG.md, ROADMAP.md, CLAUDE.md, README.md
  3. PR dev → main, merge (DO NOT delete dev branch)
  4. Tag and push: git tag -a vX.Y.Z -m "message" && git push origin vX.Y.Z
  5. Release workflow builds, signs, publishes to Homebrew/Scoop/GHCR

CI Requirements

PRs to main require:

  • lint - golangci-lint
  • test - go test
  • CodeQL - security scanning