morluto/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:
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:
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:
To launch the stdio MCP server manually:
For local development, clone the repository, install its development dependencies, and inspect the
available tools:
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