Claude Counter app icon

Claude Counter User Guide

Complete Reference Manual

This guide covers every feature in Claude Counter. Use the table of contents to jump to specific sections.

Tab 1: Session

The Session tab is your main dashboard for tracking Claude Code sessions.

Session Display

Circular Progress Indicator

  • Shows sessions used vs. total available
  • Color fills as you use more sessions
  • Center displays current count

Sessions Information

  • Used: Number of sessions started this period
  • Remaining: Sessions still available
  • Days Left: Days until your session count resets

Session Timers

Session Duration Timer

  • Tracks total time for your current session
  • Counts down from your configured duration (default: 5 hours)
  • Progress bar shows remaining time visually
  • States: Running, Paused, Stopped

Save Progress Timer

  • Independent countdown for save reminders
  • Default: 4:45 hours

Starting a Session

  1. Tap the Start Session button
  2. A sheet opens: add a description (optional) and pick the model you'll work in (optional)
  3. Tap Start Session in the sheet — or Cancel (or swipe the sheet away) to abort
  4. Both timers begin counting down

Session Descriptions

  • Enter the description in the start sheet when the session begins
  • While a session is running, an editable description field appears on the Session tab for mid-session notes
  • Use it for project names, task descriptions, or client references
  • Descriptions are saved with your session history and can be edited later from the History tab
  • Searchable in the History tab

During a Session

Status Indicators

  • Green border = Active session
  • Timer badges show state
  • Progress bars update in real-time

Ending a Session

  1. Tap the End Session button
  2. Confirm: "This will stop the current session and all timers"
  3. Session is saved to history with:
    • Start time
    • End time
    • Total duration
    • Your description

Custom Timers Section (Pro)

Pinned custom timers are displayed below the main timers on Tab 1.

Session Limits & Alerts

Free Tier Limits

  • 5 sessions
  • 1 grace session (6th session with warning)
  • After grace session: upgrade required

Tab 2: Usage

The Usage tab is a live dashboard of your real Claude Code usage — read straight from the session logs Claude Code keeps on your Mac. No manual tracking: your actual tokens, sessions, estimated costs, and the live 5-hour window countdown, all updating automatically.

How It Works

  • Claude Code keeps a private log of every session in the ~/.claude folder on your Mac
  • Claude Counter on your Mac reads those logs locally and builds the dashboard
  • Your iPhone and iPad receive the same dashboard through your private iCloud
  • Nothing leaves your own devices and iCloud account — no servers, no third parties

Setting Up on Your Mac

  1. Open Claude Counter on your Mac and go to the Usage tab
  2. Tap Grant Access
  3. In the folder window that opens: press Command+Shift+G, type ~/.claude, press Return, then click Open

That's a one-time step. You'll know it worked when the Usage tab fills with your token counts. The dashboard then refreshes itself every 30 seconds while the app is running, and you can pull down to refresh at any moment. If the tab says "That folder has no Claude Code logs", tap Change Folder at the bottom and pick ~/.claude again.

On iPhone & iPad

  • Sign in to the same iCloud account as your Mac, with iCloud Drive switched on — the Usage tab and the Claude Usage widget fill in automatically
  • Allow up to five minutes for the first sync, and pull down on the Usage tab to check sooner. You'll know it worked when the bottom of the tab shows From followed by your Mac's name and the time of its last update
  • The Mac app must be running for your other devices to get fresh data — its window can stay closed or hidden (see Hands-Free Mac Companion under Tips)
  • Requires a Mac with Apple silicon

Dashboard Cards

  • Session Window: live countdown to the current 5-hour window reset, with the number of responses in this window
  • Claude Session Windows: your recent windows — sync your Session-tab timers to the real window, or add unsaved windows to your History (each one you add counts against your remaining sessions). When you record a window you can give it a description and model, and both stay editable later from History
  • Today: input, output, and cache tokens plus responses for the day
  • Estimated Cost: today, last 7 days, and last 30 days priced at Claude API pay-per-token rates
  • Subscription Value: what your last 30 days would have cost at API rates — tap the pencil to enter your plan price and see what your subscription saved you
  • Totals & Last 7 Days: 7 and 30-day token totals with a day-by-day breakdown
  • By Model / By Project: where your tokens actually go

Note: cost figures are estimates at pay-per-token rates — on a subscription your actual cost may be lower. Cost estimates and Subscription Value are Pro features once the free trial sessions are used.

