Urgent.News

What's breaking now, across thousands of outlets.

Tech

How I Made Codex CLI Resume Itself After Hitting a Usage Limit

Cybokron Limit Guard is a free, open-source macOS menu bar app that tracks Codex CLI usage limits and resumes your sessions once the limit resets.

How I Made Codex CLI Resume Itself After Hitting a Usage Limit

When working with lengthy tasks using the Codex CLI, users often encounter a situation where the session stops halfway due to reaching the usage limit. The Codex CLI periodically checks if the usage limit has been exceeded, and if so, it stops the session. This can be frustrating, especially when the weekly limit runs out, causing users to wait for days for the limit to reset.

To address this issue, I created a free and open-source macOS menu bar app called Cybokron Limit Guard. This app focuses on how it works rather than on the app itself. The app relies on two local sources to access the necessary signals from Codex. The first source is the codex app-server codex's own local API, which speaks newline-delimited JSON-RPC.

The API provides information about the 5-hour and weekly windows, their usage percentage, reset time, and reset credits. The protocol is experimental, so the app treats every field defensively.

The second source is the session log, which is a JSONL rollout file stored under ~/.codex/sessions/. Each Codex session writes a new entry to this file, with each turn ending in a task_complete event. If a turn is cut off due to the usage limit, the error message includes "usage_limit_exceeded." This single field helps the app differentiate between finished turns, overload errors, and aborted turns without making assumptions.

To ensure safety, the app does not rely solely on the reset time. Instead, it uses the ordinaryUsageAllowed field, which should be true when the limit resets. If this value is false or cannot be decoded, the app keeps polling with an adaptive back-off strategy. The polling rate adjusts based on the window's progress, adapting to five minutes normally, one minute when a window passes 90%, and every 30 seconds after a reset.

My initial idea was to automate the "continue" command using keystrokes, but I decided against it for safety reasons. Codex's Terminal session communicates with a shared app-server daemon, and the app communicates with this daemon instead of typing directly into the terminal. This approach avoids potential issues with keystrokes, such as entering the wrong text or interacting with other parts of the interface unintentionally.

The app sends a "continue" command with a fresh clientUserMessageId, which the agent acknowledges within two minutes. If the acknowledgment is not received, the app marks the attempt as unconfirmed and does not resend it automatically. A user-friendly interface displays the message in the conversation's language, allowing users to add support for other languages using Apple's NaturalLanguage framework.

To maintain control and prevent misuse, the app includes several guardrails. Opt-in sessions are required, and automatic continues are disabled by default. A 10-second countdown runs before each continue, and users can cancel it if needed. The app also performs re-checks before sending the command, ensuring that the session is active, the Codex process is running, and the app is not paused.

Additionally, the app enforces a limit of three auto-continued turns per thread, separated by at least two minutes. If three auto-continued turns occur within a minute, the app assumes the agent is not making progress and stops.

The app detects when a field required for its actions disappears after a Codex update, pausing all automatic actions until the issue is resolved. It also provides a notice on first launch, requiring users to read and accept the terms before any automatic actions can occur. The app handles reset credits carefully, displaying them with their expiry dates and prioritizing those that expire within 24 hours.

Automatic reset usage is off by default and requires confirmation before spending a reset credit. The app spends a credit at most once per account every seven days, only when the weekly limit is approaching (at 97% by default) and only when Codex is actively being used. The app ensures idempotency by writing a ledger entry with an idempotency key before calling the consume endpoint. If the call times out or the app crashes, it retries the action using the same key, preventing accidental double-spending.

Finally, the app offers forecasting and history features. It estimates the usage rate based on recent samples and displays an estimated completion time for the weekly limit. A chart shows daily token usage over the last 7, 30, or 90 days, providing users with valuable insights into their Codex consumption patterns.

Written by urgent.news from HackerNoon's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.

Read the original at hackernoon.com →

More in Tech

More from Tuesday 17 November →