clover's git

the-knife

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	## Understand your usage
8
9	**Usage** combines Codex, Claude Code, Grok Build, OpenCode, Antigravity, Pi, and Cursor history
10	from your connected environments. It shows token use, cache savings, model breakdowns, and estimated API-equivalent
11	cost, split by token type and by speed. These estimates are not your subscription bill.
12	**Premium** is what Fast and Ultrafast requests cost above standard rates. Cost that cannot be
13	split, such as a provider-reported cost for a model without public rates, shows as **Other**.
14	Select a model under **Breakdown** to see its trend, cache hit rate, and cost per million tokens.
15
16	Totals depend on the history available on each server. Grok turns without a saved completed-turn
17	record are missing from the totals.
18
19	OpenCode reads its SQLite database and older JSON history. Antigravity reads local conversation
20	databases, including T3-managed profiles. Set `OPENCODE_DATA_DIR` or `ANTIGRAVITY_DATA_DIR` on the
21	server to read a different data directory; comma-separated paths read multiple directories.
22
23	Cursor reads account usage from Cursor's dashboard API using the CLI login saved on the server.
24	This includes headless T3 sessions and desktop usage across machines; the same account counts
25	once across connected environments. Without an accessible CLI login, T3 shows a
26	notice instead of incomplete local totals. T3 does not estimate missing tokens from conversation text.
27	On macOS, choose **Enable Cursor usage** on Usage to allow T3 to read your existing CLI login
28	from Keychain. You can turn it off in **Settings → Providers → Usage providers**. macOS may ask
29	you to allow access on the server Mac.
30
31	Usage includes each configured account's history, including disabled accounts. Custom homes follow
32	the account's home setting or its `CODEX_HOME`, `CLAUDE_CONFIG_DIR`, or `GROK_HOME` environment
33	variable. Pi reads `~/.pi/agent/sessions`, or the `sessions` directory under
34	`PI_CODING_AGENT_DIR`. Set `PI_CODING_AGENT_SESSION_DIR` to read a different session directory.
35	To include sessions saved through `--session-dir` or Pi's `sessionDir` setting, set this environment
36	variable to the same directory. Pi includes recorded tool and summary costs under `Tools/summaries`.
37	Use absolute paths or `~/` paths in the account's environment settings; relative environment paths
38	depend on each project's working directory and cannot be reliably discovered by Usage. Accounts
39	sharing a history directory count once.
40
41	When your app and server support different providers, usage totals may cover only the providers
42	your app understands. Update the app to include newly supported providers.
43
44	On web and desktop, use the environment dropdown to filter costs and tokens. All
45	environments are selected by default. The dropdown shows which environments are still scanning;
46	results appear as each one responds, and figures still updating are dimmed. Cursor shows its last
47	saved totals first, then updates them when Cursor's API responds.
48
49	If recent work is missing or a new model shows no cost, refresh to rescan session history and
50	update model pricing.
51
52	## Set custom model prices
53
54	On web or desktop, open the environment dropdown on **Usage**, then choose **Model prices** to add,
55	edit, or reset a model's estimated price. **Apply to** starts with your current Usage filter;
56	choose all environments or select individual destinations. Enter the exact model ID and USD
57	rates per million input and output tokens. You can enter any model ID, including models
58	without public pricing. When a model on **Usage** has no known price, select it under
59	**Breakdown** and choose **Set price** to open this table with that model added.
60
61	Cache read and cache write rates are optional and use the input rate when blank. Enter `0` for
62	tokens that are free. Saved prices replace automatic pricing for all of that environment's
63	history and are shared with clients connected to it. When environments have different prices,
64	cells show **Mixed**. Edit rates directly in the table, then choose **Save changes** to apply all
65	edited rows. Untouched cells keep each environment's rate. Select one environment to inspect its
66	prices. **Reset to automatic** marks a model's override for removal when you save; you can undo
67	it before saving.
68
69	To count one model as another, such as a preview model under its released name, enter the target
70	model ID under **Map to**. The mapped model no longer appears on **Usage**: its tokens and cost
71	move to the target model and use the target's price. Clear **Map to** or reset the row to show
72	the model on its own again.
73
74	Each destination reports whether the change saved. Offline or unavailable environments are
75	marked **Not saved**. Reconnect them and choose **Retry failed saves** to finish the same change
76	without writing again to environments that already saved. Changes are not queued after you close
77	the dialog.
78
79	## Track subscription limits
80
81	**On web and desktop**, hover the sidebar Usage button to inspect subscription
82	limits, or focus it and press Arrow Down.
83	Click it to open costs and tokens. Right-click it for usage reset settings and provider configuration.
84	**On mobile**, open **Usage → Limits**. The detailed limits view pools subscription accounts per
85	provider across your environments and hubs. Each window card shows how much of the pool is left
86	and a bar with one segment per account,
87	kept in the same column across windows. Accounts are ordered by their 5-hour reset, soonest
88	first, or by the first available window when no account reports a 5-hour limit. A gap means the
89	account does not report that window. When the provider reports reset times, the card also says
90	when the next reset lands and how much it hands back. The hatched
91	part of a segment is what that reset restores. Tap a segment or account row for the account's plan,
92	where it is signed in, and its reset time. On web, you can hover too. Codex and Claude accounts
93	with banked reset credits show a ticket count and the **Use reset** action in the account details.
94	Claude resets are not available when the server runs on macOS, where Claude keeps its login in the
95	Keychain. On narrow screens, numbered rows below
96	the bar show each account's quota, countdown, and credits. Tap a row to open its details.
97
98	The same account signed in on more than one environment, or reported by a hub as well, counts once.
99	On mobile, filter with the environment dropdown to see what a single machine has.
100
101	Opening the detailed limits view checks connected environments automatically. Each client waits at
102	least five minutes between automatic checks of an environment, including after a failed check.
103	If a window still looks stale, refresh the limits view to re-check every provider and hub.
104
105	Pick `/usage-limits` from the composer's command menu, or send it as a message, to check the
106	current model's limits without leaving the conversation. The result opens above the composer and
107	closes when you dismiss it or send your next message. It uses the same limits snapshot, so it does
108	not run the agent or refresh anything. The command is offered only for providers reporting limits.
109
110	OpenCode Go reports its session, weekly, and monthly allowance when OpenCode runs locally in
111	the environment. T3 cannot report limits for external OpenCode servers because their credentials
112	belong to the remote server. Limits need an OpenCode Go API key. A Console sign-in alone
113	does not report them. Add your Go API key as `OPENCODE_API_KEY` in the OpenCode instance's
114	**Environment variables**, then refresh provider status. Cursor reports
115	its monthly allowance, including separate Auto and API usage, using the CLI login or
116	`CURSOR_AUTH_TOKEN`. On macOS, this includes the default Keychain login after you enable Cursor
117	usage. Keychain login is used for limits only with Cursor's default API endpoint. If you configure
118	a custom Cursor endpoint, use an explicit token or file-based CLI login for limits.
119
120	Grok reports the remaining subscription allowance and reset time for its current billing period
121	after signing in with `grok login`. Explicit `XAI_API_KEY` connections and custom authentication
122	or endpoint configurations do not report subscription limits.
123
124	API-key accounts may not report subscription limits. This also applies to Claude connections
125	using a proxy through `ANTHROPIC_AUTH_TOKEN`.
126
127	## Connect a CLIProxyAPI hub
128
129	To see pooled accounts, open **Settings → Providers → Usage providers → Add hub**. Choose the
130	environment that will connect to the hub and enter its URL and management key.
131
132	The accounts appear in the detailed limits view. Codex accounts show banked reset credits; select an
133	account and choose **Use reset** to redeem one. No hub plugin is required.
134
135	This connection supplies usage information; configure
136	the provider separately to send agent requests through the hub. Remove the hub from the same
137	settings section when you no longer need it.
138
139	## Subscription usage widget
140
141	Add **Subscription usage** from your iOS or Android widget gallery to see remaining Codex and
142	Claude quotas. Tap it to open **Usage → Limits**; on Android this works while T3 is running in
143	the background, otherwise open the app from the launcher. On iOS, use **Edit Widget** to choose
144	Session, Weekly, or both for each provider. Reopen T3 to refresh expired readings.
145
146	## Keyboard shortcuts
147
148	On web and desktop, open Usage from the command palette. While on Usage,
149	press `C` or `T` for Cost or Tokens while not typing in a field.
150	Use `Ctrl+Shift+1/2/3/4` (`Cmd+Shift+1/2/3/4` on macOS) for the past
151	24 hours, 7 days, 30 days, or 90 days.
152	Press `Escape` to return to the previous page. Customize these shortcuts in
153	**Settings → Keybindings**.