Skip to content
Back to search

flameox

Runtime evidence that helps agents trace, profile, and burn down hotspots in application and native code, GPU kernels, and inference stacks.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/morluto/flameox with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/morluto/flameox'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/morluto--flameox/badge.svg)](/listings/morluto--flameox)

HTML

<a href="/listings/morluto--flameox"><img src="/api/listings/morluto--flameox/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

uv sync --extra dev --extra memory --extra trace --extra cpu
uv run flameox mcp inspect
uv run flameox analyze artifact.preview /absolute/path/to/artifact.json
uv run flameox capture --provider direct --cwd "$PWD" -- python benchmark.py

The MCP server has no workspace or project binding:

uv run flameox mcp serve

Run the short global setup wizard through npm:

npx flameox@latest setup

Setup detects Claude Code, Cursor, OpenCode, Codex, Gemini CLI, and Google Antigravity, then asks which clients should use Flameox. It preserves unrelated client configuration and writes a Python 3.12 `uvx` launcher pinned to the exact Flameox release that ran setup. Restart or reconnect changed clients afterward. For automation, pass `--client codex --yes`, repeat `--client`, or use `--all --yes`; `--dry-run` reports the same global paths without writing them. Detection is never automation consent.

Explicit `--provider` selections prepare the exact version-pinned `uvx` environment in the saved launcher by resolving it once into uvx's cache; they do not create a persistent global `uv tool` installation. Each invocation declares the complete managed provider set for that launcher rather than adding to remembered state. Use `--timeout-seconds` for a slow cold resolution. System and vendor tools are diagnosed with external install guidance. Setup never initializes or mutates a project.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 126 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <h1 align="center">flameox</h1>
  2. <p align="center">
  3. <img
  4. src="docs/assets/flameox-mascot-flamegraph.png"
  5. width="420"
  6. alt="flameox mascot: an ox with a flame graph between its horns"
  7. >
  8. </p>
  9. <p align="center"><strong>Bounded local runtime evidence for coding agents.</strong></p>
  10. <!-- mcp-name: io.github.morluto/flameox -->
  11. Flameox coordinates profilers, benchmark tools, trace processors, and direct local targets. It
  12. turns an explicit artifact or command into bounded evidence while keeping durable preservation
  13. optional. The agent chooses hypotheses and experiments; Flameox records observed inputs,
  14. execution provenance, typed evidence, coverage, and limitations.
  15. There is no workspace to initialize or project configuration to maintain. Pass exact artifact
  16. paths to analysis and an explicit argv plus absolute working directory to capture. Flameox does not
  17. search parent directories, edit project files, or provide a hosted service.
  18. ## Quick start
  19. Configure an MCP client with the global setup command:
  20. ```console
  21. npx flameox@latest setup
  22. ```
  23. Setup detects supported clients and asks which configurations to update. For automation, select
  24. clients explicitly, for example `--client codex --yes` or `--all --yes`; `--dry-run` reports the
  25. paths and actions without writing. Setup preserves unrelated client configuration and does not
  26. change project files. See [the npm package guide](npm/README.md) for details.
  27. Update existing MCP registrations with:
  28. ```console
  29. npx flameox@latest update
  30. ```
  31. `update --check` reports available updates without changing configuration. Updates preserve each
  32. client's provider extras and settings, verify the new environment before changing release pins,
  33. and report which clients need a restart or reconnect. Use `--client codex` to select one client,
  34. or `--version 0.2.8` to select a specific release, including for rollback. The Python CLI exposes
  35. the same `flameox update` command.
  36. For direct CLI use, pass exact artifact paths or an explicit command:
  37. ```console
  38. uvx flameox analyze preview_artifact /absolute/path/to/artifact.json
  39. uvx flameox capture --provider direct --cwd "$PWD" -- python benchmark.py
  40. ```
  41. To launch the stdio MCP server manually:
  42. ```console
  43. uvx flameox mcp serve
  44. ```
  45. For local development, clone the repository, install its development dependencies, and inspect the
  46. available tools:
  47. ```console
  48. git clone https://github.com/morluto/flameox.git
  49. cd flameox
  50. uv sync --extra dev --extra memory --extra trace --extra cpu
  51. uv run flameox mcp inspect
  52. ```
  53. ## Evidence and storage
  54. Analysis and unpreserved capture use bounded session scratch. Session `analysis_id` values expire
  55. when evicted or when the server stops. Explicit preservation creates the user-level Flameox data
  56. directory and stores native bytes and a canonical evidence bundle by SHA-256. Set
  57. `FLAMEOX_DATA_DIR` to choose another location. Preservation is optional; it does not imply full
  58. console-output retention.
  59. Flameox distinguishes observed, derived, and inferred claims. Profiles guide exploration but do
  60. not establish causality or performance improvement. Confirmatory claims require representative
  61. workloads, declared metrics and estimands, compatible identities, preserved samples, and a
  62. semantic oracle.
  63. ## MCP
  64. The MCP server has no workspace binding. It exposes named analysis and capture tools through the
  65. same operation registry as the CLI. Analysis tools accept explicit sources; capture tools accept
  66. a typed target and provider. Tool schemas expose operation-specific fields directly. Inspect the
  67. catalog with `flameox mcp inspect`; use `--tool TOOL_NAME` for
  68. focused schemas and examples. The complete contract and current tool catalog are in
  69. [the interface guide](docs/interfaces.md).
  70. Tools return their full bounded results inline, including failures and recovery actions. Preserved
  71. evidence has a durable `evidence_id`; `inspect_evidence` returns its redacted metadata and replay
  72. sources inline.
  73. Capture takes argv, not a shell string. A direct target supplies an absolute working directory and
  74. bounded environment overrides. Results may include `next_page`; replay its named analysis tool
  75. and arguments unchanged. Capture continuations read collected artifacts and do not rerun the
  76. target. MCP work belongs to the live request, so cancellation applies directly and no detached job
  77. survives a restart.
  78. ## Documentation
  79. - [Architecture](docs/architecture.md) describes process and package boundaries.
  80. - [Storage and evidence](docs/storage-and-evidence.md) defines preservation and provenance.
  81. - [Investigations](docs/investigations.md) covers experiments, comparison, and evidence quality.
  82. - [Adapters](docs/adapters.md) documents provider compatibility and integration policy.
  83. - [Runtime safety](docs/runtime-safety.md) covers limits, recovery, integrity, and privacy.
  84. - [Interfaces](docs/interfaces.md) defines CLI and MCP contracts.
  85. - [Testing](docs/testing.md) describes test selections and known proof gaps.
  86. ## Development
  87. Flameox requires Python 3.12 or newer and uses the committed `uv.lock`. See
  88. [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and contribution guidance.
  89. ```console
  90. uv run ruff check src tests tools
  91. uv run ruff format --check src tests tools
  92. uv run mypy src tests tools
  93. uv run pytest -q
  94. ```
  95. Flameox is licensed under the MIT License.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.