Claude Counter app icon

Setup Guide

Getting Started

Welcome to Claude Counter! This guide will help you set up the app and start tracking your Claude Code sessions in minutes.

Step 1: Download & Install

  1. Open the App Store on your iPhone or iPad
  2. Search for "Claude Counter"
  3. Tap Get to download and install
  4. Open the app once installation completes
Download on the App Store

Step 2: Choose Your Language

When you first open Claude Counter, you'll be asked to select your preferred language.

Available Languages:

  • English (UK)
  • English (US)
  • Afrikaans
  • Greek (Ελληνικά)
  • French (Français)
  • Spanish (Español)
  • German (Deutsch)
  • Dutch (Nederlands)
  • Chinese, Simplified (中文 简体)
  • Chinese, Traditional (中文 繁體)
  • Japanese (日本語)

Tap your preferred language to continue. You can change this later in Options.

Step 3: Connect Your Real Claude Usage (Mac)

This one-time step powers Claude Counter's most valuable features. Claude Code keeps a private log of your real usage on your Mac — connect it once and the app shows your live 5-hour session window, real token counts, estimated costs, and can sync your timers to the moment Claude actually resets.

On your Mac (one time)

Before you start: you need an Apple silicon Mac that you use Claude Code on — that is where the usage log lives — with iCloud Drive switched on (System Settings > your name > iCloud).

  1. Open the Mac App Store, search for Claude Counter, then click the iPhone & iPad Apps tab at the top of the results — it is an iPad app that runs on your Mac, so it is not listed under Mac apps. Install it
  2. Open the app and go to Tab 2 (Usage)
  3. Tap Grant Access
  4. In the folder window that opens, press Command+Shift+G, type ~/.claude, press Return, then click Open
  5. You'll know it worked when the Usage tab fills with your token counts, plus a live 5-hour countdown if you have messaged Claude Code in the last 5 hours. If it says "That folder has no Claude Code logs", tap Change Folder at the bottom of the tab and pick ~/.claude again

On your iPhone or iPad

  • Sign in to the same iCloud account as your Mac, with iCloud Drive switched on (Settings > your name > iCloud)
  • Open Tab 2 (Usage) and allow up to five minutes the first time — your Mac shares your usage privately through your own iCloud, and your iPhone picks it up on its own. Pull down on the Usage tab to check sooner
  • You'll know it worked when the bottom of the Usage tab shows From followed by your Mac's name and the time of its last update
  • Tip: keep Claude Counter running on your Mac while you work — it's what reads the logs, so your iPhone is only as current as the Mac app's last update. If you quit the Mac app, your iPhone keeps the last update until you open it again

Hands-Free Background Running (Optional)

The Mac app doesn't need its window open — it keeps reading your logs and updating your other devices while hidden. Two easy ways to make it fully hands-free:

  • Login Items: System Settings > General > Login Items & Extensions > add Claude Counter — it opens at login, and you can hide the window and forget it
  • Let Claude set it up for you: if you use Claude Code, paste this prompt into a session on your Mac and Claude will assist you with the setup:
Please help me set up the Claude Counter app to run hands-free in the background on this Mac, so it keeps my usage data fresh while hidden. Add a SessionStart hook to my ~/.claude/settings.json that runs the command: open -gja "Claude Counter" so the app launches hidden whenever I start a Claude Code session. Keep my existing settings intact, explain the change before you make it, and validate the JSON afterwards.

What This Unlocks

  • Live session window countdown on Tabs 1 and 2 — see exactly when Claude resets
  • Record & Sync — when a Claude window is already running, one tap records the session and lands your timers on the real reset time
  • Recent Windows & import — sessions you forgot to record can be added to your History with one tap
  • Estimated costs & Subscription Value — what your usage would cost at API pay-per-token rates, compared with what your plan costs
  • Model tracking — tag sessions with the Claude models you actually use

Privacy & Going Without a Mac

Your logs never leave your devices except through your own private iCloud — nothing is sent to us or anyone else. No Mac? No problem: manual session tracking works fully without this step, and you can connect a Mac later at any time.

Step 4: Understand Your Session Limits

Free Users

  • 5 sessions tracked included free
  • 1 grace session as a buffer before upgrade
  • Claude Counter session counts reset on the day that your Claude subscription renews each month (user configurable)

Pro Users

  • More sessions per month
  • Custom timers
  • Lock screen widgets
  • 2-week free trial on all plans

Step 5: Configure Your Timers

Navigate to Options (Tab 5) > Timer Settings to customize:

Session Duration Timer

  • Default: 5 hours (300 minutes)
  • Purpose: Tracks how long your Claude Code session runs
  • Recommendation: Set this to match Claude Code's session timeout

Save Progress Timer

  • Default: 4:45 hours (285 minutes)
  • Purpose: Reminds you to save your progress with Claude
  • Recommendation: Set this to a time that is less than your session duration based on your progress updating workflow

Step 6: Set Your Reset Day

Your session count resets monthly. This happens on the day of the month that you set in the Timer Settings for when your Claude subscription renews.

To change your reset day:

  1. Go to the Options (Tab 5)
  2. Tap Timer Settings
  3. Find Session Reset Day
  4. Select any day from 1-31

Step 7: Choose Your Theme

