Provides coding agents with bounded local runtime evidence by coordinating profilers, benchmark tools, and trace processors.
Also known as morluto/flameox
- Stars
- 243
- Tools
- 51
- Downloads, 30 days
- 608
- Latest version
- 0.2.9
- Last commit
- Nov 9, 2026
- License
- MIT
What is Flameox MCP?
Flameox provides coding agents with bounded local runtime evidence by coordinating profilers, benchmark tools, and trace processors. It exposes 51 tools, such as summarize_trace, inspect_trace_call_graph, summarize_pytorch_trace.
Summary generated from the project's README
About Flameox MCP server
Flameox provides coding agents with bounded local runtime evidence by coordinating profilers, benchmark tools, and trace processors. It functions as an MCP server that turns explicit commands or artifacts into recorded observations, including execution provenance, coverage, and typed evidence. Unlike many tools, it requires no workspace initialization or project configuration, instead relying on exact artifact paths and absolute working directories provided by the user.
Developers can set up the server using the npx flameox@latest setup command, which detects supported clients and updates their configurations. The system distinguishes between observed, derived, and inferred claims to ensure data integrity. While session data is stored in scratch space, users can opt for durable preservation by storing native bytes and evidence bundles in a specific data directory. This setup is designed for local execution where the agent chooses specific hypotheses and experiments to run against direct targets.
What you can do with it
- 1Capture execution benchmarksAn AI agent can run a specific Python benchmark script within a defined working directory to collect performance data.
- 2Analyze existing artifactsA developer can instruct an agent to examine a specific JSON artifact to extract runtime evidence.
- 3Inspect preserved evidence metadataAn agent can retrieve redacted metadata and replay sources for previously saved evidence using a unique ID.
- 4Verify MCP tool schemasDevelopers can audit the available tool catalog and specific operation schemas to understand how to interact with the server.
Written from the project's README. Every use case is checked against a quote from it.
How to install Flameox MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Flameox MCP in Claude Code
$ claude mcp add flameox -- uvx flameox mcp serveInstall Flameox MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"flameox": {
"command": "uvx",
"args": [
"flameox",
"mcp",
"serve"
]
}
}
}Install Flameox MCP in VS Code
.vscode/mcp.json
{
"servers": {
"flameox": {
"type": "stdio",
"command": "uvx",
"args": [
"flameox",
"mcp",
"serve"
]
}
}
}Install Flameox MCP in VS Code CLI
$ code --add-mcp '{"name":"flameox","type":"stdio","command":"uvx","args":["flameox","mcp","serve"]}'Install Flameox MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"flameox": {
"command": "uvx",
"args": [
"flameox",
"mcp",
"serve"
]
}
}
}Install Flameox MCP in Codex
$ codex mcp add flameox -- uvx flameox mcp serveInstall Flameox MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.flameox] command = "uvx" args = ["flameox", "mcp", "serve"]
Install Flameox MCP in Gemini CLI
$ gemini mcp add -s user flameox uvx -- flameox mcp serveInstall Flameox MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"flameox": {
"command": "uvx",
"args": [
"flameox",
"mcp",
"serve"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for flameox 0.2.9 in an isolated container with no network and no keys. It answered and listed 51 tools.
Flameox MCP tools 51
Read from the server with tools/listsummarize_traceRead-onlySummarize bounded execution-trace evidence. Read existing perfetto, chrome-trace, otlp, nsys-rep, nsys-parquet, pytorch, rocprof-pftrace, xctrace artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable.
inspect_trace_call_graphRead-onlyProject bounded caller-callee edges from Chrome, Perfetto, or PyTorch traces. Read existing perfetto, chrome-trace, pytorch artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable.
summarize_pytorch_traceRead-onlySummarize bounded PyTorch operator and event evidence. Read existing perfetto, chrome-trace, pytorch artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable.
summarize_trace_operationsRead-onlySummarize bounded operation timing from OTLP or Nsight Systems traces. Read existing otlp, nsys-rep, nsys-parquet artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable.
summarize_trace_lifecycleRead-onlySummarize bounded execution lifecycle events from OTLP or Nsight Systems traces. Read existing otlp, nsys-rep, nsys-parquet artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable.
inspect_trace_windowRead-onlyRead a bounded trace time window. Read existing perfetto, chrome-trace, pytorch, otlp artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable.
rank_cpu_hotspotsRead-onlyRank bounded CPU evidence. Read existing cpuprofile, pstats, py-spy, perf, perf-data artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable.
inspect_cpu_callersRead-onlyProject bounded caller-callee edges from pstats or sampled py-spy stacks. Sample weights are not deterministic invocation counts. Read existing pstats, py-spy artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable.
rank_allocation_hotspotsRead-onlyRank bounded allocation hotspots from Memray or V8 sampling heap profiles. Read existing memray, heapprofile artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable.
rank_retained_memoryRead-onlyRank bounded retained-memory evidence from a Memray capture. Read existing memray artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable.
summarize_benchmarksRead-onlySummarize bounded benchmark latency measurements. Read existing pyperf, samples, nvbench artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable.
analyze_benchmark_scalingRead-onlyEstimate how benchmark measurements scale across a declared numeric input axis. Read existing pyperf, samples, nvbench artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable.
| summarize_trace | Summarize bounded execution-trace evidence. Read existing perfetto, chrome-trace, otlp, nsys-rep, nsys-parquet, pytorch, rocprof-pftrace, xctrace artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable. | Read-only |
| inspect_trace_call_graph | Project bounded caller-callee edges from Chrome, Perfetto, or PyTorch traces. Read existing perfetto, chrome-trace, pytorch artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable. | Read-only |
| summarize_pytorch_trace | Summarize bounded PyTorch operator and event evidence. Read existing perfetto, chrome-trace, pytorch artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable. | Read-only |
| summarize_trace_operations | Summarize bounded operation timing from OTLP or Nsight Systems traces. Read existing otlp, nsys-rep, nsys-parquet artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable. | Read-only |
| summarize_trace_lifecycle | Summarize bounded execution lifecycle events from OTLP or Nsight Systems traces. Read existing otlp, nsys-rep, nsys-parquet artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable. | Read-only |
| inspect_trace_window | Read a bounded trace time window. Read existing perfetto, chrome-trace, pytorch, otlp artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable. | Read-only |
| rank_cpu_hotspots | Rank bounded CPU evidence. Read existing cpuprofile, pstats, py-spy, perf, perf-data artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable. | Read-only |
| inspect_cpu_callers | Project bounded caller-callee edges from pstats or sampled py-spy stacks. Sample weights are not deterministic invocation counts. Read existing pstats, py-spy artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable. | Read-only |
| rank_allocation_hotspots | Rank bounded allocation hotspots from Memray or V8 sampling heap profiles. Read existing memray, heapprofile artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable. | Read-only |
| rank_retained_memory | Rank bounded retained-memory evidence from a Memray capture. Read existing memray artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable. | Read-only |
| summarize_benchmarks | Summarize bounded benchmark latency measurements. Read existing pyperf, samples, nvbench artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable. | Read-only |
| analyze_benchmark_scaling | Estimate how benchmark measurements scale across a declared numeric input axis. Read existing pyperf, samples, nvbench artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable. | Read-only |
Show all 51 toolsShow fewer tools
compare_benchmarksRead-onlyCompare compatible benchmark artifacts. Read existing pyperf, samples, nvbench artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable.
summarize_inferenceRead-onlySummarize bounded inference-export measurements. Read existing aiperf, vllm-benchmark, sglang-benchmark, mooncake-trace artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable.
compare_inferenceRead-onlyCompare compatible prompt-free inference measurements. Read existing aiperf, vllm-benchmark, sglang-benchmark, mooncake-trace artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable.
inspect_gpu_launchesRead-onlySummarize GPU launch evidence. Read existing nsys-rep, nsys-parquet artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable.
inspect_gpu_kernel_metricsRead-onlySummarize GPU kernel metrics. Read existing nsight-compute artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable.
inspect_triton_autotuneRead-onlySummarize Triton autotune events or native configuration-timing caches. Read existing triton, triton-cache artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable.
inspect_sanitizer_failuresRead-onlySummarize Compute Sanitizer failures. Read existing compute-sanitizer artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable.
inspect_kernel_validationRead-onlySummarize semantic kernel validation results. Read existing kernel-validation artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable.
compare_kernel_validationRead-onlyCompare compatible kernel evidence. Read existing kernel-validation artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable.
summarize_failuresRead-onlySummarize bounded reliability evidence. Read existing pytest, observations artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable.
inspect_pytest_fixturesRead-onlyRank bounded pytest fixture setup and finalizer evidence. Read existing pytest artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable.
summarize_coverageRead-onlySummarize native coverage.py evidence. Read existing coverage artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable.
inspect_performance_candidatesRead-onlyNormalize performance candidates from an existing SARIF report. Read existing sarif artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable.
preview_artifactRead-onlyPreview a bounded artifact without mutation. Read existing json, jsonl, csv, text, parquet artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable.
capture_and_summarize_traceActionExecute an explicit argv target and collect native artifacts to: Summarize bounded execution-trace evidence. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use summarize_trace. Pagination reads captured artifacts without executing again.
capture_and_inspect_trace_call_graphActionExecute an explicit argv target and collect native artifacts to: Project bounded caller-callee edges from Chrome, Perfetto, or PyTorch traces. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use inspect_trace_call_graph. Pagination reads captured artifacts without executing again.
capture_and_summarize_pytorch_traceActionExecute an explicit argv target and collect native artifacts to: Summarize bounded PyTorch operator and event evidence. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use summarize_pytorch_trace. Pagination reads captured artifacts without executing again.
capture_and_summarize_trace_operationsActionExecute an explicit argv target and collect native artifacts to: Summarize bounded operation timing from OTLP or Nsight Systems traces. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use summarize_trace_operations. Pagination reads captured artifacts without executing again.
capture_and_summarize_trace_lifecycleActionExecute an explicit argv target and collect native artifacts to: Summarize bounded execution lifecycle events from OTLP or Nsight Systems traces. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use summarize_trace_lifecycle. Pagination reads captured artifacts without executing again.
capture_and_inspect_trace_windowActionExecute an explicit argv target and collect native artifacts to: Read a bounded trace time window. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use inspect_trace_window. Pagination reads captured artifacts without executing again.
capture_and_rank_cpu_hotspotsActionExecute an explicit argv target and collect native artifacts to: Rank bounded CPU evidence. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use rank_cpu_hotspots. Pagination reads captured artifacts without executing again.
capture_and_inspect_cpu_callersActionExecute an explicit argv target and collect native artifacts to: Project bounded caller-callee edges from pstats or sampled py-spy stacks. Sample weights are not deterministic invocation counts. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use inspect_cpu_callers. Pagination reads captured artifacts without executing again.
capture_and_rank_allocation_hotspotsActionExecute an explicit argv target and collect native artifacts to: Rank bounded allocation hotspots from Memray or V8 sampling heap profiles. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use rank_allocation_hotspots. Pagination reads captured artifacts without executing again.
capture_and_rank_retained_memoryActionExecute an explicit argv target and collect native artifacts to: Rank bounded retained-memory evidence from a Memray capture. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use rank_retained_memory. Pagination reads captured artifacts without executing again.
capture_and_summarize_benchmarksActionExecute an explicit argv target and collect native artifacts to: Summarize bounded benchmark latency measurements. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use summarize_benchmarks. Pagination reads captured artifacts without executing again.
capture_and_analyze_benchmark_scalingActionExecute an explicit argv target and collect native artifacts to: Estimate how benchmark measurements scale across a declared numeric input axis. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use analyze_benchmark_scaling. Pagination reads captured artifacts without executing again.
capture_and_inspect_gpu_launchesActionExecute an explicit argv target and collect native artifacts to: Summarize GPU launch evidence. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use inspect_gpu_launches. Pagination reads captured artifacts without executing again.
capture_and_inspect_gpu_kernel_metricsActionExecute an explicit argv target and collect native artifacts to: Summarize GPU kernel metrics. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use inspect_gpu_kernel_metrics. Pagination reads captured artifacts without executing again.
capture_and_inspect_triton_autotuneActionExecute an explicit argv target and collect native artifacts to: Summarize Triton autotune events or native configuration-timing caches. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use inspect_triton_autotune. Pagination reads captured artifacts without executing again.
capture_and_inspect_sanitizer_failuresActionExecute an explicit argv target and collect native artifacts to: Summarize Compute Sanitizer failures. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use inspect_sanitizer_failures. Pagination reads captured artifacts without executing again.
capture_and_summarize_failuresActionExecute an explicit argv target and collect native artifacts to: Summarize bounded reliability evidence. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use summarize_failures. Pagination reads captured artifacts without executing again.
capture_and_inspect_pytest_fixturesActionExecute an explicit argv target and collect native artifacts to: Rank bounded pytest fixture setup and finalizer evidence. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use inspect_pytest_fixtures. Pagination reads captured artifacts without executing again.
capture_and_summarize_coverageActionExecute an explicit argv target and collect native artifacts to: Summarize native coverage.py evidence. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use summarize_coverage. Pagination reads captured artifacts without executing again.
capture_and_preview_artifactActionExecute an explicit argv target and collect native artifacts to: Preview a bounded artifact without mutation. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use preview_artifact. Pagination reads captured artifacts without executing again.
prepare_providersActionUse when a provider result requests dependency preparation. Install the requested managed dependencies, then follow activation or reconnect guidance before retrying. Host profilers and workload-interpreter requirements receive guidance rather than installation.
preserve_evidenceActionKeep a live analysis beyond eviction or shutdown. Publish its native artifacts and provenance as immutable evidence, returning an evidence ID and refreshed next_page when available.
rescue_evidenceActionUse when the active evidence store needs recovery or a live analysis needs a distinct store. Publish into an explicit new evidence directory and return its restart handoff; the active store stays selected. Already-preserved captures use their immutable sources.
query_evidenceRead-onlyFind preserved evidence after a session ends. Search immutable manifest metadata with typed filters and rows, then call inspect_evidence for replay sources. Reports inventory coverage and a next_page when more matches exist.
inspect_evidenceRead-onlyRead one preserved evidence ID. Returns validated, redacted manifest metadata and ordered analysis_sources inline. Pass those sources unchanged to a named analysis tool to replay the saved artifacts without recapturing. Native payload bytes stay local.
| compare_benchmarks | Compare compatible benchmark artifacts. Read existing pyperf, samples, nvbench artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable. | Read-only |
| summarize_inference | Summarize bounded inference-export measurements. Read existing aiperf, vllm-benchmark, sglang-benchmark, mooncake-trace artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable. | Read-only |
| compare_inference | Compare compatible prompt-free inference measurements. Read existing aiperf, vllm-benchmark, sglang-benchmark, mooncake-trace artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable. | Read-only |
| inspect_gpu_launches | Summarize GPU launch evidence. Read existing nsys-rep, nsys-parquet artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable. | Read-only |
| inspect_gpu_kernel_metrics | Summarize GPU kernel metrics. Read existing nsight-compute artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable. | Read-only |
| inspect_triton_autotune | Summarize Triton autotune events or native configuration-timing caches. Read existing triton, triton-cache artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable. | Read-only |
| inspect_sanitizer_failures | Summarize Compute Sanitizer failures. Read existing compute-sanitizer artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable. | Read-only |
| inspect_kernel_validation | Summarize semantic kernel validation results. Read existing kernel-validation artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable. | Read-only |
| compare_kernel_validation | Compare compatible kernel evidence. Read existing kernel-validation artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable. | Read-only |
| summarize_failures | Summarize bounded reliability evidence. Read existing pytest, observations artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable. | Read-only |
| inspect_pytest_fixtures | Rank bounded pytest fixture setup and finalizer evidence. Read existing pytest artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable. | Read-only |
| summarize_coverage | Summarize native coverage.py evidence. Read existing coverage artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable. | Read-only |
| inspect_performance_candidates | Normalize performance candidates from an existing SARIF report. Read existing sarif artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable. | Read-only |
| preview_artifact | Preview a bounded artifact without mutation. Read existing json, jsonl, csv, text, parquet artifacts; returns input identities, metrics/rows, coverage and limitations. Follow next_page for more evidence; preserve_evidence makes it durable. | Read-only |
| capture_and_summarize_trace | Execute an explicit argv target and collect native artifacts to: Summarize bounded execution-trace evidence. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use summarize_trace. Pagination reads captured artifacts without executing again. | Action |
| capture_and_inspect_trace_call_graph | Execute an explicit argv target and collect native artifacts to: Project bounded caller-callee edges from Chrome, Perfetto, or PyTorch traces. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use inspect_trace_call_graph. Pagination reads captured artifacts without executing again. | Action |
| capture_and_summarize_pytorch_trace | Execute an explicit argv target and collect native artifacts to: Summarize bounded PyTorch operator and event evidence. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use summarize_pytorch_trace. Pagination reads captured artifacts without executing again. | Action |
| capture_and_summarize_trace_operations | Execute an explicit argv target and collect native artifacts to: Summarize bounded operation timing from OTLP or Nsight Systems traces. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use summarize_trace_operations. Pagination reads captured artifacts without executing again. | Action |
| capture_and_summarize_trace_lifecycle | Execute an explicit argv target and collect native artifacts to: Summarize bounded execution lifecycle events from OTLP or Nsight Systems traces. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use summarize_trace_lifecycle. Pagination reads captured artifacts without executing again. | Action |
| capture_and_inspect_trace_window | Execute an explicit argv target and collect native artifacts to: Read a bounded trace time window. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use inspect_trace_window. Pagination reads captured artifacts without executing again. | Action |
| capture_and_rank_cpu_hotspots | Execute an explicit argv target and collect native artifacts to: Rank bounded CPU evidence. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use rank_cpu_hotspots. Pagination reads captured artifacts without executing again. | Action |
| capture_and_inspect_cpu_callers | Execute an explicit argv target and collect native artifacts to: Project bounded caller-callee edges from pstats or sampled py-spy stacks. Sample weights are not deterministic invocation counts. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use inspect_cpu_callers. Pagination reads captured artifacts without executing again. | Action |
| capture_and_rank_allocation_hotspots | Execute an explicit argv target and collect native artifacts to: Rank bounded allocation hotspots from Memray or V8 sampling heap profiles. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use rank_allocation_hotspots. Pagination reads captured artifacts without executing again. | Action |
| capture_and_rank_retained_memory | Execute an explicit argv target and collect native artifacts to: Rank bounded retained-memory evidence from a Memray capture. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use rank_retained_memory. Pagination reads captured artifacts without executing again. | Action |
| capture_and_summarize_benchmarks | Execute an explicit argv target and collect native artifacts to: Summarize bounded benchmark latency measurements. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use summarize_benchmarks. Pagination reads captured artifacts without executing again. | Action |
| capture_and_analyze_benchmark_scaling | Execute an explicit argv target and collect native artifacts to: Estimate how benchmark measurements scale across a declared numeric input axis. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use analyze_benchmark_scaling. Pagination reads captured artifacts without executing again. | Action |
| capture_and_inspect_gpu_launches | Execute an explicit argv target and collect native artifacts to: Summarize GPU launch evidence. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use inspect_gpu_launches. Pagination reads captured artifacts without executing again. | Action |
| capture_and_inspect_gpu_kernel_metrics | Execute an explicit argv target and collect native artifacts to: Summarize GPU kernel metrics. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use inspect_gpu_kernel_metrics. Pagination reads captured artifacts without executing again. | Action |
| capture_and_inspect_triton_autotune | Execute an explicit argv target and collect native artifacts to: Summarize Triton autotune events or native configuration-timing caches. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use inspect_triton_autotune. Pagination reads captured artifacts without executing again. | Action |
| capture_and_inspect_sanitizer_failures | Execute an explicit argv target and collect native artifacts to: Summarize Compute Sanitizer failures. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use inspect_sanitizer_failures. Pagination reads captured artifacts without executing again. | Action |
| capture_and_summarize_failures | Execute an explicit argv target and collect native artifacts to: Summarize bounded reliability evidence. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use summarize_failures. Pagination reads captured artifacts without executing again. | Action |
| capture_and_inspect_pytest_fixtures | Execute an explicit argv target and collect native artifacts to: Rank bounded pytest fixture setup and finalizer evidence. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use inspect_pytest_fixtures. Pagination reads captured artifacts without executing again. | Action |
| capture_and_summarize_coverage | Execute an explicit argv target and collect native artifacts to: Summarize native coverage.py evidence. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use summarize_coverage. Pagination reads captured artifacts without executing again. | Action |
| capture_and_preview_artifact | Execute an explicit argv target and collect native artifacts to: Preview a bounded artifact without mutation. Returns immediate evidence and execution provenance, including failed attempts. For existing artifacts use preview_artifact. Pagination reads captured artifacts without executing again. | Action |
| prepare_providers | Use when a provider result requests dependency preparation. Install the requested managed dependencies, then follow activation or reconnect guidance before retrying. Host profilers and workload-interpreter requirements receive guidance rather than installation. | Action |
| preserve_evidence | Keep a live analysis beyond eviction or shutdown. Publish its native artifacts and provenance as immutable evidence, returning an evidence ID and refreshed next_page when available. | Action |
| rescue_evidence | Use when the active evidence store needs recovery or a live analysis needs a distinct store. Publish into an explicit new evidence directory and return its restart handoff; the active store stays selected. Already-preserved captures use their immutable sources. | Action |
| query_evidence | Find preserved evidence after a session ends. Search immutable manifest metadata with typed filters and rows, then call inspect_evidence for replay sources. Reports inventory coverage and a next_page when more matches exist. | Read-only |
| inspect_evidence | Read one preserved evidence ID. Returns validated, redacted manifest metadata and ordered analysis_sources inline. Pass those sources unchanged to a named analysis tool to replay the saved artifacts without recapturing. Native payload bytes stay local. | Read-only |
Automated checks
Ran Nov 16, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablemorluto/flameox is public and reachablegithub.com/morluto/flameox ↗Pass
- Package names this repository as its sourceflameox names morluto/flameox as sourcepypi.org/project/flameox/ ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for flameoxpypi.org/project/flameox/ ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-09github.com/morluto/flameox ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from flameoxPass
- No critical advisory in the package or its dependencies51 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model51 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubFlameox coordinates profilers, benchmark tools, trace processors, and direct local targets. It turns an explicit artifact or command into bounded evidence while keeping durable preservation optional. The agent chooses hypotheses and experiments; Flameox records observed inputs, execution provenance, typed evidence, coverage, and limitations.
There is no workspace to initialize or project configuration to maintain. Pass exact artifact paths to analysis and an explicit argv plus absolute working directory to capture. Flameox does not search parent directories, edit project files, or provide a hosted service.
Quick start
Configure an MCP client with the global setup command:
npx flameox@latest setup
Setup detects supported clients and asks which configurations to update. For automation, select
clients explicitly, for example --client codex --yes or --all --yes; --dry-run reports the
paths and actions without writing. Setup preserves unrelated client configuration and does not
change project files. See the npm package guide for details.
Update existing MCP registrations with:
npx flameox@latest update
update --check reports available updates without changing configuration. Updates preserve each
client's provider extras and settings, verify the new environment before changing release pins,
and report which clients need a restart or reconnect. Use --client codex to select one client,
or --version 0.2.8 to select a specific release, including for rollback. The Python CLI exposes
the same flameox update command.
For direct CLI use, pass exact artifact paths or an explicit command:
uvx flameox analyze preview_artifact /absolute/path/to/artifact.json
uvx flameox capture --provider direct --cwd "$PWD" -- python benchmark.py
To launch the stdio MCP server manually:
uvx flameox mcp serve
For local development, clone the repository, install its development dependencies, and inspect the available tools:
git clone https://github.com/morluto/flameox.git
cd flameox
uv sync --extra dev --extra memory --extra trace --extra cpu
uv run flameox mcp inspect
Evidence and storage
Analysis and unpreserved capture use bounded session scratch. Session analysis_id values expire
when evicted or when the server stops. Explicit preservation creates the user-level Flameox data
directory and stores native bytes and a canonical evidence bundle by SHA-256. Set
FLAMEOX_DATA_DIR to choose another location. Preservation is optional; it does not imply full
console-output retention.
Flameox distinguishes observed, derived, and inferred claims. Profiles guide exploration but do not establish causality or performance improvement. Confirmatory claims require representative workloads, declared metrics and estimands, compatible identities, preserved samples, and a semantic oracle.
MCP
The MCP server has no workspace binding. It exposes named analysis and capture tools through the
same operation registry as the CLI. Analysis tools accept explicit sources; capture tools accept
a typed target and provider. Tool schemas expose operation-specific fields directly. Inspect the
catalog with flameox mcp inspect; use --tool TOOL_NAME for
focused schemas and examples. The complete contract and current tool catalog are in
the interface guide.
Tools return their full bounded results inline, including failures and recovery actions. Preserved
evidence has a durable evidence_id; inspect_evidence returns its redacted metadata and replay
sources inline.
Capture takes argv, not a shell string. A direct target supplies an absolute working directory and
bounded environment overrides. Results may include next_page; replay its named analysis tool
and arguments unchanged. Capture continuations read collected artifacts and do not rerun the
target. MCP work belongs to the live request, so cancellation applies directly and no detached job
survives a restart.
Documentation
- Architecture describes process and package boundaries.
- Storage and evidence defines preservation and provenance.
- Investigations covers experiments, comparison, and evidence quality.
- Adapters documents provider compatibility and integration policy.
- Runtime safety covers limits, recovery, integrity, and privacy.
- Interfaces defines CLI and MCP contracts.
- Testing describes test selections and known proof gaps.
Development
Flameox requires Python 3.12 or newer and uses the committed uv.lock. See
CONTRIBUTING.md for development setup and contribution guidance.
uv run ruff check src tests tools
uv run ruff format --check src tests tools
uv run mypy src tests tools
uv run pytest -q
Flameox is licensed under the MIT License.
Flameox MCP questions
How do I add Flameox MCP to Claude Code?
Run claude mcp add flameox -- uvx flameox mcp serve in your terminal. Add --scope user to make it available in every project.
How do I add Flameox MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Flameox MCP provide?
It exposes 51 tools, including summarize_trace, inspect_trace_call_graph, summarize_pytorch_trace, summarize_trace_operations, summarize_trace_lifecycle.
Does Flameox require a project workspace to be initialized?
No, Flameox does not require a workspace to be initialized or project configuration to be maintained; you simply pass exact artifact paths or explicit commands.
Can I choose where Flameox stores its data?
Yes, you can set the FLAMEOX_DATA_DIR environment variable to choose a different location for the user-level Flameox data directory.