io.github.morluto/flameox

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

Related MCP server: flameox

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.