Set up Cost Doctor

Cost Doctor needs almost no setup. Install it, open it, and your Claude Code and Codex sessions appear. Two extras take one click each: Claude Code plan limits and phone alerts.

1. Install

1. Open the file you downloaded, CostDoctor.dmg.
2. Drag Cost Doctor onto the Applications folder.
3. Open Cost Doctor from Applications. An orange cross appears in the menu bar at the top right of the screen.
4. When macOS asks whether Cost Doctor may send notifications, choose Allow. That is how it tells you about a failed check when you are in another app.

It runs on macOS 13 or later, on Apple silicon and Intel Macs. The 14-day free trial starts the first time you open it. No account is needed.

2. Claude Code

Tokens, cost and sessions need no setup. Claude Code already keeps a log of every session in ~/.claude/projects on your Mac. Cost Doctor reads those files. It works the same whether you use Claude Code in a terminal or in the desktop app. Nothing is uploaded.

Plan limits need one click. Click the orange cross, find Claude Code limits are not connected under Plan limits, click Connect, then Connect now. Cost Doctor uses the Claude sign-in already saved on your Mac to ask Anthropic how much of your 5-hour and weekly limits is used. The sign-in is sent only to Anthropic.

If you mostly use the desktop app, the saved sign-in can go out of date after a few hours and the reading stops updating. To prevent that, open Settings in the dropdown and tick Renew the saved Claude sign-in when it expires.

3. Codex

Nothing to set up. Codex keeps its logs in ~/.codex/sessions, and it writes your plan limits into those same logs. Cost Doctor reads both, so Codex sessions and limits appear automatically after your next Codex reply.

4. Red alerts for failed checks

Cost Doctor watches three things and turns the menu bar and a frame around the screen red when one fails:

• Sessions that stopped on a failure, such as a failed test run or a refused push. No setup.
• Pull request checks on GitHub. This needs GitHub's command line tool, gh, installed and signed in. If you already use gh, it works. If not, install it from cli.github.com and run gh auth login once.
• Your own scripts. Any script can raise the alert by writing a file:

  echo "deploy failed" > ~/.costdoctor/alerts/deploy.txt

Every alert has a Dismiss button, and the red frame never blocks clicks.

5. Alerts on your phone (optional)

1. Open Settings in the dropdown and find Phone alerts.
2. Paste an address that accepts messages: an ntfy topic such as https://ntfy.sh/your-topic, a Slack or Discord webhook, or any address that takes a JSON post.
3. Click Send test. A message should arrive within a few seconds.

6. Make it yours

• Tick Start Cost Doctor when I log in so it is always there.
• In Settings you can change when it says "compact now", your daily token budget, the limit warning, and what the menu bar shows.

Entering your licence

After you buy, the confirmation page shows your licence key. Copy it, click the orange cross, choose Enter licence, paste the key and click Activate. The link to that page always shows the key again, so keep it.

If something looks wrong