CAUR — Coding Agent Usage Record

CAUR is a small, vendor-neutral record format for measuring the work and resource usage of coding agents.

Coding agents combine model calls, tools, subagents, retries, queueing, and human approvals. Provider invoices expose only part of that activity, while traces are usually too detailed and sensitive for billing or reporting. CAUR defines the portable record between those layers.

Status: v0.1 draft. This is an early proposal, published to invite implementation feedback. Nothing is stable yet.

What CAUR is for

• attribute model and tool usage to an agent run;
• distinguish measured values from estimates;
• represent parallel and nested agent execution without double-counting time;
• retain enough pricing evidence to reproduce a cost calculation;
• exchange usage data without prompts, source code, or tool output.

CAUR is not a tracing protocol, invoice format, telemetry backend, or pricing catalog. It can be produced from any harness and consumed by metering, analytics, chargeback, or billing systems.

The deliberately small model

A CAUR document describes one completed or interrupted agent run:

identity + run relationships
        + outcome and timing
        + model usage
        + tool usage
        + optional cost evidence

The normative draft is in SPEC.md. A machine-readable schema and example are available at:

• schema/caur-v0.1.schema.json
• examples/minimal-run.json
• examples/node-middleware — runnable Node.js middleware that emits CAUR records

Validate the example with any JSON Schema Draft 2020-12 validator:

npx --yes --package ajv-cli --package ajv-formats ajv validate \
  --spec=draft2020 \
  -c ajv-formats \
  -s schema/caur-v0.1.schema.json \
  -d examples/minimal-run.json

Run the middleware example:

cd examples/node-middleware
npm ci
npm test
npm run demo

Design principles

1. Independent core. CAUR does not require OpenTelemetry, CloudEvents, FOCUS, or a specific vendor.
2. Evidence over precision theatre. Every model-usage item states where its measurement came from.
3. No sensitive payloads. Prompts, source code, tool arguments, and tool output do not belong in a CAUR record.
4. Append-only corrections. Published records are not silently rewritten; replacements point to the record they supersede.
5. Extensible without permission. Namespaced extension fields are allowed while the common core stays compact.

Integrations

OpenTelemetry traces can supply run and timing data. CloudEvents can transport CAUR documents. FOCUS or other FinOps formats can receive aggregated exports. These are mappings around CAUR, not dependencies of the format.

Help shape CAUR

CAUR needs implementers, not spectators. Contributions are welcome from agent-harness authors, model gateways, observability projects, FinOps practitioners, and teams operating coding agents in production.

Useful first contributions include:

• capture a real run from Codex, Claude Code, Gemini CLI, OpenCode, or another harness;
• identify a field that cannot be measured consistently across two implementations;
• propose a privacy or double-counting test case;
• build a validator, adapter, or mapping;
• challenge a requirement before it becomes stable.

Start with a GitHub issue or open a pull request. Please read CONTRIBUTING.md. Small, evidence-backed changes are preferred over large theoretical expansions.

Near-term roadmap

• collect fixtures from at least three independent agent harnesses;
• add conformance tests for timing and usage accounting;
• prove one end-to-end exporter and consumer;
• publish v0.1 only after implementation feedback.

License

MIT