Repository navigation
Add machine-readable status output (for example: /status --json or codex status --json) #16037
Description
Summary
Codex already builds /status from structured internal state, but today that information is only exposed as rendered TUI text.
It would be useful to expose the same status snapshot through a supported machine-readable surface, for example:
/status --jsoncodex status --json
Problem
Integrations can currently get some Codex state from existing files like auth.json and config.toml, but /status includes additional live session/runtime information that is not cleanly available elsewhere, such as:
- effective model / reasoning configuration
- current thread metadata
- token usage
- rate limit snapshot data
Today the only practical workaround is scraping the rendered /status text, which is brittle and formatting-dependent.
Why this seems feasible
From the current implementation, /status is already assembled from structured data before it is rendered:
ChatWidget::add_status_output()gathers config, token info, usage, thread metadata, and rate limit snapshotsstatus/already turns those snapshots into stable display structures for rendering
That suggests the code is already very close to supporting a JSON output path without needing a big redesign of the status feature itself.
Request
Please expose the existing status snapshot through a supported machine-readable interface.
A minimal version would be enough:
- stable top-level fields for current config/session state
- token usage
- thread metadata
- rate limit snapshots
Suggested shape
No strong preference on exact UX, but one of these would work well:
codex status --json/status --jsoncodex status --format json
Why this matters
There is already precedent for machine-readable output being a supported integration surface in Codex (for example codex exec --json).
A structured status command would make it much easier to build reliable tooling around Codex without depending on internal protocol details or scraping terminal output.
Happy to contribute an implementation if this direction is welcome.
Activity
randallb commentedon Mar 27, 2026
I'm the human on the hook for this / responsible for followups, etc.
github-actions commentedon Mar 27, 2026
Potential duplicates detected. Please review them and close your issue if it is a duplicate.
Powered by Codex Action
bft-codebot commentedon Mar 27, 2026
Closing this since it appears to be a duplicate of an existing request.
bft-codebot commentedon Mar 27, 2026
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.
YitzhakMizrahi commentedon Apr 24, 2026
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
/statustext.Suggested command shape:
Optional later extension:
where
--watchcould 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:
schema_version.nullor 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 --jsongives the current snapshot, while an event stream would give the transition history.itssosunny commentedon May 10, 2026
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. Afterinteractive
/modelor/effortchanges, external tooling has no supported way to confirm theeffective runtime config without scraping TUI text or relying on internal logs.
Suggested minimal fields:
{ "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.