Tab 3: Timers

The Timers tab provides full management of custom timers (Pro feature).

Timer List

Viewing Timers

  • All custom timers displayed in a list
  • Each shows: Name, Duration, Current State
  • Progress bars for running timers
  • Pinned timers appear at top

Creating Timers

  1. Tap Add Timer or +
  2. Enter timer name (e.g., "Pomodoro", "Stand-up", "Client Call")
  3. Set duration using the time picker
  4. Tap Save
  5. Tap the pin of a timer to display the timer below the main timers on Tab 1

Timer Ideas

  • Pomodoro: 25 minutes work, 5 minutes break
  • Stand-up Meeting: 15 minutes
  • Code Review: 30 minutes
  • Deep Work Block: 90 minutes

Timer Controls

For Each Timer

  • Play/Pause: Start or pause the timer
  • Reset: Return to full duration
  • Edit: Change name or duration
  • Delete: Remove the timer

Timer States

  • Idle: Not started, shows full duration
  • Running: Actively counting down
  • Paused: Stopped mid-countdown
  • Completed: Reached zero

Pro Feature Lock

Free Users See

  • "Pro Feature" badge
  • Feature description
  • Upgrade button
  • No access to timer creation

Tab 4: History & Statistics

Tab 4 combines History and Statistics in one place — switch between them with the selector at the top of the tab. The History view shows all your session records.

Session List

