Flameox

flameox

Bounded local runtime evidence for coding agents.

Flameox 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.