sherlock

Every time an app is slow to start or heavy to run, someone builds a one-off harness for that one repo: launch it, poll some numbers, eyeball a chart, guess. Sherlock replaces the harness. An agent reads the project, works out what it is and how to run it, launches a release build with a ready signal, samples the whole process tree every 100 ms, captures where the startup time went, and keeps watching while you click through the app. Mark an interaction and repeat it, and Sherlock tells you how much memory each one keeps.

The measuring is a small, dependency-free Node engine built on the tools your OS already ships (ps, footprint, sample, nettop, /proc, perf, simctl, adb, the Chrome DevTools Protocol). The judgment is Claude: which scenario to run, which numbers matter, which line of your code caused them.

Quick start

In Claude Code:

/plugin marketplace add hiftikha/sherlock
/plugin install sherlock@sherlock

Then, in any project:

/sherlock:profile why is the cold start of the release build slow?

Or without Claude Code installed first, from any project folder:

npx sherlock-profiler            # from npm
npx github:hiftikha/sherlock     # or straight from this repository

The wizard detects the project, then offers to open Claude Code with Sherlock loaded, run the agent in the terminal with your API key, profile it directly without an agent, or install the plugin for every project.

Related MCP server: flameox

Gallery

The dashboard is one local page that updates as the app runs. Numbers animate with NumberFlow, the right rail collapses (]), m marks an interaction, and every run is saved as a JSON report plus a standalone HTML page you can send to someone.

What it measures

A metric Sherlock can't measure on a target is shown as unavailable with the reason, never as a flat line or a guess.

It works on anything that runs as a process: Rust, Go, Swift, C and C++ binaries, Tauri and Electron apps (the webview and helper processes are in the tree), Node, Python, dev servers, and Rust compiled to WebAssembly in the browser.

Install

Pick one way in:

claude plugin marketplace add hiftikha/sherlock
claude plugin install sherlock@sherlock

or let the CLI do both: npx sherlock-profiler install.

Usage

In Claude Code

/sherlock:profile
/sherlock:profile the dev server takes 8 seconds to come up
/sherlock:profile memory after opening five documents
/sherlock:profile compare cold start before and after my change

You don't have to name the skill. Claude also uses Sherlock when you ask why an app is slow to start, uses too much memory, or leaks after an interaction. A drill pass goes: detect the project, profile a release build with a ready signal, open the dashboard, read the startup phases and hot functions and find them in your code, drive two or three interactions three times each, write the findings into the dashboard, and save the report under .sherlock/.

As an agent in your terminal

export ANTHROPIC_API_KEY=...
npx sherlock-profiler agent "why does the app take 2 seconds to show a window?"

The agent runs on claude-opus-5-5 with the same playbook and tools as the plugin, plus read_file, search_code and run_command. It asks before running any command or launching anything. --yes skips the questions.

Without an agent

sherlock launch --ready-log 'listening on' -- ./target/release/server
sherlock launch --ready-port 3000 -- npm run dev
sherlock attach my-app                       # by name or pid
sherlock web http://localhost:3000/ --throttle 4
sherlock ios com.example.app                 # the booted Simulator
sherlock android com.example.app             # a device or emulator
sherlock detect                              # what is this project?
sherlock report .sherlock/sherlock-1a2b3c4d.json

While a launch or attach is live, type a label and press enter to mark an interaction, or press enter alone to stop and save the report. --json prints a machine-readable digest, --exit stops after startup, --no-ui skips the dashboard.

How it works

• src/platform/host.mjs samples a process tree. On macOS: ps for CPU time, footprint for memory, ps -M for threads, nettop for network, ioreg for the GPU. On Linux: /proc/<pid>/{stat,status,io,net/dev} and, when perf is allowed, LLC miss counters for memory bandwidth. CPU is computed from cumulative CPU time between samples, so it's exact for short spikes rather than a decayed average.