Each Session Card Shows

  • Session number (#1, #2, etc.)
  • Date and time range
  • Total duration (formatted as Xh Xm)
  • Description (if provided)
  • Model badge (when a model was recorded)
  • Active indicator (green border for current session)

Filtering Sessions

Period Filter

  • Current Period: This month's sessions only
  • All Periods: Complete history
  • Select Periods: Select specific period ranges

Period Selector

  • Tap to open period selection sheet
  • See all archived periods
  • Select multiple periods to combine

Sorting Sessions

Tap the Sort button to order by:

  • Date (Newest): Most recent first
  • Date (Oldest): Earliest first
  • Duration (Longest): Longest sessions first
  • Duration (Shortest): Quickest sessions first
  • Description (A-Z): Alphabetical
  • Description (Z-A): Reverse alphabetical

Searching Sessions

  1. Use the search bar at top
  2. Search by:
    • Description text
    • Date

Session Actions

Edit a Session

  • Tap Edit on any saved session — including Claude windows you imported
  • Change the description and the model, then tap Save

Delete a Session

  • Tap Delete
  • Confirm deletion

Note: Deleted sessions cannot be recovered. The currently running session can't be edited or deleted here — manage it on the Session tab.

Exporting History

  1. Tap the Export button
  2. Choose export method:
    • Copy to Clipboard: Formatted text report for pasting
    • Share as Text: Text format
    • Share as CSV: Spreadsheet format

Export Includes

  • Report header with generation date
  • Period information
  • All session records with:
    • Session number
    • Developer ID
    • Date and time
    • Duration
    • Description

Statistics View

Switch the selector at the top of Tab 4 to Statistics for analytics and insights about your sessions.

Period Filter

Located at the top of the Statistics tab.

Filter Options

  • Current Period: This month only
  • All: Complete history
  • Select Periods: Select specific period ranges

Display Shows

  • Selected period range (e.g., "Periods 1 - 13")
  • Total session count for selection

Quick Stats Dashboard

Row 1

  • Sessions Remaining: Total for period
  • Days Remaining: Until period reset

Row 2

  • Sessions Today: Count for current day
  • Sessions This Week: Count for current 7 days

Row 3

  • Sessions Used: Total for period
  • Total Time Last 7 Days: Formatted as Xh Xm

Row 4

  • Total Time This Period: Complete duration
  • Avg Duration: Average session length

Charts

Usage by Seven Days

  • Bar chart showing 7-day period totals
  • Y-axis: Duration in minutes
  • X-axis: Period dates (adaptive labels)
  • Purple gradient bars

Session Duration by Date

  • Daily session totals
  • Individual days with activity
  • Blue gradient bars
  • Shows actual session dates only

Usage by Day of Week

  • Mon through Sun breakdown
  • Identifies your most productive days
  • Orange gradient bars

Sessions by Hour of Day

  • 24-hour distribution
  • Shows when you typically work
  • Identifies peak coding hours
  • Green gradient bars

Insights Section

Longest Session

  • Your longest single session
  • Duration displayed

Most Productive Day

  • Date with most sessions
  • Session count shown

Average Duration

  • Mean session length
  • Across all sessions in filter

Exporting Statistics

  1. Tap Export Statistics
  2. Choose method:
    • Copy to Clipboard: Formatted text report for pasting
    • Share as Text: Text format
    • Share as CSV: Spreadsheet format

Text Export Includes

  • Quick stats summary
  • Period information
  • Key metrics

CSV Export Includes

  • Session data in columns
  • Session Number, Developer ID, Date, Time, Duration, Description
  • Ready for Excel, Numbers, or Google Sheets

Tab 5: Options

The Options tab contains all the settings and customization.

Subscription Section

For Free Users

  • Shows "Free" status
  • Upgrade to Pro button
  • Tap to subscribe

For Pro Users

  • Shows "Pro" with crown icon
  • Subscription management link
  • View renewal date
  • Manage via App Store

Appearance

Theme Selection

Choose from 15+ themes:

  • System (follows iOS)
  • Blue, Purple, Green, Pink
  • Gold, Orange, Red, Yellow
  • Cobalt, Indigo, Dodger Blue
  • Gray, Black, Brown

Mode Selection

  • Light: Always light appearance
  • Dark: Always dark appearance
  • System: Follows iOS setting
  • Custom: Full theme customization

Timer Settings

Developer ID

  • Default: #1
  • Unique identifier for enterprise reporting
  • Included in all session exports (Tab 3 and Tab 4)
  • Set once, applied to all future sessions
  • Tap to expand and edit the ID

Session Duration

  • Default: 5 hours (300 minutes)
  • Set to match Claude Code session length
  • Range: 1 minute to 24 hours

Save Progress Timer

  • Default: 4:45 hours (285 minutes)
  • Reminder to update Claude work progress
  • Range: 1 minute to session duration

Session Reset Day

  • Default: 1st of month
  • Select any day (1-31)
  • Aligns with your monthly billing cycle

Language

Available Languages

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

Changing Language

  1. Select language
  2. App immediately updates

Information Links

  • About: App version and credits
  • Product Page: Marketing website
  • Setup Guide: Getting started help
  • User Guide: This document
  • Terms of Service: Legal terms
  • Privacy Policy: Data handling

Widgets

Home Screen and Lock Screen widgets provide at-a-glance information (Pro feature).

Available Widgets

Sessions Remaining

  • Number of sessions available
  • Updates after each session
  • Shows limit context

Days Remaining

  • Days until your session counter resets
  • Shows next reset date
  • Progress ring shows period elapsed

Session Timer

  • Shows remaining session time
  • Updates during active sessions
  • Displays paused state when paused

Save Progress Timer

  • Countdown to save reminder
  • Independent of session timer
  • Shows remaining minutes

Active Timer

  • Tracks your running custom timers at a glance
  • Shows the timer name and remaining time

Claude Usage

  • Live 5-hour window countdown and today's real token usage
  • Fed by the Usage tab — needs the Mac companion set up (see Tab 2: Usage)

Adding Widgets

  1. Long-press Lock Screen
  2. Tap Customize
  3. Select Lock Screen
  4. Tap widget area
  5. Scroll down to "Claude Counter"
  6. Tap on "Claude Counter"
  7. Initially swipe left to view the widgets one by one
  8. Tap and hold the widget you want to add and then drag it to the widget area
  9. For the Sessions Left and Days Until Reset tracking the circular widgets are popular
  10. For the Next Session and Save Progress tracking the smaller square widgets are popular
  11. Popular widget order: Next Session, Save Progress, Sessions Left, Days Until Reset
  12. Tap Done

Widget Behavior

Active Timers

  • Update every minute
  • Show live countdown

Subscription

Free Tier

Includes

  • 6 sessions per month (5 + 1 grace session)
  • Session tracking & timers
  • Real usage dashboard with cost estimates while your trial sessions last
  • History & statistics
  • Data export

Pro Tier

Includes everything in Free, plus

  • 50 sessions per month
  • Custom timers
  • Cost estimates & Subscription Value beyond the trial
  • Home Screen and Lock Screen widgets
  • All future Pro features

Pricing

  • Pro 1 Month: $0.99/month
  • Pro 1 Year: $9.99/year (best value)

New subscribers get a 2-week free trial. Prices may vary by region.

Subscribing

  1. Go to Settings > Subscription
  2. Tap Upgrade to Pro
  3. Select Monthly or Annual
  4. Tap Subscribe Now
  5. Confirm
  6. Pro features unlock immediately

Managing Subscription

  1. Go to Settings > Subscription
  2. Tap Manage Subscription
  3. Opens App Store subscription settings
  4. Change plan or cancel

Restoring Purchases

If you reinstall or switch devices:

  1. Go to Settings > Subscription
  2. Tap Restore Purchases
  3. Sign in with Apple ID if prompted
  4. Pro status restores automatically

Tips & Best Practices

For Individual Developers

  1. Give each session a description and model in the start sheet
  2. Add descriptions to track what you worked on
  3. Review weekly stats to understand your patterns
  4. Use save timer to commit progress before session ends
  5. Create custom timers for your workflow

For Employees

  1. Set Developer ID in Timer Settings for team reporting
  2. Tag sessions with project codes
  3. Export weekly for management reports
  4. Use period filtering for monthly summaries
  5. Track time consistently for accurate reporting

For Contractors

  1. Description = Client/Project for billing
  2. Export CSV for invoicing

Hands-Free Mac Companion

Your iPhone's live usage data is only as fresh as the Claude Counter app on your Mac, but the Mac app doesn't need its window open — it keeps reading your logs and updating your other devices while hidden. Two ways to make it fully hands-free:

  • Login Items: add Claude Counter in System Settings > General > Login Items — it opens at login and you can hide it and forget it
  • Claude Code power users: add a SessionStart hook to ~/.claude/settings.json so the app launches hidden every time you start a Claude Code session:
"hooks": {
  "SessionStart": [
    { "hooks": [ { "type": "command",
        "command": "open -gja \"Claude Counter\" 2>/dev/null || true",
        "async": true } ] }
  ]
}

The -gja flags open the app hidden, in the background, without taking focus. There's no need to quit it when you stop — leaving it running keeps your widgets and iPhone up to date.

Timer Strategies

Pomodoro Technique

  • Create 25-minute work timer
  • Create 5-minute break timer
  • Alternate for focused productivity

Deep Work Blocks

  • Create 90-minute timer
  • No interruptions during block
  • Review progress after

Meeting Timers

  • Stand-up: 15 minutes
  • 1:1: 30 minutes
  • Planning: 60 minutes

FAQ

Sessions

Q: What counts as a tracked session?

A: Each time you tap "Start Session" and start it from the sheet, one session is used.

Q: What's the grace session?

A: After using 5 free sessions, you get 1 additional session before needing to upgrade.

Q: When do sessions reset?

A: On your configured reset day (default: 1st of month).

Timers

Q: Why two timers?

A: Session timer tracks total time; save timer reminds you to commit work or update Claude progress.

Q: Can I change timer durations mid-session?

A: Changes apply to new sessions, not the current one.

Q: Do timers run in the background?

A: Yes, timers continue when the app is backgrounded.

Usage Dashboard

Q: Why is my Usage tab empty on my iPhone or iPad?

A: The data comes from Claude Counter on your Mac. Open the Mac app once, grant it access to your ~/.claude folder, and leave it running (its window can stay closed) — your other devices on the same iCloud account then update automatically.

Q: Do my tokens or code ever leave my devices?

A: No. Your Mac reads the Claude Code logs locally, and the dashboard travels to your other devices only through your own private iCloud. Nothing is sent to us or to any third party.

Data

Q: Where is my data stored?

A: On your device. Usage dashboard data also syncs between your own devices through your private iCloud — never through anyone else's servers.

Q: Can I backup my data?

A: Data is included in iOS backups.

Q: What happens if I delete the app?

A: All session data is permanently deleted.

Subscription

Q: Can I try Pro for free?

A: The free tier lets you evaluate the app. Upgrade when ready.

Q: Can I downgrade from Pro?

A: Cancel subscription; you keep Pro until period ends, then revert to Free.

Q: Do I lose data if I downgrade?

A: No, data is retained. Access to some features becomes limited.

Getting Help

Website

https://solosoftware.app/claude-counter/

Last Updated: August 2026
Claude Counter Version 26.6

Still Need Help?

Can't find what you're looking for? We're here to assist!

Setup Guide Product Page Contact Support