1# Usage and limits
2
3Open **Usage** from the sidebar or the command palette, or press `mod+u` on web and
4desktop when the terminal is not focused. Customize `usage.open` in
5**Settings → Keybindings**.
6
7On mobile, choose **Usage** in the workspace navigation.
8
9## Understand your usage
10
11**Usage** combines Codex, Claude Code, Grok Build, OpenCode, Antigravity, Pi, Muse Code, and Cursor history
12from your connected environments. It shows token use, cache savings, model breakdowns, and estimated API-equivalent
13cost, split by token type and by speed. These estimates are not your subscription bill.
14**Premium** is what Fast and Ultrafast requests cost above standard rates. Cost that cannot be
15split, such as a provider-reported cost for a model without public rates, shows as **Other**.
16Select a model under **Breakdown** to see its trend, cache hit rate, and cost per million tokens.
17
18Totals depend on the history available on each server. Grok turns without a saved completed-turn
19record are missing from the totals.
20Text generation (thread titles, commit messages, PR text, branch names and review guides) is not in
21the totals for Codex or Claude Code 2.0.63 and newer, because those runs save no session history.
22
23OpenCode reads its SQLite database and older JSON history. Antigravity reads local conversation
24databases, including T3-managed profiles. Set `OPENCODE_DATA_DIR` or `ANTIGRAVITY_DATA_DIR` on the
25server to read a different data directory; comma-separated paths read multiple directories.
26
27Cursor reads account usage from Cursor's API for the account you signed in with in T3 or set as
28`CURSOR_API_KEY`. This includes headless T3 sessions and desktop usage across machines; the same
29account counts once across connected environments. T3 does not estimate missing tokens from
30conversation text.
31
32Usage includes each configured account's history, including disabled accounts. Custom homes follow
33the account's home setting or its `CODEX_HOME`, `CLAUDE_CONFIG_DIR`, or `GROK_HOME` environment
34variable. Pi reads `~/.pi/agent/sessions`, or the `sessions` directory under
35`PI_CODING_AGENT_DIR`. Set `PI_CODING_AGENT_SESSION_DIR` to read a different session directory.
36To include sessions saved through `--session-dir` or Pi's `sessionDir` setting, set this environment
37variable to the same directory. Pi includes recorded tool and summary costs under `Tools/summaries`.
38Muse Code reads native session history, including child sessions, from the home reported by the
39configured Muse CLI. Its environment settings, including `XDG_DATA_HOME`, apply. Models without
40known prices still contribute tokens and appear as unpriced; set custom prices to estimate their cost.
41Use absolute paths or `~/` paths in the account's environment settings; relative environment paths
42depend on each project's working directory and cannot be reliably discovered by Usage. Accounts
43sharing a history directory count once.
44
45The server saves its first hostname in `<T3 home>/usage-host-id`, so a recreated container keeps
46its usage identity when T3 home is persisted. Set `T3CODE_HOST_ID` to choose the identity
47explicitly.
48
49When your app and server support different providers, usage totals may cover only the providers
50your app understands. Update the app to include newly supported providers.
51
52On web and desktop, use the environment dropdown to filter costs, tokens, and limits. All
53environments are selected by default. The dropdown shows which environments are still scanning;
54results appear as each one responds, and figures still updating are dimmed. Cursor shows its last
55saved totals first, then updates them when Cursor's API responds.
56
57If recent work is missing or a new model shows no cost, refresh to rescan session history and
58update model pricing.
59
60## Set custom model prices
61
62On web or desktop, open the environment dropdown on **Usage**, then choose **Model prices** to add,
63edit, or reset a model's estimated price. **Apply to** starts with your current Usage filter;
64choose all environments or select individual destinations. Enter the exact model ID and USD
65rates per million input and output tokens. You can enter any model ID, including models
66without public pricing. When a model on **Usage** has no known price, select it under
67**Breakdown** and choose **Set price** to open this table with that model added.
68
69Cache read and cache write rates are optional and use the input rate when blank. Enter `0` for
70tokens that are free. Saved prices replace automatic pricing for all of that environment's
71history and are shared with clients connected to it. When environments have different prices,
72cells show **Mixed**. Edit rates directly in the table, then choose **Save changes** to apply all
73edited rows. Untouched cells keep each environment's rate. Select one environment to inspect its
74prices. **Reset to automatic** marks a model's override for removal when you save; you can undo
75it before saving.
76
77To count one model as another, such as a preview model under its released name, enter the target
78model ID under **Map to**. The mapped model no longer appears on **Usage**: its tokens and cost
79move to the target model and use the target's price. Clear **Map to** or reset the row to show
80the model on its own again.
81
82Each destination reports whether the change saved. Offline or unavailable environments are
83marked **Not saved**. Reconnect them and choose **Retry failed saves** to finish the same change
84without writing again to environments that already saved. Changes are not queued after you close
85the dialog.
86
87## Show only some models
88
89To count only some models, or to leave some out, add `usageModelFilter` to the server's
90`settings.json` in its `userdata` directory, such as `~/.t3/userdata/settings.json`:
91
93{
94 "usageModelFilter": {
95 "include": [{ "provider": "claude", "model": "orbit-1" }, { "model": "orbit-2" }],
96 "exclude": [{ "model": "drift-9" }]
97 }
98}
100
101`include` keeps only the listed models and `exclude` leaves the listed models out. `provider` is
102one of `claude`, `codex`, `cursor`, `grok`, `opencode`, `antigravity`, `pi`, or `muse`; omit it
103to match a model ID from any provider. Use the model ID that Usage shows without **Map to**, such
104as a provider-prefixed ID for Pi. Filters apply before **Map to**, so a model you leave out is not
105counted under its mapped name. Usage applies each environment's own filter. Remove the setting to
106show every model again.
107
108If the setting is invalid, Usage ignores it and shows every model, and the next save of any other
109setting removes it from `settings.json`.
110
111## Track subscription limits
112
113**Usage → Limits** pools every subscription account it can see per provider, so with several Codex
114or Claude accounts across your enabled environments and hubs you read one number per window rather than a
115list. Each window card shows how much of the pool is left and a bar with one segment per account,
116kept in the same column across windows. Accounts are ordered by their next 5-hour refill, soonest
117first. For an account with no weekly quota left, this is when its session becomes usable again.
118The first available window is used when no account reports a 5-hour limit. A gap means the
119account does not report that window. When the provider reports reset times, the card also says
120when the next reset lands and how much it hands back. The hatched
121part of a segment is what that reset restores. Tap a segment or account row for the account's plan,
122where it is signed in, and its reset time. On web, you can hover too. Codex and Claude accounts
123with banked reset credits show a ticket count and the **Use reset** action in the account details.
124Claude resets are not available when the server runs on macOS, where Claude keeps its login in the
125Keychain. On narrow screens, numbered rows below
126the bar show each account's quota, countdown, and credits. Tap a row to open its details.
127
128The same account signed in on more than one environment, or reported by a hub as well, counts once.
129Filter with the environment dropdown to see what a single machine has.
130
131When a Claude or Codex account has no overall weekly quota left, its pooled session contribution
132shows 0% left. The next refill depends on both reset times: an exhausted session must also reset,
133and a partly spent session may only regain its unused portion when the week resets. Missing or
134stale reset times have no refill estimate; refresh Limits for a new reading. Claude's
135model-specific weekly allowances keep their reported values.
136
137Opening Limits checks the selected connected environments automatically. Each client waits at
138least five minutes between automatic checks of an environment, including after a failed check.
139If a window still looks stale, refresh Limits to re-check every provider and hub.
140
141Pick `/usage-limits` from the composer's command menu, or send it as a message, to check the
142current model's limits without leaving the conversation. The result opens above the composer and
143closes when you dismiss it or send your next message. It uses the same snapshot as **Usage → Limits**, so it does not run the agent or refresh
144anything. The command is offered only for providers that appear under **Usage → Limits**.
145
146To keep them in view on web and desktop, turn on **Usage limits** in **Settings → Appearance → Thread details**, or right-click the thread details card.
147The bottom of the thread details card then shows how much is left in each limit window of the
148current provider account. Some windows, such as a weekly Opus limit, count only one model. Hover a
149row to see when it resets and your pace. Turn on **Context window** to also show the thread's
150context use against the model's limit. A tick on the bar marks where the provider compacts
151automatically, when it reports that point.
152
153On web and desktop, when the selected provider's session has less than 25% left, the composer says
154so, with the time until it resets and, when the pace so far would run it dry first, about when it
155runs out. **Switch to** moves the thread to another ready provider when the thread allows it.
156Dismissing the notice hides it until that window resets.
157
158OpenCode Go reports its session, weekly, and monthly allowance when OpenCode runs locally in
159the environment. T3 cannot report limits for external OpenCode servers because their credentials
160belong to the remote server. Limits need an OpenCode Go API key, or an OpenCode Console connected
161in OpenCode with an API key. A Console browser sign-in alone does not report them. You can also add
162your Go API key as `OPENCODE_API_KEY` in the OpenCode instance's **Environment variables**, then
163refresh provider status. Cursor reports
164its monthly allowance, including separate Auto and API usage, for `CURSOR_AUTH_TOKEN` when it is set,
165otherwise for the account you signed in with in T3 or set as `CURSOR_API_KEY`.
166Sign-in and API keys report limits only with Cursor's default API endpoint. If you configure a custom
167Cursor endpoint, use an explicit `CURSOR_AUTH_TOKEN` for limits.
168
169Grok reports the remaining subscription allowance and reset time for its current billing period
170after signing in with `grok login`. Explicit `XAI_API_KEY` connections and custom authentication
171or endpoint configurations do not report subscription limits.
172
173Muse Code reports its session and weekly windows and its tier once the Muse CLI has run in a thread.
174Until then it shows no limits. Readings are not kept across a server restart.
175
176API-key accounts may not report subscription limits. This also applies to Claude connections
177using a proxy through `ANTHROPIC_AUTH_TOKEN`.
178
179## Connect a CLIProxyAPI hub
180
181To see pooled accounts, open **Settings → Providers → Usage providers → Add hub**. Choose the
182environment that will connect to the hub and enter its URL and management key.
183
184The hub's Codex, Claude, xAI (shown as Grok) and Antigravity accounts appear under **Usage → Limits**;
185accounts for other providers are not read. Codex accounts show banked reset credits; select an
186account and choose **Use reset** to redeem one. No hub plugin is required.
187
188This connection supplies usage information; configure
189the provider separately to send agent requests through the hub. Remove the hub from the same
190settings section when you no longer need it.
191
192## Subscription usage widget
193
194Add **Subscription usage** from your iOS or Android widget gallery to see remaining Codex and
195Claude quotas. Tap it to open **Usage → Limits**; on Android this works while T3 is running in
196the background, otherwise open the app from the launcher. On iOS, use **Edit Widget** to choose
197Session, Weekly, or both for each provider. Reopen T3 to refresh expired readings.
198
199## Keyboard shortcuts
200
201On web and desktop, open Usage from the command palette. While on Usage,
202press `C`, `T`, or `L` for Cost, Tokens, or Limits while not typing in a field.
203Use `Ctrl+Shift+1/2/3/4` (`Cmd+Shift+1/2/3/4` on macOS) for the past
20424 hours, 7 days, 30 days, or 90 days. Period shortcuts do nothing on Limits.
205Press `Escape` to return to the previous page. Customize these shortcuts in
206**Settings → Keybindings**.