Bounded local runtime evidence for coding agents.
\n\n\n\nFlameox coordinates profilers, benchmark tools, trace processors, and direct\nlocal targets. It gives an agent a short path from an explicit native artifact\nor live command to bounded evidence, while keeping preservation optional.\n\nThere is no workspace to initialize, `flameox.toml`, SQLite control plane,\ndurable job to poll, or parent-directory discovery. Analyze existing artifacts\nby passing their exact paths and formats.\n\n## Quick start\n\n```console\nuv sync --extra dev --extra memory --extra trace --extra cpu\nuv run flameox mcp inspect\nuv run flameox analyze artifact.preview /absolute/path/to/artifact.json\nuv run flameox capture --provider direct --cwd \"$PWD\" -- python benchmark.py\n```\n\nThe MCP server has no workspace or project binding:\n\n```console\nuv run flameox mcp serve\n```\n\nRun the short global setup wizard through npm:\n\n```console\nnpx flameox@latest setup\n```\n\nSetup detects Claude Code, Cursor, OpenCode, Codex, Gemini CLI, and Google Antigravity, then asks\nwhich clients should use Flameox. It preserves unrelated client configuration and writes a\nPython 3.12 `uvx` launcher pinned to the exact Flameox release that ran setup. Restart or reconnect\nchanged clients afterward. For automation, pass `--client codex --yes`, repeat `--client`, or use\n`--all --yes`; `--dry-run` reports the same global paths without writing them. Detection is never\nautomation consent.\n\nExplicit `--provider` selections prepare the exact version-pinned `uvx` environment in the saved\nlauncher by resolving it once into uvx's cache; they do not create a persistent global `uv tool`\ninstallation. Each invocation declares the complete managed provider set for that launcher rather\nthan adding to remembered state. Use `--timeout-seconds` for a slow cold resolution. System and\nvendor tools are diagnosed with external install guidance. Setup never initializes or mutates a\nproject.\n\n## Authority model\n\n```text\nexplicit artifact paths / typed direct target\n │\n ▼\n bounded process-lifespan runtime\n │ │\n ▼ ▼\n inline evidence session scratch/cache\n │\n explicit preservation\n │\n ▼\n user Flameox data directory\n```\n\nAnalysis and unpreserved capture make no durable Flameox writes. Capture\nartifacts stay in bounded session scratch until preservation, least-recently-used eviction, or\nserver shutdown. An evicted `analysis_id` returns `EXPIRED_SESSION_ANALYSIS`; preserve conclusions\nbefore relying on them. The first `preserve_evidence` call creates the user-level Flameox data\ndirectory and stores native bytes and a canonical evidence bundle by SHA-256. `FLAMEOX_DATA_DIR`\noverrides the platform default for isolation or another storage location. Flameox never edits\nproject Git files.\n\nThe console-retention default is bounded diagnostics in memory, with explicit\nomission counts. Keep native artifacts when needed; retain full console output on\ndisk only when it is the evidence, an oracle needs it, or the caller requests it.\nPreservation alone does not request full logs. See\n[console retention](docs/storage-and-evidence.md#console-retention-and-disk-backing).\n\nWorkload time and RSS budgets are optional: use `target.budget` in MCP or\n`--workload-budget` in CLI capture. They do not inherit analysis-worker limits;\ncancellation and storage protection remain active when no workload budget is set.\n\nThe agent owns hypotheses and narrative findings in its own notes. Flameox owns\nonly observed inputs, effective requests, execution provenance, typed evidence,\ncoverage, truncation, limitations, and optional immutable preservation.\n\n## MCP interface\n\nThe server exposes six operations. Read-only analysis and executing capture remain separate for\naccurate MCP effect annotations, while each accepts a discriminated capability request that retains\ncapability-specific options and provider validation:\n\n```text\nanalyze capture_and_analyze\nprepare_providers preserve_evidence\nrescue_evidence query_evidence\n```\n\nThe two operation schemas advertise every capability's exact options and compatible providers.\nAnalysis and capture have separate names and annotations because reading an artifact and executing a\ntarget are materially different effects. Tool search happens in the MCP client; Flameox does not\nrequire an additional catalog-search call.\n\nFor example, a bounded artifact preview calls `analyze` with the capability inside `request` and\nthe response bound beside it:\n\n```json\n{\n \"request\": {\n \"capability_id\": \"artifact.preview\",\n \"sources\": [{\"kind\": \"path\", \"path\": \"/absolute/path/to/output.log\"}]\n },\n \"page_size\": 100\n}\n```\n\n`capture_and_analyze` uses the same outer shape, but its `request` also contains `target`,\n`provider`, and `execution`. Use `request.execution.kind: \"single\"` for one run and\n`request.execution.kind: \"experiment\"` with an experiment `design` for paired cases. When a result\ncontains `next_page`, call its named tool with its arguments unchanged; continuing a capture uses\n`analyze` and never runs the target again.\n\nIt exposes one resource template, `flameox://evidence/{evidence_id}`, for the\ndigest-bound, redacted projection of the canonical immutable manifest. Full\nargv, environment values, working directories, and host paths remain available\nonly through explicit local manifest inspection. Native artifact bytes are\ndeliberately not available as MCP resources.\n\nDirect capture accepts an argv array, an explicit absolute cwd, bounded environment overrides, a\ntyped compatible-provider variant, capability-specific options, and an explicit single/experiment\nchoice inside `request`. The only public response bound, `page_size`, is a top-level tool argument.\nServer resource ceilings stay out of the request schema. There is no generic provider or\nanalysis-arguments object.\nShell strings are never accepted. Work remains owned by the live MCP request, so SDK progress and\ncancellation apply directly; there are no detached or restart-surviving tasks.\n\nManaged external collectors such as py-spy execute from Flameox's uvx\nenvironment. In-process collectors such as coverage.py and Memray are verified\nin, and run with, the workload's declared Python interpreter. Flameox does not\nsubstitute one Python runtime for the other. When a capture reports a missing managed provider,\n`prepare_providers` prepares its version-pinned uvx environment and returns that same launcher for\nreconnection. The agent supplies the complete provider list it wants in that launcher; Flameox does\nnot merge it with prior calls. Preparation does not modify the running MCP process. When the client\nmust reconnect, the result returns a typed `next_action` with `kind: \"reconnect_mcp\"`, an agent-facing\nmessage, and the launcher to use. The managed provider IDs are `aiperf`, `memray`, `otlp`, `perfetto`,\n`py-spy`, and `torch`. Host tools, drivers, and permissions are never installed or changed; the same\nresult reports their setup guidance.\n\nComparison is intentionally a two-stage workflow. Flameox captures representative baseline and\ncandidate summaries separately, optionally preserves them, and then passes both artifacts to an\n`analyze` call with the matching comparison `request.capability_id`: `benchmark.compare`,\n`inference.compare`, or `kernel.compare`. Those variants are intentionally absent from\n`capture_and_analyze`: experiment capture measures cases and reports an effect, but it is not a\nsubstitute for comparing explicit native artifacts.\n\n## Evidence quality\n\nAn investigation still follows:\n\n```text\nsymptom → capture or explicit artifact → bounded evidence → hypothesis\n → discriminating experiment → supported, refuted, or inconclusive finding\n```\n\nA profile supports exploration, not causality. Confirmatory claims require a\nrepresentative target, declared metric and estimand, compatible identities,\npreserved samples, a practical threshold, and an appropriate semantic oracle.\n\nSee [architecture](docs/architecture.md), [storage and evidence](docs/storage-and-evidence.md),\n[interfaces](docs/interfaces.md), [runtime safety](docs/runtime-safety.md), and\n[investigations](docs/investigations.md) for the contracts.\n\n## Development\n\nFlameox requires Python 3.12 or newer and uses the committed `uv.lock`.\n\n```console\nuv run ruff check src tests tools\nuv run ruff format --check src tests tools\nuv run mypy src tests tools\nuv run lint-imports\nuv run pytest -q\n```\n\nThe project is licensed under the MIT License.\n", "bytes": 8790, "sha": "d8824cde0a3d9f267ae5282f415447ac4d17c9ef8f22a8630e3a156217bc08b1", "repo_slug": "morluto/flameox", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_morluto_flameox_fe6b69c9/readme" }