Reference

Troubleshooting

Fixes for the problems people meet most often, from empty usage and missing CLIs to expired logins, usage limits, widgets, codz and Codz Remote.

Most problems in Codz come down to one of a few causes: macOS blocking access to your agents’ data, a provider tool that is missing or out of date, a login that expired, or a Mac that Codz Remote cannot reach. This page lists each problem with the words Codz shows you and the fix.

Two checks answer many questions at once. In the app, Settings ▸ General ▸ Re-run environment check ▸ Check now looks again for provider CLIs, local data and Full Disk Access. In a terminal, codz doctor shows what codz can read and which provider tools it finds.

First, check whether usage is locked rather than empty. If Codz says Tokens and cost are part of Codz Pro, or Usage is part of Codz Pro, this Mac is not signed in to a Pro account. Sign in under Settings ▸ Account. See Plans & pricing.

If you see zeros instead, macOS is probably blocking Codz from reading your agents’ data. Codz says so above Overview: macOS is blocking Codz from reading some agent data on this Mac. Click Fix, or:

Open System Settings ▸ Privacy & Security ▸ Full Disk Access.
Find Codz in the list and switch it on.
Come back to Codz. If it still cannot read your data, quit and reopen Codz; setup offers Relaunch Codz for this.

Codz reads the provider files already on your Mac. It doesn’t read your documents, and granting access uploads nothing.

If codz in Terminal shows your usage but the app shows zeros, it is the app that lacks Full Disk Access.

A provider isn’t found

Codz drives each agent through the provider’s own command-line tool. When it can’t find one, a chat on that provider shows Set up Claude (or the provider in question) with “Claude wasn’t found on this Mac.”, and Settings ▸ Models & providers marks the provider CLI missing. If you used a provider on this Mac before and its tool has gone, Codz also says, for example, Codex history is here, but its CLI isn’t on this Mac’s path. with Check setup.

For Claude Code, Codex and Cursor, click Install Claude (or the provider in question). Codz installs its own copy.
For OpenCode and DeepSeek, click Setup guide, install the tool, then check again.
If you installed a tool yourself and Codz still doesn’t see it, check where it lives. Codz looks in /usr/local/bin, /opt/homebrew/bin, ~/.local/bin, ~/.npm-global/bin, ~/.bun/bin and /usr/bin, and it also finds the copies the Cursor and ChatGPT apps keep.

After installing, run Settings ▸ General ▸ Re-run environment check. The providers’ install guides are Claude Code, Codex, Cursor and OpenCode. See Providers & logins.

A provider needs an update

In Settings ▸ Models & providers ▸ Provider status, Update available means a newer version is out, and Update needed means Codz needs a newer CLI than the one installed. For Claude Code, Codex and Cursor, click Update: Codz installs a separate version and keeps your existing installation.
If Codex refuses a model because it is too old, the chat says Codex needs an update, with “Update Codex, then retry this message.” Click Update Codex….
Codz won’t replace a CLI while a task on that provider is running, and says “Wait for the running Codex task to finish.”
If a new version misbehaves, Local CLI versions on the same page has Restore previous and Choose version….

When a provider login expires, the chat stops where it was and says, for example, “Your Claude login expired. Sign in again to continue.” A banner over the composer offers the fix:

Click Sign In. Your browser opens, and the banner says Finish signing in to Claude in your browser. Cancel stops the sign-in.
Sign in in the browser.
When the banner says You’re signed in to Claude again, click Try Again to resend the message that stopped.

If the banner says Claude couldn’t refresh its login instead, the login is fine: another Claude Code process was refreshing it. Wait a minute, then click Try Again.

Codz can also warn you before you send, with You’re not signed in to Claude. The sign-in banner covers Claude Code and Codex. For both, Settings ▸ Models & providers shows whether each login is Signed in or Not signed in, with Sign in or Sign in again beside it. See Providers & logins.

You hit a usage limit

When a provider refuses a turn because your plan is spent, the chat shows where it stopped, and a banner over the composer says You’re out of Claude usage (or Selected model is out of usage) with when it resets. If the provider names a page for more usage, the banner has Add Credits, Upgrade or Raise Limit.

With Continue on another provider on, which is the default, Codz moves the chat to the next ready model in your loadout and carries on where it stopped. Turn it off in Settings ▸ Agent & composer. See Plan limits and Models & loadout.

Cursor usage is missing

Cursor’s tokens and cost come from Cursor’s own usage records, for the account signed in to the Cursor app on this Mac. Without that sign-in, Codz shows Cursor’s context fill only and never invents a total. Open the Cursor app and sign in; Cursor tokens appear once it is signed in.

In the terminal, codz usage shows the same state as Cursor — Context only (account tokens unavailable).

Widgets show “as of” a time

Widgets don’t read your agents’ data themselves. They show a snapshot the Codz app writes, which stays current while Codz runs. When the snapshot is more than 15 minutes old, a widget adds “as of” and the time it was taken.

Open Codz to bring them up to date, and turn on Launch at login in Settings ▸ General to keep them current. A widget that says Open Codz to watch your agents. (or similar) has no snapshot yet. On the Free plan, Tokens Today says Tokens and cost are part of Codz Pro. See Menu bar & widgets.

codz isn’t found

If your shell says command not found: codz, the command hasn’t been linked, or ~/.local/bin isn’t on your PATH. Follow Set up the codz command, then open a new terminal window.

codz usage exits with code 3

codz usage prints “Token and cost history is part of Codz Pro. Sign in to Codz in Settings ▸ Account.” and exits with code 3 when this Mac isn’t on Pro.

codz reads the answer the Codz app last recorded. Open Codz, check that Settings ▸ Account shows your Pro plan, then run the command again. codz has to be a link to the Codz app’s binary; a copied binary can’t read the app’s answer. See What needs Pro.

Codz Remote doesn’t connect

Codz Remote needs your Mac to be running Codz and awake, with Allow connections on, signed in to the same Pro account as the phone, and at least one project approved. The Mac’s status is next to Allow connections in Settings ▸ Connections; it should read Online.

What you see	What to do
Allow connections is off in Settings ▸ Connections	Turn Allow connections on.
Codz Pro required	Sign the Mac in to your Pro account in Settings ▸ Account.
Mac offline, or “This Mac is offline. Commands are not queued.”	Wake the Mac and open Codz. Turn on Keep this Mac awake and Open Codz at login to keep it reachable.
No shared projects	Approve a folder under Projects your phone can use.
“That isn’t a Codz pairing code.”	Scan the code from Settings ▸ Connections ▸ Set up on your Mac.
“This code has expired.”	Show a new code on your Mac and scan it again.
“… hasn’t confirmed yet.”	Keep the code open on your Mac, or click Allow next to the phone in Settings ▸ Connections.
“Codz Pro is required to connect a Mac.”	Sign the phone in with the Pro account your Mac uses.
“This Mac was issued a new remote identity, so paired devices must be paired again.”	Connect each phone again with Set up.
“Face ID was not confirmed, so nothing was sent to your Mac.”	Try again and confirm with Face ID or your passcode.
“Live wake-up is unavailable; Remote is using recovery polling.”	Remote still works; updates can take longer to arrive.

See Codz Remote and Security.

Get help

Help and settings ▸ Help, at the bottom of the sidebar, opens these docs. If they don’t solve it, email support@codz.com with:

what you did and what Codz showed, word for word. The error line on Settings ▸ Connections can be selected and copied.
the output of codz --version.
your Device ID, from Settings ▸ Account ▸ Advanced.