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/flamegraph-rs/flamegraph 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 2w ago
• 27+ active contributors
• Distributed ownership (top contributor 36% of recent commits)
• Apache-2.0 licensed
• CI configured
• ⚠ No test directory detected

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

What it runs against: a local clone of flamegraph-rs/flamegraph — 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 flamegraph-rs/flamegraph | 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 ≤ 43 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "flamegraph-rs/flamegraph(\\.git)?\\b" \\
  && ok "origin remote is flamegraph-rs/flamegraph" \\
  || miss "origin remote is not flamegraph-rs/flamegraph (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 "src/lib.rs" \\
  && ok "src/lib.rs" \\
  || miss "missing critical file: src/lib.rs"
test -f "src/bin/cargo-flamegraph.rs" \\
  && ok "src/bin/cargo-flamegraph.rs" \\
  || miss "missing critical file: src/bin/cargo-flamegraph.rs"
test -f "src/bin/flamegraph.rs" \\
  && ok "src/bin/flamegraph.rs" \\
  || miss "missing critical file: src/bin/flamegraph.rs"
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 43 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~13d)"
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/flamegraph-rs/flamegraph"
  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).

flamegraph-rs is a Rust-native flamegraph generator that profiles any executable (Rust projects, arbitrary binaries, or systems) without requiring Perl, pipes, or external flamegraph.pl scripts. It wraps the Inferno library to generate interactive SVG flamegraphs from perf (Linux), xctrace (macOS), or blondie (Windows) profiling data, and provides a cargo flamegraph subcommand for seamless Cargo project integration. Dual-binary structure: src/bin/cargo-flamegraph.rs handles Cargo integration (metadata parsing, dependency resolution), while src/bin/flamegraph.rs is a standalone CLI wrapper. The src/lib.rs exports shared profiling logic. Platform-specific conditionals (cfg attributes) route to perf on Linux, xctrace on macOS, or blondie on Windows. Dependencies like cargo_metadata and clap_complete support CLI parsing and shell completion generation.

Rust developers and systems engineers who need to profile and optimize their applications' CPU performance. Primary users are Cargo project maintainers who want one-command profiling without installing Perl dependencies, and performance engineers analyzing any binary across Linux, macOS, and Windows.

Actively maintained and production-ready. The project is at v0.6.12 with a solid CI/CD pipeline (GitHub Actions in .github/workflows/ci.yml), uses modern Rust 1.86+ MSRV, and has two stable binary outputs (cargo-flamegraph and flamegraph). It's built on the well-established Inferno library and is widely used in the Rust community for performance profiling.

Standard open source risks apply.

The repo is actively maintained (Rust 1.90.0+ compatibility work visible in README), with recent updates documenting lld/mold linker issues and the --no-rosegment flag requirement for accurate perf traces. Dependabot automation (deny.toml, .github/dependabot.yml) suggests active dependency management. No specific PR or milestone data visible, but the README tip about samply indicates the team is aware of competitive tooling.

git clone https://github.com/flamegraph-rs/flamegraph.git
cd flamegraph
cargo build --release
cargo install --path .
# For Rust project profiling:
cargo flamegraph
# For arbitrary binary profiling:
flamegraph -- /path/to/binary

Daily commands:

cargo build
# Run tests (if present):
cargo test
# Install locally:
cargo install --path .
# Profile a Rust project:
cd /path/to/rust/project && cargo flamegraph
# Profile arbitrary binary:
flamegraph -- /usr/bin/target_binary arg1 arg2

• src/lib.rs — Core library API exposing flamegraph generation logic; all flamegraph operations route through here
• src/bin/cargo-flamegraph.rs — Cargo subcommand entry point; handles cargo-specific argument parsing and build orchestration
• src/bin/flamegraph.rs — Standalone CLI binary entry point; main user-facing interface for non-cargo flamegraph profiling
• Cargo.toml — Project manifest defining dependencies (inferno, clap, cargo_metadata) and platform-specific features
• README.md — Comprehensive usage guide showing quick-start patterns and platform-specific profiling setup (Linux/macOS/Windows)

• cargo-flamegraph CLI (src/bin/cargo-flamegraph.rs) (clap, cargo_metadata, std::process) — Parses cargo-specific args, invokes cargo build with release profile, collects binary path, delegates profiling to core lib
  • Failure mode: Fails if Cargo.toml not found, binary build fails, or profiler not available; reports error with context
