Know how much time you're
spending in Claude.

We're all spending more time on Claude Code. But where do the hours actually go? This is a status bar that helps you keep tabs on your time across every session, so you always know where your day stands before you hit a rate limit or burn through your hours.

Install in 2 minutes View source

Runs locally · Zero API tokens consumed · macOS & Linux · Built on Claude Code's official status line

you@~/claude-statusline-timer $ claude
...working with Claude...
[Opus 4.7 (1M context)] 📁 claude-statusline-timer | 🌿 main | This Session: 00h 47m 23s (API: 08m 15s)
███░░░░░░░ 28% ctx | All Sessions: 3 today (since 9:42am) | Today: 02h 15m | Wall: 03h 02m | Active: 24m | Week: 14h 38m
Limit (5hr): 47% used, resets in 2h 38m | Limit (7day): 12% used, resets in 4d 12h

Why I made this

I use Claude Code every day. I'd get heads down on a problem, and hours would fly by before I came up for air. Sometimes that meant hitting a rate limit mid-task. Sometimes it meant looking up and realizing the day was already gone.

I wanted a time buddy right there in the terminal where I work. Something quietly keeping tabs on every session across the day, so I always knew where I stood before I burned through my hours.

So I wrote one.

Rob (rkrevolution)

Four problems it fixes

The moments that made me build this. Probably the reason you're here too.

✕ problem

Rate limits arrive without warning

You're in flow, then Claude refuses to respond. You don't know when it'll come back. Your momentum is gone.

✕ problem

Parallel agents, muddled totals

Running Claude across git worktrees, spawning subagents, or just juggling two terminals? Normal timers count the overlap twice. You can't tell if you've burned one hour or three.

✕ problem

"How long have I been here?"

A simple question with no honest answer. Walking away for an hour shouldn't count the same as actively coding, but most timers say it does.

✕ problem

No view of the whole week

The 7-day rate limit is real, but nothing warns you about it until you're already bumping into it.

Every field, explained

This is exactly what you see in your terminal. Hover a highlighted field, or the numbered entry below, to see what it tells you.

The layout

[1Opus 4.7 (1M context)] 📁 2claude-statusline-timer | 🌿 3main | 4This Session: 00h 01m 13s 5(API: 00m 30s)
6░░░░░░░░░░ 3% ctx | 7All Sessions: 1 today (since 2:37pm) | 8Today: 00h 01m | 9Wall: 00h 01m | 10Active: 0m | 11Week: 05h 16m
12Limit (5hr): 0% used, resets in 4h 51m | 13Limit (7day): 0% used, resets in 1d 23h
Line 1 · Session info
1
Model
Which Claude model this session is running. Useful when you juggle Opus for hard problems and Sonnet/Haiku for cheap grunt work, so you always know which one just cost you.
2
📁 Working directory
The folder Claude Code is pointed at. Critical when you have three terminals open in three repos.
3
🌿 Git branch
Current branch, cached per repo so it stays fast even in large repositories.
4
This Session
Wall-clock time since you opened this specific Claude Code window. Starts ticking on your first message.
5
API time in this session
Of that session duration, this is the slice Claude actually spent thinking and generating. The gap between the two is you reading, typing, and thinking.
Line 2 · Your day's usage
6
Context window usage
How full the current context is. Green when you have room, yellow when filling, red when you're about to need /compact.
7
All Sessions today
How many Claude Code windows you've opened today, and when the first one started. A quick pulse of how distributed your day has been.
8
Today (the real total)
The honest answer to "how long was I with Claude today." Parallel sessions are combined into one. Time after you walked away doesn't count, because the clock only advances when Claude responds.
9
Wall (raw total)
Raw sum of every session's duration, with no merging. If Wall is bigger than Today, it means two or more sessions overlapped and the merge worked. A sanity check.
10
Active (API time)
Sum of time Claude actually spent processing across every session today. The rest was you typing or thinking.
11
Week
Rolling 7-day total, merged the same way as Today. Early warning system for the weekly rate limit.
Line 3 · Rate limits
12
Limit (5hr) (subscription only)
The one to watch. Your short-term budget. When it hits ~100%, Claude rate-limits you. The reset timer tells you exactly when you can pick back up.
13
Limit (7day) (subscription only)
Weekly budget. Matters for sustained heavy usage over multiple days. API users see a Cost: $X.XX field here instead.

The logic behind it

No server. No telemetry. No API tokens consumed. Just four ideas working together, built on Claude Code's official status line.

Idea 1

Claude Code already sends everything you need

After every message, Claude Code runs your status line script and pipes in a JSON blob with the session ID, current model, context usage, cost, and your rate limits. That's all first-party. The script just reads what's there and formats it into something you can use at a glance.

Idea 2

One timestamp per session, and "end" keeps moving

Every Claude Code window is a session. The script records the moment it started, then pushes its end time forward to now every time Claude responds. If you walk away for an hour, the clock stops advancing. That's why idle time gets trimmed out of your daily total.

Idea 3

Overlapping sessions get merged into one honest interval

Run Claude across git worktrees, fan out parallel subagents, or just have two terminals open? Their time ranges get combined into a single merged interval. One hour of overlap counts as one hour, not two. That's what makes "Today" an honest number instead of an inflated one.

Idea 4

Everything lives on your machine

The whole system is one bash script reading from stdin and writing to stdout. Session data is saved to a local JSON file per day and auto-cleaned after 30 days. No network calls, no accounts, no tokens consumed. Per the official docs: "The status line runs locally and does not consume API tokens."

The key insight: "how long?" isn't one number

Most timers pick one definition and hide the rest. This one shows three, because each answers a different question, and together they tell the truth.

Dimension What it answers Same scenario: 2 concurrent sessions, 1–3pm
Today "How long was I really with Claude?" Parallel sessions combined into one. Time after you walked away doesn't count. 2h (the honest answer)
Wall "Sum of every session." The raw total, before merging. If Wall is bigger than Today, parallel sessions overlapped. 3h (what a normal timer would show)
Active "How long was Claude actually thinking?" Just the time Claude spent responding, not you typing. 25m (the rest was you)

Install in 2 minutes

One shell script, one settings tweak, done. Everything runs locally on your machine.

Before you start, you'll need
  • Claude Code installed and working (claude.com/code)
  • macOS or Linux (the script is bash)
  • jq (see step 1 below to install it)
  • A Claude.ai Pro/Max subscription to see rate-limit fields. API users see a daily Cost: $X.XX field instead.

Install jq

Used to parse the JSON Claude Code pipes in.

# macOS
brew install jq

# Linux
sudo apt install jq

Download the script

Drop it in your Claude Code config directory and make it executable.

curl -o ~/.claude/ultimate-timer.sh \
  https://raw.githubusercontent.com/rkrevolution/claude-statusline-timer/main/ultimate-timer.sh
chmod +x ~/.claude/ultimate-timer.sh

Wire it into Claude Code

Edit ~/.claude/settings.json and add the statusLine key alongside your existing settings.

{
  "statusLine": {
    "type": "command",
    "command": "bash ~/.claude/ultimate-timer.sh"
  }
}

Launch Claude Code

The status bar appears at the bottom after your first message. That's it.

claude
Full docs on GitHub →