• src/launch.mjs launches the app and times its phases: spawn, first output, a ready signal (a log line, a port, a URL) and the CPU going quiet. On macOS a separate warm-up launch captures call stacks from the first instruction with sample -wait, because attaching a sampler freezes the process for a few hundred milliseconds and would distort the timed run.

• src/platform/web.mjs drives headless Chrome over the DevTools Protocol with no Puppeteer: navigation timing, paint and LCP observers, a timeline trace for long tasks, runtime metrics, and the browser's own process tree.

• src/platform/mobile.mjs cold-launches iOS apps with simctl and samples the Simulator process on the Mac, and Android apps with am start -W and /proc over adb.

• src/findings.mjs turns samples into findings: wait-bound vs CPU-bound startup, the hot function, main-thread-bound work, memory each repeated interaction keeps, steady growth, and idle CPU.

• src/mcp.mjs and src/tools.mjs expose all of it as 13 MCP tools. The plugin's .mcp.json runs it with node, no install step.

• skills/profile/SKILL.md is the playbook Claude follows for a drill pass. The terminal agent (src/agent.mjs) uses the same file as its system prompt.

• ui/ is the dashboard: plain HTML, CSS and JavaScript fed by server-sent events from a server bound to 127.0.0.1.

sherlock/
├── .claude-plugin/        plugin.json and marketplace.json
├── .mcp.json              the MCP server the plugin starts
├── skills/profile/        the drill-pass playbook (/sherlock:profile)
├── cli/sherlock.mjs       the CLI and npx wizard
├── src/
│   ├── platform/          host (macOS, Linux), web, mobile samplers
│   ├── parse/             pure parsers for every tool's output
│   ├── launch.mjs         launch, attach, startup phases, stacks
│   ├── findings.mjs       rules that turn samples into findings
│   ├── tools.mjs          the tool layer shared by MCP and the agent
│   ├── mcp.mjs            stdio MCP server
│   ├── agent.mjs          terminal agent on the Claude API
│   └── server.mjs         dashboard server and HTML reports
├── ui/                    the dashboard
├── test/                  unit tests per platform, integration tests, fixtures
└── docs/                  the website

Privacy and what it runs

Sherlock runs only on your machine. It starts the commands you or the agent choose (the terminal agent asks first), reads process information with the system tools listed above, and serves the dashboard on 127.0.0.1. The dashboard page loads its fonts from Google Fonts and NumberFlow from jsDelivr; without network it falls back to system fonts and plain numbers. The terminal agent sends your goal, tool results and the files it reads to the Claude API using your key. The plugin itself makes no network calls; Claude Code's own model calls are covered by your Claude Code settings. Reports are written to .sherlock/ in the project.

Limits

• Memory bandwidth on macOS isn't measured. Apple exposes it only through sudo powermetrics, and Sherlock never runs sudo. On Linux it's an estimate from last-level cache misses and needs perf with perf_event_paranoid ≤ 1.

• macOS GPU is the whole GPU, not your process. It's still useful for seeing a render spike line up with an interaction.

• Startup on macOS is a warm start when call stacks are on, because the warm-up launch runs first. Pass --no-stacks for a launch with nothing before it. Neither is a true cold start after a reboot.

• iOS Simulator timings run on your Mac's CPU. Use them to compare builds, not as device numbers.

• Linux call stacks and Android memory bandwidth aren't wired up yet.

• Interactions are marked, not captured. Sherlock doesn't hook your app's input events; you, the agent or a script mark them. End-to-end interaction latency (input → frame) is the next milestone.

Requirements

Development

git clone https://github.com/hiftikha/sherlock.git && cd sherlock
npm install
npm test

The test suite has unit tests for every platform's parsers and integration tests that profile real processes: a Node app, a Rust app built with cargo, a page in headless Chrome, the iOS Simulator and Android through recorded simctl and adb stand-ins (and real ones when a Simulator is booted or a device is connected), the MCP server, the dashboard and the CLI. CI runs it on macOS and Linux. See CONTRIBUTING.md.

License

MIT © 2026 Haroon Iftikhar