• flamegraph CLI (src/bin/flamegraph.rs) (clap, std::path, std::process) — Parses binary path and arguments, validates binary exists, delegates to core lib for profiling
  • Failure mode: Fails if binary not found or not executable; graceful error message
• Core profiler (src/lib.rs) (std::process, std::env, inferno, indicatif) — Detects OS, invokes appropriate profiler (perf/xctrace/blondie), collects stack traces, delegates rendering to inferno
  • Failure mode: Profiler not found: instructs user to install (perf/xctrace); insufficient permissions: reports EACCES; invalid binary: reports ENOENT
• inferno (external crate) (Rust (no external deps), SVG generation) — Merges stack samples, generates colorized SVG flamegraph; does not perform I/O except final SVG write
  • Failure mode: Stack trace parsing failure: typically recovers gracefully; OOM on very large traces: rare in practice

• User shell → cargo-flamegraph.rs / flamegraph.rs — Command-line arguments (binary path, profiler options, output file)
• cargo-flamegraph.rs → cargo — Invokes cargo build with --release flag and target/bin path extraction
• src/lib.rs → perf / xctrace / blondie — Spawns subprocess with perf record / xctrace record / native blondie sampling
• perf / xctrace / blondie → src/lib.rs — Returns stack traces in perf.data / xctrace XML / native format; converted to flamegraph input
• src/lib.rs → inferno crate — Passes merged stack traces (Vec<StackFrame>) to inferno::flamegraph() function
• inferno crate → flamegraph.svg —

Add support for a new profiling backend (e.g., alternative to perf/xctrace)

1. Add feature flag and conditional compilation block in Cargo.toml for the new backend (Cargo.toml)
2. Implement platform-specific profiler invocation in src/lib.rs; follow existing perf/xctrace conditional logic (src/lib.rs)
3. Add CLI flag to both cargo-flamegraph.rs and flamegraph.rs to allow users to select the backend (src/bin/cargo-flamegraph.rs)
4. Document new backend in README.md platform-specific installation section (README.md)

Add a new command-line option or configuration parameter

1. Define new clap derive struct field in either cargo-flamegraph.rs or flamegraph.rs with #[arg(...)] attribute (src/bin/flamegraph.rs)
2. Pass parsed argument through to the library function in src/lib.rs; update function signature if needed (src/lib.rs)
3. Implement logic to use the parameter in flamegraph generation or perf invocation (src/lib.rs)
4. Update README.md with usage example and description of the new option (README.md)

Improve flamegraph rendering or filtering output

1. Review inferno dependency version in Cargo.toml; consider upgrading if new rendering features exist (Cargo.toml)
2. Modify src/lib.rs to pass additional options to inferno's flamegraph generation call (src/lib.rs)
3. Expose new rendering options via CLI flags in src/bin/flamegraph.rs and src/bin/cargo-flamegraph.rs (src/bin/cargo-flamegraph.rs)

• Inferno (flamegraph rendering library) — Pure Rust flamegraph generator eliminates dependency on Perl + pipes; integrates seamlessly with Rust ecosystem
• clap (CLI argument parsing) — Modern derive-based CLI framework simplifies argument definition and validation for both cargo subcommand and standalone binary
• cargo_metadata — Parses Cargo.toml metadata to understand project structure and invoke cargo build with correct target/release flags
• perf (Linux), xctrace (macOS), blondie (Windows) — Delegates OS-specific stack sampling to battle-tested platform profilers; flamegraph-rs provides unified Rust interface
• indicatif (progress bars) — Provides user-friendly progress feedback during potentially long profiling sessions

• Dual binary design (cargo-flamegraph.rs + flamegraph.rs)

  • Why: Allows both cargo integration (for Rust projects) and standalone profiling (for any binary or language)
  • Consequence: Code duplication in CLI parsing; requires maintaining two entry points

• Platform-specific profiler delegates (perf/xctrace/blondie) vs. unified profiling library

  • Why: Leverages native OS profilers which have best-in-class performance and kernel integration; avoids reimplementing low-level sampling
  • Consequence: Requires platform detection logic; installation docs must cover each OS separately

• Synchronous, blocking profiling workflow

  • Why: Simpler UX: user runs command, waits for flamegraph, opens result; matches shell tool expectations
  • Consequence: Cannot profile long-running services without explicit time limits; progress bar (indicatif) mitigates UX friction

