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