Claude Counter includes 15+ beautiful color themes.

  1. Go to Options (Tab 5)
  2. Tap Theme & Appearance
  3. Select your preferred theme:
    • System (follows iOS)
    • Blue, Purple, Green, Pink, Gold
    • Cobalt, Indigo, Dodger Blue
    • Orange, Red, Yellow
    • Gray, Black, Brown
  4. Choose Light, Dark, or System mode
  5. There are many combinations so take some time to find the theme that pleases you

Step 8: Set Up Lock Screen Widgets (Pro)

Lock screen widgets let you see session info without opening the app.

Adding Widgets

  1. Long-press on your Lock Screen
  2. Tap Customize
  3. Tap the Lock Screen to edit
  4. Tap the widget area (above or below the time)
  5. Search for Claude Counter
  6. Choose from available widgets:
    • Session Timer - Remaining session time
    • Save Progress - Time until save reminder
    • Sessions Remaining - Available sessions count
    • Days Remaining - Available days until your Claude subscription renews

Widget Refresh

Widgets update automatically when timers are running.

Step 9: Start Your First Session

You're ready to go! Here's how to start tracking:

Starting a Session

  1. Open Claude Counter to Tab 1 (Session)
  2. (Optional) Add a session description. Include any project or client tags to enable keyword filtering for data export
  3. (Optional) Pick the Claude model you'll be using — it's saved with the session
  4. Tap the large Start Session button
  5. Confirm you want to start a new session

With your Mac connected (Step 3): if a Claude window is already running when you open the app, it offers Record & Sync instead — accept, add a description, and your timers land on Claude's actual reset time. The window already counts as one of your sessions, so recording it just keeps your count accurate.

What Happens Next

  • Session Timer begins counting down
  • Save Progress Timer starts its countdown
  • Session count increments
  • Circular progress shows sessions used

During Your Session

  • Keep Claude Counter open or use widgets to monitor time
  • You'll receive a save reminder when your save timer target is reached
  • You'll receive a reminder when your session timer target is reached
  • Keep in mind that any instruction or response sent to Claude AI after a Claude session expires automatically starts a new session

Ending Your Session

  • Should you decide to stop working with Claude before the end of the session tap the button again to End Session
  • Confirm to stop all timers
  • Session time is saved to your history

Step 10: Review Your Statistics

After a few sessions, explore your statistics:

  1. Go to Tab 4 (Statistics)
  2. View your Quick Stats dashboard
  3. Scroll to see charts:
    • Usage by 7-day periods
    • Session duration by date
    • Usage by day of week
    • Sessions by hour
  4. Use the Period Filter to view:
    • Current period only
    • All time data
    • Specific period ranges

Step 11: Export Your Data

Need to report your usage or bill a client?

Quick Export

  1. Go to Tab 3 (History) or Tab 4 (Statistics)
  2. Tap the Export button
  3. Choose:
    • Copy to Clipboard - Formatted text
    • Share as CSV - For spreadsheets

What's Included

  • The user set developer ID
  • Session dates and times
  • Duration for each session
  • Session descriptions
  • Claude model used (when set)
  • Summary statistics
  • Period information

Pro Tip: Prevent Accidental Sessions

Claude Counter's confirmation dialogs help prevent wasted sessions:

  1. Start Session Confirmation - "Are you sure you want to start a new session?"
  2. End Session Confirmation - "This will stop all timers. Continue?"
  3. Session Cooldown - Brief wait period between sessions

These safeguards ensure you only start sessions when you intend to.

Upgrading to Pro

When you're ready for more features:

  1. Go to Options (Tab 5)
  2. Tap Subscription
  3. Choose Monthly ($0.99) or Annual ($9.99)
  4. Complete purchase

Pro Features Unlocked

  • More sessions per month
  • Custom timers
  • Lock screen widgets
  • All future Pro features

Troubleshooting

Sessions Not Counting

Ensure you tap "Start Session" and confirm

Widgets Not Updating

  • Widgets refresh periodically based on iOS
  • Try removing and re-adding the widget
  • Ensure the app has been opened recently

Timer Sounds Not Playing

  • Check your iPhone isn't on Silent mode
  • Verify notification permissions in iOS Settings

Usage Tab Waiting for Your Mac

  • Open Claude Counter on your Mac and grant folder access (Step 3) — the Mac's own Usage tab must show numbers before the iPhone can
  • Make sure both devices are signed in to the same iCloud account with iCloud Drive switched on
  • Allow up to five minutes for the first sync, then pull down on the Usage tab to refresh. Your iPhone only receives updates while the Mac app is running

"Access to the folder was lost" or "That folder has no Claude Code logs"

  • Access can be lost after reinstalling or updating the Mac app — tap Change Folder at the bottom of the Usage tab and pick ~/.claude again
  • "No Claude Code logs" means a different folder was chosen — it must be the hidden ~/.claude folder in your home folder. Press Command+Shift+G in the folder window and type it

"No Active Window" Showing

  • A window only appears once you've sent Claude Code a message — your next message starts a fresh 5-hour window
  • The Session and Usage tabs re-check every 30 seconds while open; the Usage tab's Refresh button checks immediately
  • On iPhone, the countdown is as fresh as your Mac's last update — open the Mac app to bring it current

Need More Help?

Visit: User Guide

Next Steps

Now that you're set up:

  1. Start tracking your Claude Code sessions
  2. Create custom timers for your workflow (Pro)
  3. Review statistics weekly to understand your patterns
  4. Export reports as needed for billing or management

Happy coding!

Need Help?

We're here if you have questions or run into any issues.

Full User Guide Product Page Contact Support