JSON schema

agentop --json prints a single-line snapshot to stdout and exits. agentop --json --pretty indents it for human reading.

The schema is versioned. schema_version is currently 1 and will not remove or rename fields during the 1.x release line. Additive changes (new fields) are allowed without a version bump. Breaking changes increment the number.

The authoritative, machine-checked reference lives at docs/output-schema.md in the repository and is included below verbatim.

agentop JSON output schema

agentop --json emits a single-line JSON object (schema version 1). agentop --json --pretty emits the same object with 4-space indentation.

Stability promise

Schema version 1 will never remove or rename a field. Additive changes (new fields, new optional members in nested objects) are allowed without a version bump and will be noted in CHANGELOG.md as a minor change. A schema-breaking change (field removal, rename, type change) increments schema_version to 2.

Consumers must check schema_version before parsing. A schema_version of 1 guarantees the fields listed below are always present (never absent due to skip_serializing_if).

Top-level fields

system object

agent_summary object

processes array (recursive)

Each entry in processes is a root agent process. Its children field contains the same structure recursively. Non-agent child processes appear inside children with kind: null.

activity_state values

telemetry object

The shape of the telemetry object is the same for all providers. Fields that a provider does not track are null. The provider field identifies the source.

schema_version remains at 1 — this field is additive.

Claude provider

Present on root-level Claude process entries when ~/.claude/sessions/ exists and a matching session file has been found for the PID. null otherwise.

Codex provider

Present on root-level Codex process entries when ~/.codex/sessions/ exists (or $CODEX_HOME/sessions/) and a rollout file whose filename timestamp is within ±90 s of the process start time is found. null otherwise.

Pricing table is pinned at 2026-04-21 and covers: gpt-5-codex, gpt-5, o4-mini, o4, o3-mini, o3, gpt-4.1, gpt-4o, gpt-4. Model lookup uses longest-prefix matching. All costs are estimates.

status values

Privacy

The telemetry object intentionally omits all transcript content. The --json output never includes message text, tool arguments, or any other content from the conversation transcript, regardless of what the TUI detail view displays.

This promise is enforced at the serialization boundary in src/output/json.rs: TelemetryJson (the serialized form) is a separate type from AgentTelemetry (the in-memory form). The conversion function build_telemetry_json() only copies aggregated counters, never the recent_messages field.

Example (pretty-printed)

{
  "schema_version": 1,
  "generated_at": "2026-04-21T13:45:00Z",
  "agentop_version": "0.7.1",
  "system": {
    "cpu_usage_percent": 42.1,
    "total_memory_bytes": 17179869184,
    "used_memory_bytes": 8421376,
    "total_swap_bytes": 4294967296,
    "used_swap_bytes": 0,
    "cpu_count": 10
  },
  "agent_summary": {
    "claude_count": 2,
    "codex_count": 1,
    "total_cpu_percent": 15.2,
    "total_memory_bytes": 2147483648
  },
  "processes": [
    {
      "pid": 5678,
      "parent_pid": null,
      "kind": "codex",
      "name": "codex",
      "display_name": "codex",
      "cmd": ["codex"],
      "exe_path": "/usr/local/bin/codex",
      "cwd": "/Users/me/project",
      "cpu_percent": 1.1,
      "memory_bytes": 524288000,
      "status": "Run",
      "start_time_unix": 1714000200,
      "uptime_seconds": 100,
      "activity_state": "idle",
      "activity_state_seconds": 60,
      "telemetry": {
        "provider": "codex",
        "session_id": "019d2d54-207e-7b80-b98e-2968e4d1204a",
        "model": "gpt-5",
        "status": "waiting_input",
        "input_tokens": 25000,
        "output_tokens": 1800,
        "cache_write_tokens": null,
        "cache_read_tokens": 3000,
        "context_tokens": 29800,
        "context_window": 258400,
        "context_fill_percent": 11.5,
        "cost_usd": 0.19,
        "cost_is_estimated": true,
        "pending_tool": null,
        "decay_score": null,
        "subagent_count": 0,
        "last_event_timestamp": null
      },
      "children": []
    },
    {
      "pid": 1234,
      "parent_pid": null,
      "kind": "claude",
      "name": "claude",
      "display_name": "claude",
      "cmd": ["claude", "--resume", "abc"],
      "exe_path": "/usr/local/bin/claude",
      "cwd": "/Users/me/project",
      "cpu_percent": 3.4,
      "memory_bytes": 1073741824,
      "status": "Run",
      "start_time_unix": 1714000000,
      "uptime_seconds": 300,
      "activity_state": "active",
      "activity_state_seconds": 42,
      "telemetry": {
        "provider": "claude",
        "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "model": "claude-opus-4-7",
        "status": "idle",
        "input_tokens": 42000,
        "output_tokens": 3100,
        "cache_write_tokens": 12000,
        "cache_read_tokens": 28000,
        "context_tokens": 82000,
        "context_window": 1000000,
        "context_fill_percent": 8.2,
        "cost_usd": 0.87,
        "cost_is_estimated": true,
        "pending_tool": null,
        "decay_score": 3,
        "subagent_count": 2,
        "last_event_timestamp": "2026-04-21T13:44:55Z"
      },
      "children": [
        {
          "pid": 1235,
          "parent_pid": 1234,
          "kind": null,
          "name": "node",
          "display_name": "node",
          "cmd": ["node", "/path/to/script.js"],
          "exe_path": "/usr/local/bin/node",
          "cwd": "/Users/me/project",
          "cpu_percent": 1.2,
          "memory_bytes": 536870912,
          "status": "Run",
          "start_time_unix": 1714000010,
          "uptime_seconds": 290,
          "activity_state": null,
          "activity_state_seconds": null,
          "telemetry": null,
          "children": []
        }
      ]
    }
  ]
}