A CLAUDE.md is just a markdown file at the root of your repo. Copy the content below into your own project's CLAUDE.md to give your agent the same context.
npx versuz@latest install jfernandez-bpftop --kind=claude-mdcurl -o CLAUDE.md https://raw.githubusercontent.com/jfernandez/bpftop/HEAD/CLAUDE.md# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview bpftop is a dynamic real-time view of running eBPF programs written in Rust. It displays runtime statistics, events per second, and CPU utilization for eBPF programs, using a TUI (Terminal User Interface) built with ratatui. ## Development Commands ### Building ```bash cargo build --release ``` ### Testing ```bash cargo test ``` ### Code Quality ```bash cargo clippy --all --tests --all-features --no-deps ``` ### Running ```bash # Run the application (requires sudo privileges) sudo ./target/release/bpftop ``` ## Architecture ### Core Components 1. **Main Entry** (`src/main.rs`): Handles initialization, terminal setup, main event loop, and BPF statistics collection using `BPF_ENABLE_STATS` syscall. 2. **Application State** (`src/app.rs`): Manages UI state, sorting, filtering, and view modes (tabular vs graph views). 3. **BPF Program Data** (`src/bpf_program.rs`): Represents individual eBPF programs with their statistics and handles data collection/calculation. 4. **BPF Integration** (`src/bpf/`): - `pid_iter.bpf.c`: BPF C code for iterating over programs - `pid_iter.skel.rs`: Generated skeleton from BPF code (built via `build.rs`) - Helper headers for BPF development ### Key Dependencies - **libbpf-rs**: Rust bindings for libbpf, used for BPF program interaction - **ratatui**: Terminal UI framework for the interactive display - **crossterm**: Terminal manipulation for cross-platform support - **procfs**: Reading kernel version and system information ### Build Process The project uses a build script (`build.rs`) that: 1. Compiles the BPF C code (`pid_iter.bpf.c`) 2. Generates Rust bindings (`pid_iter.skel.rs`) 3. Uses libbpf-cargo's SkeletonBuilder for BPF-to-Rust integration ### Important Notes - Requires sudo privileges to run due to BPF syscall requirements - CI uses native GitHub ARM64 runners for aarch64 builds - BPF statistics are only collected while the application is running to minimize overhead - The UI updates every second with new statistics ## Conventions ### Rust Style - Follow standard `rustfmt` formatting. Run `cargo fmt` before committing. - All clippy warnings must pass: `cargo clippy --all --tests --all-features --no-deps` - Prefer `anyhow::Result` for error propagation. Use `.context()` for meaningful error messages. - Every `unsafe` block must have a `// SAFETY:` comment explaining why it is sound. - Keep dependencies minimal. This is a single-binary tool — avoid pulling in large frameworks. ### BPF Code - BPF C code lives in `src/bpf/`. Changes here require rebuilding via `build.rs`. - BPF programs must pass the kernel verifier. Keep helpers simple and bounded. - Do not modify `pid_iter.skel.rs` directly — it is generated. ### Commits - Use conventional commit format: `type: lowercase description` - Types: `feat`, `fix`, `chore`, `ci`, `docs`, `refactor`, `test` - Write prose commit bodies explaining why, not what. No bullet lists. ### Pull Requests - PRs must pass CI on both x86_64 and aarch64 before merging. - Run `cargo clippy` and `cargo test` locally to catch issues early.