yoloyolo/CLAUDE.md

Project

NetSynth

A Go CLI tool that captures live network traffic on an interface, clusters and classifies the packets by protocol/pattern, and synthesizes an ambient MP3 soundscape where each traffic type produces a distinct harmonic drone or tone. Run it, let it listen, hit Ctrl+C, and get an audio fingerprint of your network.

Core Value: Network traffic patterns are instantly recognizable as distinct sounds — a ping sounds different from HTTPS noise, which sounds different from a port scan.

Constraints

• Language: Go — user preference, single binary output
• Privileges: Packet capture requires root/CAP_NET_RAW on Linux
• Audio format: MP3 output (not WAV or raw PCM)
• Interaction model: Non-interactive capture (run → Ctrl+C → file saved)

Technology Stack

Recommended Stack

Core Technologies

Technology	Version	Purpose	Why Recommended
github.com/gopacket/gopacket	v1.5.0	Packet capture, protocol decoding	The canonical Go packet library. Community fork (gopacket/gopacket) supersedes the original Google repo (google/gopacket) as of 2024; released v1.5.0 in November 2025, minimum Go 1.24. 14.5k dependents; has ICMP, TCP, UDP, DNS, TLS layer decoders built in.
github.com/packetcap/go-pcap	v0.0.0-20251215	Pure-Go live packet capture backend	Replaces CGo libpcap dependency for live capture. 100% native Go, Linux + macOS, mmap-based kernel ring buffer for performance. Implements the gopacket.PacketDataSource interface so gopacket decodes packets on top of it. Enables CGO_ENABLED=0 builds and cross-compilation.
github.com/sjzar/go-lame	v0.0.9	MP3 encoding	Embeds libmp3lame C source directly via CGo — no external libmp3lame system package required. Published April 2025. Exposes sample rate, channels, quality control. Produces LAME-quality MP3, unlike the pure-Go shine-mp3 port which produces larger, lower-quality output. Tradeoff: requires CGo, so CGO_ENABLED=1 and a C compiler at build time.
github.com/spf13/cobra	v1.10.2	CLI flag parsing and command structure	The industry standard for Go CLIs (Kubernetes, Docker, Hugo, etc.). v1.10.2 released December 2025. Handles --interface, --output flags, Ctrl+C signal plumbing, and --help generation automatically. No alternatives worth considering for this scope.

Supporting Libraries

Library	Version	Purpose	When to Use
github.com/muesli/kmeans	v0.3.1	K-means clustering for unrecognized traffic patterns	Use to auto-cluster packets that don't match known protocol rules. Feed feature vectors: [port, protocol_num, packet_size_bin, direction]. Last release July 2022 but mathematically stable; the algorithm doesn't change. Alternatively, implement a simple incremental classifier directly (see Architecture notes below).
github.com/go-audio/wav	latest	WAV file I/O as intermediate format	Optional. Originally recommended for PCM intermediate buffering, but Phase 2 research found that go-audio/wav requires io.WriteSeeker (which bytes.Buffer does not satisfy) and adds unnecessary complexity. The simpler approach is writing interleaved int16 PCM bytes directly to go-lame's LameWriter.Write(). Skip unless a WAV debug output feature is needed. Decision made under CONTEXT.md Claude's Discretion grant for "WAV intermediate format usage."
golang.org/x/sys/unix	stdlib	Raw socket / CAP_NET_RAW privilege checks	Use for detecting if the process has required privileges and for signaling (SIGINT for clean shutdown). Part of Go extended stdlib — no external version pinning needed.

Development Tools

Tool	Purpose	Notes
go build -ldflags="-s -w"	Stripped binary production builds	Reduces binary size significantly; combine with upx if size is critical
goreleaser	Cross-platform release builds	Handles CGo cross-compilation complexity with Docker-based build matrix; useful for distributing Linux x86_64 + ARM64 binaries
golangci-lint	Static analysis	Catches nil pointer dereferences common in packet-handling code
Wireshark / tcpdump	Manual verification of packet capture	Essential for confirming gopacket is decoding the right protocols before plugging into audio synthesis

Installation

Initialize module

Core dependencies

Supporting

Build (CGo required for go-lame)

OR: grant capability instead of running as root

Alternatives Considered

Recommended	Alternative	When to Use Alternative
gopacket/gopacket (community fork)	google/gopacket (original)	Never for new projects — original repo has 270 open issues, community fork actively merges fixes
packetcap/go-pcap (pure Go)	gopacket/pcap (CGo + libpcap)	Use libpcap path only if you need advanced BPF filter syntax or BSD/Windows support — it requires libpcap-dev system package
sjzar/go-lame (embedded C source)	braheezy/shine-mp3 (pure Go)	Use shine-mp3 if CGo is truly impossible (e.g., WASM target) — but accept that output quality and file size are worse
sjzar/go-lame (embedded C source)	viert/go-lame (dynamic link)	Never — viert/go-lame requires libmp3lame installed on the target system, defeating single-binary distribution
Hand-rolled additive synthesis	dasa.cc/snd, bspaans/bleep	Use a library only if you need MIDI scheduling or real-time playback; for file output, the synthesis math is simple enough to own directly (see Architecture notes)
muesli/kmeans	mpraski/clusters	Use mpraski if you need online (incremental) clustering — it supports add-one-point updates vs muesli's batch-only approach

