hotpath CLI
hotpath — a Rust profiler for time, memory, CPU, channels, SQL and HTTP, set up by an agent with hotpath init, plus an MCP server for questions
- 1,911 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- `hotpath init` downloads the skill's instructions from GitHub on every run and hands them to an agent that then edits `Cargo.toml` and source code
- A build with `hotpath-mcp` opens an HTTP server with the running program's metrics on a local port, with no token set by default
- In the CI setup reports are uploaded to hotpath Cloud, and the service's GitHub App gets the right to write comments on pull requests
Install
- Works in
Manual install
cargo install hotpath --version '^0.28'Installs the hotpath command. The project dependency is the line hotpath = "0.28" in Cargo.toml.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- `hotpath init` downloads the skill's instructions from GitHub on every run and hands them to an agent that then edits `Cargo.toml` and source code
- A build with `hotpath-mcp` opens an HTTP server with the running program's metrics on a local port, with no token set by default
- In the CI setup reports are uploaded to hotpath Cloud, and the service's GitHub App gets the right to write comments on pull requests
This is third-party code. Review the repository files before installing.
What it does
hotpath is a Rust profiler that installs as the `hotpath` Cargo package and a command of the same name via `cargo install hotpath`. You add the `#[hotpath::main]` and `#[hotpath::measure]` macros to the code. While the `hotpath` cargo feature is off, the macros do nothing and add no overhead. With the feature on, the program measures function time, memory allocations (`hotpath-alloc`), CPU load through samply (`hotpath-cpu`), channels, streams, futures, Mutex and RwLock waits, byte-level I/O, SQL queries (sqlx, Diesel, Toasty), reqwest and ureq HTTP clients, axum routes and Tokio workers. The result is a table at the end of a run or a live terminal dashboard, and metrics can go to Prometheus and Grafana. For agents there is the `hotpath init --agent claude` command (`codex` and `opencode` work too). It downloads the `hotpath_init` skill from GitHub and starts an agent session with the skill as instructions. The agent studies the project, adds a dependency with features to `Cargo.toml`, puts macros on `main` and the first functions, channels and locks, then checks that the build compiles with and without profiling. For the first setup the author advises no more than five `measure_all` and thirty `measure`. You approve each edit through the agent's usual permission prompts. Skills for CI setup, a Grafana dashboard and reading hotpath Cloud reports sit alongside. With the `hotpath-mcp` feature the running program brings up an MCP server on port 6771 (`HOTPATH_MCP_PORT` changes it, `HOTPATH_MCP_AUTH_TOKEN` sets a token). There are 30 tools: 19 return summaries such as `functions_timing`, `functions_alloc`, `channels`, `sql`, `http` and `threads`, and 11 return logs of individual events by id. The agent answers questions from live data: which functions take the most time and where allocation grows.
Who it is for. For Rust developers who hunt for bottlenecks in a program and want Claude Code, Codex or OpenCode to place the measurements and read the reports.
Good fit when
- A Rust service answers slowly and you need to tell whether functions wait on I/O or are CPU-bound
- Memory grows for an unknown reason: `hotpath-alloc` shows allocations by function and by thread
- You want to see queue depth and throughput of `mpsc` channels, Mutex and RwLock waits, and SQL and HTTP latency per axum route
- You want an agent to do the first profiling setup in a repository with `hotpath init`
- Performance regressions have to be caught in every pull request: the `hotpath_init_ci` skill and comparison with the main branch cover that
Not a fit when
- The project is not written in Rust: the package connects through Cargo and Rust macros
- You cannot change the source code: hotpath needs macros placed, while profiling without code edits is done by external samplers such as perf and samply
- You need libraries that are not listed: SQL works for sqlx, Diesel and Toasty, HTTP clients for reqwest and ureq, servers only for axum
- You need an MCP server that starts by itself without a build with the feature: the server runs inside your program and lives while it runs
Example request
Set up hotpath in this Rust project: place measurements on the request handlers and channels and show which functions take the longestLimitations
- MIT license. The author calls the project under active development: core public APIs are stable, but JSON report formats, TUI and MCP internals and advanced settings may change between releases.
- CPU profiling needs `samply` version 0.13 and the `hotpath-samply` wrapper on PATH, plus system permissions for sampling on macOS and Linux.
- A profiling build is switched on only by the `hotpath` feature. Wrappers for channels, streams and locks change the types in function signatures: outside profiling they do nothing, but the code has to be edited.
- The hotpath Cloud service belongs to the author. It is in open beta and free, and the author promises to keep public repositories free. Installing the GitHub App lets it write comments on pull requests, and the app asks for no access to code.
- The `hotpath_init` skill takes macro descriptions from hotpath.rs and does not change the project's `hotpath` version even if the documentation describes a newer release.
How to disable. Remove the `hotpath` feature from the build command, and the macros stop doing anything. To remove the profiler entirely, delete the `hotpath` dependency and the `[features]` entries from `Cargo.toml`, and the macros from the code. `cargo uninstall hotpath` removes the command. The MCP server runs while the program is started with the `hotpath-mcp` feature and shuts down with it.
FAQ
How do I set up hotpath through an agent with hotpath init?
Run `cargo install hotpath --version '^0.28'`, then `hotpath init --agent claude` in the project root. `--agent codex` and `--agent opencode` work too, and the chosen agent must be installed and on PATH. If you would rather not run it through the CLI, copy the `hotpath_init` skill to `~/.claude/skills/hotpath_init/SKILL.md` and call `/hotpath_init`.
How is hotpath different from sampling profilers such as perf and samply?
A sampler shows where the CPU spends time, but it is hard to tell I/O waiting from computation by it. hotpath macros measure function time and allocations at their boundaries. Comparing the reports explains the kind of bottleneck: high time with few CPU samples means waiting, many samples mean computing, many allocations mean memory pressure.
How do I connect the hotpath MCP server to Claude Code?
Start the program with `cargo run --features='hotpath,hotpath-alloc,hotpath-mcp'`. Then run `claude mcp add --transport http hotpath http://localhost:6771/mcp`. If you set `HOTPATH_MCP_AUTH_TOKEN`, add `--header "Authorization: your-token"`. `HOTPATH_MCP_PORT` changes the port.
What is hotpath's overhead and how does it depend on settings?
Without the `hotpath` feature the macros are empty, the dependencies are optional and not compiled, so there is no overhead. With profiling on, `#[hotpath::measure]` adds about 40 ns per call, a Mutex lock cycle 29–54 ns and a channel send and receive 47–88 ns. The author measured on an Apple M2 Pro and asks you to treat the numbers as orders of magnitude.
What does the hotpath_init_ci skill do, and does it need hotpath Cloud?
It adds the `hotpath-cloud` feature, a regression policy file and a GitHub Actions workflow that uploads reports so every pull request gets a comment with changes in time, allocations and RSS. For forks there is the `hotpath_init_ci_forks` skill. The comment is posted by the hotpath Cloud GitHub App, so this setup does need the cloud.
Can I get a Grafana dashboard for my project?
Yes, the `hotpath_init_grafana` skill writes a dashboard file with panels only for what you measure: SQL and HTTP time per route, N+1 detection, memory and time per request, channel queues, lock waits, Tokio workers. It does not configure the Prometheus export itself; the `hotpath-prometheus` feature does that.
Discussion
No questions or reviews yet.
Related
CLI toolsrust-analyzer MCP: Rust code navigation for agents
r3bl-rust-analyzer-mcp-server
A Rust MCP server on standard threads: the agent gets hover info, go to definition, references, formatting and compiler diagnostics from rust-analyzer
CodeGraph (Rust)
codegraph-rust
A Rust code graph for agents: four MCP tools show what an edit will touch, how the architecture fits together and where the fragile spots are
Resolves which files import each other and what an edit will touch, and serves it to agents through hooks, MCP and a CLI
A Rust SDK for coding agents and the ready-made abstract CLI: REPL, 34 tools, MCP, graph memory, Anthropic and OpenAI, JSON output for CI
An MCP server and CLI for code research: search and understand your project and all of GitHub with fewer tokens
Code graph and project memory in one Rust program: the agent gets excerpts with file and line citations
README in short
The repository holds six Cargo packages: the main `hotpath`, the macros, the drain mechanism and their `meta` versions for profiling the profiler itself. Three command-line programs sit alongside: `hotpath` with the dashboard and cloud commands, `hotpath-samply` and `hotpath-utils` for comparing reports. The `skills` folder holds six skills, and the `docs` folder documents modes, CPU, SQL, HTTP, MCP and CI. There is a test suite, Miri checks, CI runs on Linux, macOS and Windows and a changelog. The `AGENTS.md` file sets rules for agents working on the code.
README badge
Original SKILL.md
--- name: hotpath_init description: Configure hotpath profiling in a Rust project. Adds the hotpath dependency with feature-gated setup, instruments main with hotpath::main, functions with measure/measure_all, and wraps channels, mutexes, rw_locks, streams, futures, reqwest clients, axum routers and byte-level I/O with hotpath macros. Use when the user wants to add or set up hotpath profiling in a crate. --- # Initialize hotpath Profiling Set up hotpath profiling in the current Rust project. The setup is fully feature-gated: zero compile-time and runtime overhead unless the hotpath feature is explicitly enabled.