@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

main
md 210 lines 13.1 KB
Rendered Raw
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**.