I built Statusline: an open-source Codex usage monitor for desktop and mobile

Alan Rodrigo Vivares — Wed, 09 Sep 2026 13:14:31 +0000

Statusline started with a small interface detail I wanted to make more useful:

Weekly limit: [███████████░░░░░░░░░] 53% left (resets 09:02 on 2 Sep)

That line answers two practical questions: how much capacity is left, and when it
resets.

I wanted to keep that information visible while working—and make it accessible
from my phone without opening a terminal.

That became Statusline, an open-source desktop companion with native mobile
apps and home screen widgets.

The iPhone app is now available on the App Store. Desktop builds and Android are
available in beta.

What Statusline does

Statusline reads usage information from your local Codex session and presents the
remaining quota, reset time, and sample timestamp. The desktop companion also
displays short-window usage and account-plan information when available.

It lives in the menu bar on macOS or the system tray on Windows and Linux. Optional
encrypted synchronization carries a minimal quota snapshot to the mobile apps and
their widgets.

The visual language, called Data Plane, grew out of the original terminal
display: segmented meters, restrained typography, dark surfaces, and an amber
accent.

The interface is intentionally focused. Statusline monitors your personal Codex
quota; it does not run coding tasks, manage conversations, or increase your usage
limits.

The architecture: shared protocol, native interfaces

The project uses different technologies where they fit:

Desktop: Tauri, Rust, and TypeScript.
iPhone: SwiftUI and WidgetKit.
Android: Kotlin, Jetpack Compose, and native app widgets.
Relay: TypeScript, currently deployed on Cloudflare Workers with D1.

Instead of sharing one UI implementation across every platform, the clients share
a versioned synchronization contract.

The data flow looks like this:

Local Codex runtime
        │
        │ Usage metadata over local stdio
        ▼
Desktop companion
        │
        │ Encrypt snapshot with AES-256-GCM
        ▼
HTTPS relay
        │
        │ Encrypted snapshot
        ▼
Native mobile app
        │
        │ Decrypt, validate, and cache
        ▼
Home screen widget

The desktop companion communicates with the local Codex App Server process. It
normalizes the relevant usage information before deciding what to display locally
and what to synchronize.

The current mobile payload is deliberately small: remaining percentage, reset
time, and the time of the reading.

A Windows computer and an iPhone use the same pairing and snapshot protocol as a
Linux computer and an Android phone. The synchronization flow does not require a
shared iCloud account.

The relay protocol specification
and encryption interoperability fixture are versioned in the repository so the
Rust, Swift, and Kotlin implementations can be checked against the same contract.

Keeping account credentials out of synchronization

A quota widget should not need your prompts, source code, or conversation history.

Statusline does not require an OpenAI API key. The local Codex runtime manages its
own authentication; Statusline does not copy its credential files or send those
credentials to the relay.

Device pairing separates authentication from encryption:

The companion creates a relay channel and generates an encryption key locally.
A single-use pairing QR transfers the pairing information and encryption key to the phone.
The phone exchanges the temporary pairing token for a reader credential.
The companion encrypts quota snapshots before uploading them.

The relay never receives the encryption key. It stores the encrypted snapshot
alongside the operational information needed to manage the channel, such as
credential hashes and timestamps.

That distinction matters: encrypted payloads do not mean the service has no
metadata. The goal is to keep the quota contents and Codex credentials outside the
relay's trust boundary.

The pairing QR is also sensitive information. It should not appear in screenshots,
public issue reports, or promotional videos.

Supporting macOS users without a separate CLI installation

One practical issue came up during development: some people use Codex through the desktop application and have never installed a standalone CLI.

The latest macOS beta can discover the Codex executable bundled inside supported
ChatGPT or Codex.app installations. That allows Statusline to use the existing
local runtime without requiring a separate CLI installation.

There are important boundaries to this support:

Older desktop-app versions may not contain a compatible runtime.
Session reuse depends on how the local Codex installation manages authentication.
Windows and Linux currently retain their CLI-based discovery.

If a session is unavailable, Statusline reports that state. It does not attempt to
extract desktop cookies or silently migrate account credentials.

The supported sources and troubleshooting steps are documented in the
Codex runtime guide.

A widget shows a snapshot, not a live connection

One design decision I want to be explicit about is freshness.

The widgets read a local cache populated by the mobile app. They display the most
recently synchronized sample, not a continuously streaming connection to Codex.

A new reading depends on the companion collecting and publishing it, the phone
fetching it, and the operating system allowing the relevant work.

That is why the sample timestamp matters alongside the percentage. A reading can
still be useful when it is cached, but users should be able to understand how
recent it is.

Push-assisted background refresh is planned; it is not something the current
release promises.

Availability

Platform	Current availability
iPhone	Available on the App Store; requires iOS 17 or later
Android	Beta APKs and Google Play closed testing
macOS	Universal beta DMG and PKG installers, signed and notarized
Linux	Beta DEB, RPM, and AppImage packages with detached OpenPGP signatures
Windows	Beta NSIS and MSI installers; currently unsigned previews

Windows signing remains unfinished. SmartScreen may warn about or block those
installers. Signed checksums help verify file integrity, but they do not replace a
trusted Windows publisher signature.

The applications support English and Spanish, following the system language with
English as the fallback.

What comes next

The first version focuses on Codex.

The longer-term direction is a single view of capacity across coding agents. AGY,
Claude Code, and GitHub Copilot are on the research roadmap, but they are not
supported integrations today.

The challenge is not simply adding more progress bars. A future adapter needs a
reliable, authorized data source and a clear definition of what its numbers mean.
Requests, tokens, credits, and subscription percentages should not be presented as
interchangeable measurements.

Other planned improvements include local usage history, low-capacity alerts,
configurable multi-provider widgets, and a separately packaged Linux relay for
self-hosting.

These are directions, not delivery commitments. The
public roadmap tracks
the scope and constraints.

Try it, or help improve it

Statusline is available under the MIT license:

I'm particularly interested in feedback on initial setup, device pairing, and
widget readability.

I'm also looking for Android testers before the public Google Play release. If you
use Codex and would like to try the Android app, leave a comment or get in touch
through the project.

What would make a quota monitor useful in your workflow: a simple
remaining-capacity indicator, reset notifications, or usage history?

Statusline is an independent project. It is not affiliated with, sponsored by, or
endorsed by OpenAI.

DEV Community: Alan Rodrigo Vivares