flameox

<h1 align="center">flameox</h1> <p align="center"> <img src="docs/assets/flameox-mascot-flamegraph.png" width="420" alt="flameox mascot: an ox with a flame graph between its horns" > </p> <p align="center"><strong>Bounded local runtime evidence for coding agents.</strong></p> <!-- mcp-name: 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: ```console 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](npm/README.md) for details. Update existing MCP registrations with: ```console 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: ```console 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: ```console uvx flameox mcp serve ``` For local development, clone the repository, install its development dependencies, and inspect the available tools: ```console 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](docs/interfaces.md). 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](docs/architecture.md) describes process and package boundaries. - [Storage and evidence](docs/storage-and-evidence.md) defines preservation and provenance. - [Investigations](docs/investigations.md) covers experiments, comparison, and evidence quality. - [Adapters](docs/adapters.md) documents provider compatibility and integration policy. - [Runtime safety](docs/runtime-safety.md) covers limits, recovery, integrity, and privacy. - [Interfaces](docs/interfaces.md) defines CLI and MCP contracts. - [Testing](docs/testing.md) describes test selections and known proof gaps. ## Development Flameox requires Python 3.12 or newer and uses the committed `uv.lock`. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and contribution guidance. ```console 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.