What NOT to Use

Avoid	Why	Use Instead
google/gopacket (original)	Effectively unmaintained since 2022; 270 open issues, PRs not merged	github.com/gopacket/gopacket (community fork, v1.5.0)
viert/go-lame or sunicy/go-lame	Dynamic-links against system libmp3lame — breaks single-binary distribution, fails on machines without the library	github.com/sjzar/go-lame (embeds C source statically)
braheezy/shine-mp3 (pure Go MP3)	Last commit 2023, explicitly not production-ready per its own README, produces larger lower-quality files, no bitrate control	sjzar/go-lame for quality, or WAV output if you must avoid CGo
go-audio/generator	Archived February 2026, read-only — do not take a new dependency on it	Write your own oscillator (20 lines of Go) or use dasa.cc/snd
faiface/beep	Designed for real-time audio playback via PortAudio/oto; pulls in platform audio drivers that are irrelevant for file output	Roll a minimal additive synthesizer directly (see below)
dasa.cc/snd	Plays audio through hardware; brings in real-time audio scheduling complexity unnecessary for batch file output	Roll a minimal additive synthesizer directly
urfave/cli	Fine for simpler tools, but Cobra's flag validation, help generation, and signal handling are better for a tool with multiple flags and clean shutdown semantics	github.com/spf13/cobra

Stack Patterns by Variant

• Use sjzar/go-lame for real MP3 quality
• Use packetcap/go-pcap for the capture layer (pure Go on Linux/macOS)
• Build with CGO_ENABLED=1; single binary is still self-contained because LAME C source is embedded
• Use braheezy/shine-mp3 for MP3 — accept lower quality and larger files
• Use packetcap/go-pcap for capture — already pure Go
• Build with CGO_ENABLED=0; truly static binary
• Consider packetcap/go-pcap's mmap ring buffer mode for high-traffic interfaces (default on Linux)
• Privilege: CAP_NET_RAW setcap is cleaner than running as root

Version Compatibility

Package	Compatible With	Notes
gopacket/gopacket@v1.5.0	Go 1.24+	v1.5.0 bumped minimum Go to 1.24; use Go 1.24.x toolchain
packetcap/go-pcap	Linux, macOS (Darwin)	No Windows support; this is acceptable per project constraints
sjzar/go-lame@v0.0.9	Any Go + C compiler; CGO_ENABLED=1	Embeds LAME C source; no system library dependency
spf13/cobra@v1.10.2	Go 1.20+	No issues with Go 1.24
muesli/kmeans@v0.3.1	Go 1.12+	Stable; no compatibility concerns

Audio Synthesis Architecture Note

Sources

• github.com/gopacket/gopacket releases page — v1.5.0 confirmed, November 2025
• pkg.go.dev/github.com/packetcap/go-pcap — v0.0.0-20251215, pure Go, Linux/macOS confirmed
• pkg.go.dev/github.com/sjzar/go-lame — v0.0.9, April 2025, embedded C source confirmed
• pkg.go.dev/github.com/spf13/cobra — v1.10.2, December 2025
• github.com/go-audio/generator — archived February 2026 (read-only), do not use
• braheezy.github.io/posts/what-i-learned-about-mp3-encoding/ — author's first-hand account of Go MP3 encoding options, concluded shine-mp3 is not production-grade
• github.com/google/gopacket/issues/1016 — maintenance status discussion confirming community fork is preferred
• WebSearch: muesli/kmeans v0.3.1 last release July 2022 — LOW confidence on ongoing maintenance, but algorithm is stable
• WebSearch: cobra v1.9.1/v1.10.2 — MEDIUM confidence, confirmed via pkg.go.dev

Conventions

Conventions not yet established. Will populate as patterns emerge during development.

Architecture

Architecture not yet mapped. Follow existing patterns found in the codebase.

GSD Workflow Enforcement

Before using Edit, Write, or other file-changing tools, start work through a GSD command so planning artifacts and execution context stay in sync.

Use these entry points:

• /gsd:quick for small fixes, doc updates, and ad-hoc tasks
• /gsd:debug for investigation and bug fixing
• /gsd:execute-phase for planned phase work

Do not make direct repo edits outside a GSD workflow unless the user explicitly asks to bypass it.

Developer Profile

Profile not yet configured. Run /gsd:profile-user to generate your developer profile. This section is managed by generate-claude-profile -- do not edit manually.