Add machine-readable status output (for example: /status --json or codex status --json)

I'm the human on the hook for this / responsible for followups, etc.

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

• #15281

Powered by Codex Action

Closing this since it appears to be a duplicate of an existing request.

Reopening this because it is not actually a duplicate of #15281. #15281 is a human-facing CLI usage/limits visibility request (5h/weekly quota display). This issue is asking for a machine-readable status surface, such as or , so integrations do not need to scrape rendered terminal output.

Adding a concrete integration-oriented use case for this request.

For terminal automation and multi-session workflows, the most useful version of this would be a stable "current session snapshot" command, not just a JSON rendering of the human /status text.

Suggested command shape:

codex status --json
codex status --json --session <session-id>

Optional later extension:

codex status --json --watch

where --watch could emit newline-delimited JSON snapshots when relevant state changes. That could remain a follow-up; the one-shot command would already be very useful.

Suggested JSON contract, with fields optional/nullable where the data is unavailable:

{
  "schema_version": 1,
  "codex_version": "0.x.y",
  "session": {
    "id": "local-session-id",
    "thread_id": "remote-thread-id-if-known",
    "cwd": "/path/to/project",
    "started_at": "2026-04-24T12:00:00Z",
    "last_activity_at": "2026-04-24T12:03:18Z"
  },
  "runtime": {
    "variant": "cli",
    "model": "gpt-5.x",
    "reasoning_effort": "medium",
    "mode": "code",
    "approval_policy": "on-request",
    "sandbox": "workspace-write",
    "network_access": false
  },
  "turn": {
    "state": "idle",
    "current_tool": null,
    "pending_approval": null,
    "last_error": null
  },
  "usage": {
    "context_window_tokens": 258000,
    "input_tokens": 12345,
    "output_tokens": 678,
    "context_used_percent": 12.3
  },
  "limits": {
    "five_hour": {
      "used_percent": 37,
      "resets_at": "2026-04-24T17:00:00Z"
    },
    "weekly": {
      "used_percent": 90,
      "resets_at": "2026-04-28T00:00:00Z"
    }
  }
}

The important part is not the exact field list; it is the stability of the surface:

• Stable top-level keys and a schema_version.
• Machine-readable enum values for turn state, mode, sandbox, and approval policy.
• Exit codes that distinguish "not logged in", "no active/local session found", and "status unavailable".
• No transcript content, prompts, command output, secrets, or file contents in the default payload.
• Best-effort values are fine as long as unavailable fields are null or omitted predictably.

This would let external tools build statuslines, terminal titles, health checks, dashboards, and orchestration glue without scraping TUI text or depending on internal storage formats. It also complements the separate event-stream idea in #16484: status --json gives the current snapshot, while an event stream would give the transition history.

A minimal JSON status with just the current session/thread id, effective model, and reasoning effort
would already unblock automation that tracks declared vs actual runtime config.

Today wrappers can read config.toml, but that only gives defaults/declared values. After
interactive /model or /effort changes, external tooling has no supported way to confirm the
effective runtime config without scraping TUI text or relying on internal logs.

Suggested minimal fields:

```json
{
"session_id": "...",
"model": "gpt-5.5",
"reasoning_effort": "xhigh"
}

This would let integrations avoid parsing ~/.codex/log/codex-tui.log or other internal implementation details.