• Real-time interactive profiling UI (see samply recommendation in README for better UI)
• Cross-compilation flamegraph generation (must run profiler on target OS/architecture)
• Profiling without native OS profiler installed (perf/xctrace/blondie must be available)
• Handling authentication or secure code signing workflows beyond basic binary execution
• Language-agnostic source line attribution (limited to symbols available in binary; Rust has best support)

1. Linux perf profiling requires --no-rosegment linker flag when using lld (default since Rust 1.90.0) or mold; omitting this will cause inaccurate/empty stack traces (documented in README but easy to miss). 2) macOS requires xctrace (Xcode tooling); the quick-xml dependency is only compiled on macOS and parses xctrace output—ensure Xcode is installed. 3) Windows requires blondie OR dtrace; blondie is a native dependency and may have platform-specific build requirements. 4) cargo flamegraph only works within Cargo projects; passing a non-Cargo path will fail silently or with unclear errors. 5) Signal handling (Ctrl+C) is Unix-only; Windows uses a different code path via blondie that may not gracefully handle interruption.

• Stack sampling and perf — flamegraph-rs core function is orchestrating perf record/script (Linux), xctrace (macOS), or blondie (Windows) to sample call stacks; understanding how perf works and its sampling rate/overhead is critical for interpreting profiles correctly
• Flamegraph visualization — The output is an interactive SVG flamegraph where x-axis = time, y-axis = call stack depth, and width = CPU time spent; this is the fundamental abstraction that Inferno renders and this tool wraps
• Symbol demangling (Rust) — Raw perf output contains mangled Rust symbols (e.g., _ZN4core...); flamegraph-rs uses rustc-demangle to convert these to human-readable function names, essential for interpreting profiles
• Cargo subcommands and cargo-metadata — The cargo-flamegraph binary is a Cargo plugin that parses Cargo.toml and workspace metadata to profile Cargo projects; understanding cargo_metadata crate and Cargo plugin conventions is needed to modify integration behavior
• [Platform-specific profiling backends (perf, xctrace, blondie)](https://developer.apple.com/documentation/os/instruments and https://github.com/nico-abram/blondie) — flamegraph-rs abstracts over three OS-specific profilers with different output formats and APIs; maintaining cross-platform support requires understanding each backend's quirks (e.g., xctrace XML parsing, blondie native API)
• ROsegment and linker security features — Modern linkers (lld, mold) default to RO segments for security, which breaks perf's symbol resolution; the --no-rosegment flag disables this, a footgun that affects Linux users on Rust 1.90.0+
• SVG and interactive visualization — Inferno outputs interactive SVG flamegraphs that can be zoomed, clicked, and searched in a browser; understanding SVG generation and the interactive features helps troubleshoot rendering or performance issues

• jonhoo/inferno — The core flamegraph rendering library that flamegraph-rs wraps; understanding Inferno's API is essential for modifying flamegraph generation logic
• mstmange/samply — Modern alternative profiler written in Rust with Firefox Profiler UI integration; recommended in the README as a potentially superior interactive alternative with better macOS support
• flamegraph-rs/flamegraph-rs.github.io — Official documentation and landing page for the flamegraph-rs project; linked from the repo for deployment and marketing information
• rust-lang/rustup — Rust toolchain installer; flamegraph-rs requires Rust 1.86+ MSRV and relies on rustup for cross-platform installation and toolchain management
• cargo-profiling/cargo-expand — Complementary Cargo subcommand ecosystem tool; users of cargo-flamegraph are likely interested in other profiling and debugging subcommands

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 integration tests for cargo-flamegraph and flamegraph binaries

The repo has two main binaries (cargo-flamegraph and flamegraph) but no visible test directory structure. Integration tests would validate end-to-end flamegraph generation across different platforms and scenarios, improving reliability and preventing regressions. This is particularly important given the platform-specific dependencies (signal-hook for Unix, blondie for Windows, quick-xml for macOS).

• [ ] Create tests/ directory with integration test structure
• [ ] Add test case validating flamegraph generation with a simple test binary
• [ ] Add platform-specific tests using cfg attributes to verify Unix/Windows/macOS code paths
• [ ] Test cargo-flamegraph integration with a minimal test Cargo project
• [ ] Validate output SVG generation and basic flamegraph structure

Add cargo-generate-completion to generate shell completions for all shells

The Cargo.toml includes clap_complete dependency but there's no visible mechanism to generate and distribute shell completions. Adding a build script or separate binary to generate completions for bash, zsh, fish, and powershell would improve user experience. This is a concrete feature gap given the dependency is already included.

• [ ] Add build.rs script or update src/bin/cargo-flamegraph.rs to support --generate-completions flag
• [ ] Generate completions for bash, zsh, fish, and powershell shells using clap_complete
• [ ] Add completions/ directory and document installation in README.md for each shell
• [ ] Update .gitignore to include generated completion files if needed
• [ ] Add CI step in .github/workflows/ci.yml to verify completions generate without error

Add architectural documentation explaining the Unix/Windows/macOS platform abstraction layer

The Cargo.toml shows significant platform-specific dependencies (signal-hook, blondie, quick-xml) indicating complex platform differences, but there's no documentation explaining how these are used or what platform-specific code paths exist. Adding a ARCHITECTURE.md or similar would help new contributors understand the codebase structure and platform abstraction strategy.

• [ ] Create ARCHITECTURE.md documenting high-level design and platform-specific modules
• [ ] Explain the role of signal-hook (Unix signal handling), blondie (Windows execution), and quick-xml (macOS integration)
• [ ] Document how src/lib.rs coordinates between src/bin/cargo-flamegraph.rs and src/bin/flamegraph.rs
• [ ] Add diagrams or flowcharts showing the profiling workflow on each platform
• [ ] Link to ARCHITECTURE.md from README.md in the development section

• Add integration tests in a tests/ directory for each platform backend (Linux/perf, macOS/xctrace, Windows/blondie). Currently no visible test files; test coverage for flamegraph generation and symbol demangling would improve reliability.
• Document the exact error messages and troubleshooting steps for the --no-rosegment linker flag in a dedicated TROUBLESHOOTING.md. Users frequently hit this on Rust 1.90.0+ without clear guidance on why their flamegraphs are empty.
• Add shell completion generation tests and CI validation (using clap_complete which is already a dependency). Ensure cargo flamegraph --generate-completions bash works correctly and test the bash/zsh/fish completion output.

The flamegraph project has a reasonable security posture for a profiling tool. No critical vulnerabilities were identified. The main concerns are medium-severity issues related to automatic file opening (via the opener crate) and potential command injection vectors through argument parsing and shell execution. The codebase relies on well-maintained dependencies (clap, cargo_metadata, inferno) which is positive. No hardcoded secrets or obvious SQL/XSS injection risks were identified. The tool is designed to execute system commands by nature, which is expected functionality but should be clearly documented. Recommended actions: (1) Validate and sanitize file paths before opening, (2) Audit shell argument parsing for injection risks, (3) Consider making auto-opening optional, and (4) Document security implications for users running with elevated privileges.

• Medium · Use of opener crate for automatic file opening — Cargo.toml (opener dependency). The opener crate (v0.8.1) is used to automatically open flamegraph output files. This could potentially be exploited if an attacker can control the output file path or name, leading to execution of arbitrary applications or opening of unintended files. The crate spawns system-specific file openers without strict validation. Fix: Validate and sanitize all file paths before passing them to the opener crate. Consider making automatic file opening optional and requiring explicit user confirmation, or provide a flag to disable auto-opening functionality.
• Medium · Shell command execution via shlex — Cargo.toml (shlex dependency) and src/bin/cargo-flamegraph.rs. The shlex crate is used for shell argument parsing. Combined with the cargo-flamegraph binary that accepts arbitrary arguments, there's potential for command injection if user input is not properly validated before being passed to shell commands or subprocesses. Fix: Ensure all user-supplied arguments are properly validated and escaped before being used in shell commands. Prefer using direct subprocess APIs (std::process::Command) instead of shell invocation when possible. Audit argument parsing in cargo-flamegraph.rs.
• Low · Unrestricted subprocess execution — src/bin/cargo-flamegraph.rs and src/bin/flamegraph.rs. The tool executes arbitrary profiling commands (perf on Linux, etc.) based on user input. While this is by design for a profiling tool, it could allow local privilege escalation if combined with other vulnerabilities. Fix: Document the security implications of running with elevated privileges. Implement least-privilege execution where possible. Add warnings when running with sudo or elevated permissions.
• Low · Signal handling on Unix systems — Cargo.toml (signal-hook dependency for unix targets). The signal-hook crate (v0.4.1) is used for Unix signal handling. While this is a legitimate security practice, ensure signal handlers are kept minimal and don't introduce race conditions. Fix: Review signal handler implementations to ensure they follow best practices: avoid blocking operations, keep handlers minimal, and properly synchronize state. The current version appears reasonable but warrants periodic audits.

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.