JSON output

Xerg has two related JSON outputs:

xerg audit --json returns the local audit summary
xerg audit --push --dry-run and xerg push --dry-run return the exact Push v7 payload

The shared wire types are published in @xerg/schemas. Runtime cost may be observed, locally catalog-estimated, or unpriced; it is not provider-invoice reconciliation.

Local audit summary

npx @xerg/cli@latest audit --json

A current summary contains separate findings and signals arrays:

{
  "auditId": "...",
  "economicAuditId": "...",
  "totalSpendUsd": 148.0,
  "wasteSpendUsd": 8.6,
  "structuralWasteRate": 0.0581,
  "findings": [
    {
      "kind": "retry-waste",
      "affectedSpendUsd": 14.2,
      "avoidableSpendUsd": 8.6,
      "evidenceBasis": "observed",
      "impactBasis": "observed-charge",
      "detectorVersion": "retry-waste.v2"
    }
  ],
  "signals": [
    {
      "kind": "context-growth",
      "scopeLabel": "Support summarizer",
      "metrics": {
        "baselineContextTokens": 25000,
        "finalContextTokens": 95000,
        "callCount": 5
      },
      "associatedSpendUsd": 12.0,
      "associatedSpendBasis": "observed-charge",
      "detectorVersion": "context-growth.signal.v1"
    }
  ],
  "recommendations": [],
  "auditWindow": {
    "startAt": "2026-08-01T00:00:00.000Z",
    "endAt": "2026-08-08T00:00:00.000Z"
  },
  "wasteByWorkflow": [
    {
      "key": "support_triage",
      "wasteUsd": 8.6
    }
  ],
  "spendByAgent": [
    {
      "key": "support_lead",
      "spendUsd": 48.0,
      "callCount": 24,
      "observedShare": 1.0,
      "delegatedSpendUsd": 18.0,
      "delegatedCallCount": 9
    },
    {
      "key": "research_subagent",
      "spendUsd": 18.0,
      "callCount": 9,
      "observedShare": 1.0,
      "delegatedSpendUsd": 0.0,
      "delegatedCallCount": 0
    }
  ],
  "agentDelegations": [
    {
      "parentKey": "support_lead",
      "childKey": "research_subagent",
      "spendUsd": 18.0,
      "callCount": 9
    }
  ],
  "detectionCoverage": {
    "mode": "partial",
    "findingDetectors": [],
    "signalDetectors": [],
    "byDay": [],
    "reasonCodes": []
  }
}

Key rules:

wasteSpendUsd, structuralWasteRate, wasteByDay, recommendations, and gates use only detector-owned avoidableSpendUsd
affectedSpendUsd describes the full proved pattern and is not a savings estimate
signals expose observed metrics, optional human-readable scopeLabel, and optional associatedSpendUsd plus associatedSpendBasis; chain-backed deep-loop-activity may include chainOccurrenceCount, fingerprintedToolExecutionCount, and toolInputDistinctRatio; associated spend is descriptive, not waste or savings. Earlier Push v7/v6 and stored v5 history remain readable without scopeLabel.
component-level ownership prevents overlapping findings from double-counting one charge
missing required evidence appears in detector coverage rather than being inferred
pricingCoverage reports priced and unpriced calls/tokens; unknown cost is not treated as zero
auditWindow records the requested analysis interval; endAt is the exclusive upper boundary
wasteByWorkflow is detector-attributed waste grouped by the owning workflow; it reconciles exactly to audit waste and uses Unattributed when ownership cannot be resolved
spendByAgent is the authoritative flat agent rollup when call-level agent identity is available
agentDelegations records observed immediate parent-to-child relationships. Its spend is already included in the child row and audit total, so never add relationship spend to either total
agentDelegations is omitted when no parent relationship was observed. Older summaries can contain delegated totals without the relationship rows needed to identify their children

Local summaries may also include toolChains and localDiagnostics (xerg-local-diagnostics/v1) plus source-specific blocks such as mechanicalEfficiency, analysisCoverage, toolActivity, workloadEconomics, Cursor usage detail, or QM reconciliation detail. Diagnostic packets retain SHA-256 digests and byte counts, never raw or truncated tool arguments/results. These local blocks, source paths, per-TTL cache-write buckets, and local pricing-limitation details do not cross Push v7. The existing aggregate tokenEconomics.cacheWriteTokens remains the wire total.

