Account usage and limits

Run nid usage (or nid limits without a target) to see the latest subscription usage per agent and billing account. The terminal app's /usage command and the dashboard header's Account usage panel show the same account view.

Each row names the window, percentage used, reset time, observation age (as of) and source. Sessions sharing an agent login feed the same account row. API billing is kept separate, also during an API-key fallback. When nid knows the login (Claude's auth status, Codex's account id) the account is a short hash of it (acct-…), so two logins never mix and one login's data never clears another's limit; when it does not know, the account is default. Readings older than an hour are marked (stale). Once a window's reset time passes, its old percentage is hidden: reset (not seen since) means current usage is unknown, not zero.

Codex usage comes from its app-server's read-only account endpoint and recent local rollout files under CODEX_HOME (default ~/.codex). The files also capture usage outside nid, including a changed percentage after a limit-reset credit. Reads are bounded, so very old snapshots or snapshots buried behind large output may be absent. Claude Code reports usage while sessions run (each rate_limit_event), and nid asks a running Claude session for its /usage data (the get_usage control request: the plan's 5-hour, weekly and per-model windows from your account, not a model call). Claude Code may answer that from a cached snapshot without saying how old it is, so such a reading only clears a limit when it shows a new window (a later reset time than the limit's); otherwise the reset time or a live rate-limit event does. nid asks one running session per login, preferring an idle one. With no Claude session running, nid has nothing fresh to ask and says so, keeping the age of its last observation visible. Reading usage never starts a paid model turn, and nid never starts an agent just to read usage.

Use nid limits <group> for sessions' last reports, including stopped sessions labelled stale, or nid limits --sessions for all sessions. Account data may be newer than a session's last report. nid usage --json returns the account report and source status; nid limits <group> --json returns the session records, including their historical percentages and timestamps.

When newer account data shows a limited window is open, or its reset time passes, nid clears the active limit and resumes held deliveries. "Newer" means read at least 30 seconds after the session became limited, and when the limit named its window (weekly, 5-hour) that window itself must have been seen open. For example, after you use a Codex limit-reset credit, the next Codex session file or app-server read shows the lower percentage and the limited Codex sessions resume. While any session is limited the daemon re-reads the free sources every 5 minutes; nid usage and the dashboard also trigger a read (at most once a minute). A stopped session never shows a live limit: nid ls shows its last one as last limit (stale). If a session hits the limit again within 30 minutes of account data clearing it, nid stops trusting account data for that limit until its reset time (also across restarts and if the provider extends the limit), so a wrong reading cannot loop.

nid limits <session> --clear also retries immediately after you change provider or account settings.