Multi-source JSON

With --remote-config, more than one successful source returns a top-level sources array. Exactly one successful source returns the normal single-summary shape.

Push v7

npx @xerg/cli@latest audit --push --dry-run
npx @xerg/cli@latest push --dry-run

The current top-level discriminator is version: 7:

{
  "version": 7,
  "summary": {
    "auditKind": "runtime",
    "auditId": "...",
    "economicAuditId": "...",
    "findings": [],
    "signals": [],
    "recommendations": [],
    "auditWindow": {
      "startAt": "2026-08-01T00:00:00.000Z",
      "endAt": "2026-08-08T00:00:00.000Z"
    },
    "wasteByWorkflow": [
      {
        "key": "support_triage",
        "wasteUsd": 8.6
      }
    ],
    "spendByAgent": [
      {
        "key": "support_lead",
        "spendUsd": 48.0,
        "callCount": 24,
        "observedShare": 1.0,
        "delegatedSpendUsd": 18.0,
        "delegatedCallCount": 9
      }
    ],
    "agentDelegations": [
      {
        "parentKey": "support_lead",
        "childKey": "research_subagent",
        "spendUsd": 18.0,
        "callCount": 9
      }
    ],
    "comparison": {
      "baselineAuditId": "...",
      "spendComparisonAvailable": true,
      "findingChanges": {
        "newHighConfidenceWaste": [],
        "resolvedHighConfidenceWaste": [
          {
            "kind": "retry-waste",
            "detectorVersion": "evidence-strict-v1",
            "title": "Repeated requests consumed avoidable spend",
            "scope": "workflow",
            "scopeId": "support_triage",
            "baselineCostImpactUsd": 8.6,
            "deltaCostImpactUsd": -8.6
          }
        ],
        "worsenedHighConfidenceWaste": []
      }
    },
    "detectionCoverage": {
      "mode": "partial",
      "measure": {
        "totalRequestCount": 83,
        "eligibleRequestCount": 61,
        "totalSpendUsd": 148.0,
        "eligibleSpendUsd": 104.2
      },
      "findingDetectors": [],
      "signalDetectors": [],
      "detectors": [],
      "byDay": [],
      "reasonCodes": []
    },
    "sourceStability": {
      "status": "stable",
      "reasonCodes": [],
      "openRunCount": 0,
      "snapshotRetryCount": 0
    },
    "spendByDay": [
      {
        "date": "2026-08-22",
        "spendUsd": 148.0,
        "observedSpendUsd": 120.0,
        "estimatedSpendUsd": 28.0,
        "callCount": 83,
        "pricedCallCount": 80,
        "unpricedCallCount": 3
      }
    ]
  },
  "meta": {
    "cliVersion": "0.20.0",
    "sourceId": "...",
    "sourceHost": "...",
    "environment": "local",
    "pushedAt": "...",
    "dedupKey": "..."
  }
}

Push payloads exclude source files, local paths, prompts, tool arguments, tool results, cache content, raw correlation IDs, and local detector details. Input, result, state, and cache identities are content-free fingerprints computed locally. Current producers may include the optional requested auditWindow, wasteByWorkflow, observed agentDelegations, detector-versioned comparison.findingChanges, and comparison.spendComparisonAvailable. The last flag is true only when both measurements have priced calls; consumers treat an absent flag as unavailable. Older Push v7, v6, and stored history remain valid without these fields.

Legacy v5

The API continues to accept and store v5 payloads unchanged. Readers display them with a Legacy detection method badge and an upgrade advisory. New v5 pushes cannot create or recur current optimization records. Push v6 remains accepted and meters the same daily runtime spend as v7; v7 adds daily priced and unpriced call counts for coverage transparency.

When to use which format

use audit --json for local automation that needs source metadata or local-only diagnostics
use --push --dry-run to inspect the privacy-bounded payload before sending it

Concepts

Hosted workspace

Automate and share

Releases

JSON output

Local audit summary

Multi-source JSON

Push v7

Legacy v5

When to use which format

​Local audit summary

​Multi-source JSON

​Push v7

​Legacy v5

​When to use which format

Local audit summary

Multi-source JSON

Push v7

Legacy v5

When to use which format