Sundial · 日晷

English · 简体中文

A small sun that sits on your desktop, showing live Claude Code session activity
and how much of your usage allowance is left. macOS and Windows.

A subscription is not required. The session half reads local files, so it
works the moment you install it; only the two usage dials need Claude Max or Pro.

An unofficial personal project. It is not affiliated with Anthropic, nor
endorsed or supported by them. The usage half depends on an undocumented
endpoint and may stop working at any time — see Please read this first.

Written with Claude Code, reviewed and tested by a human.

_{Left: light mode · Right: dark mode (follows the system setting)
Dozing → expand on hover → a session begins → the rays reach towards the cursor → left alone, the dials pull and push the rays into a slow breath → finished, unread → folded away}

_{With nothing running, the gravity reverses: the sleeping sun shies away from the cursor rather than reaching for it — rays drawn in on the near side, pushed out on the far side.}

Download

Grab the latest build from Releases:

Opening it for the first time on macOS. The app is not notarised by Apple,
so Gatekeeper will stop it. Either drag it into Applications and run this once
in Terminal:

xattr -dr com.apple.quarantine /Applications/Sundial.app

…or avoid the terminal entirely: double-click, let it be blocked, then open
System Settings › Privacy & Security, scroll down to the notice about
Sundial, and choose Open Anyway.

Opening it for the first time on Windows. SmartScreen will show a blue
warning, because the executable is not signed with a Microsoft code-signing
certificate. Choose More info → Run anyway.

What it does

Two usage dials (Max / Pro only)

A ring sits on either side of the sun, with the percentage in the middle and a
label beneath.

• Left ring (honey gold) — the five-hour allowance.
• Right ring (apricot pink) — whichever weekly allowance is under the most
  pressure. That may be Weekly · all models, or a limit belonging to one
  particular model. Whichever is tightest is the one shown, and the label
  changes with it.

Details worth knowing:

• The arc fills clockwise from the top, easing smoothly as the figure changes.
• Overruns are shown honestly. If the endpoint returns 106%, it says 106%
  rather than clamping to 100. Clamping would suggest you had just run out,
  hiding how far past the line you actually are.
• The easing state is kept per ring position, not per label. The limit shown
  on the right changes identity from time to time; keeping state by label means a
  newly promoted label has no history and grows from zero, which reads as usage
  suddenly collapsing (measured: a jump from 216° to 54° in a single frame).

The sun is itself the indicator

Even folded down to a single sun, a glance tells you where things stand.

• Its expression follows usage: a broad grin when there is room, a flat line
  around halfway, a frown as the limit approaches. Eyebrows only appear once
  things get tight, angled high on the inside.
• Its colour deepens continuously with usage, rather than stepping between bands.
• The ray tips take on the colour of the dial on that side, and glow
  brighter the fuller it gets. The gradient sits only at the far end — the
  roots keep the body colour, so the colour reads as having been picked up
  from the dial.
• Ray length is pulled by the dials on either side: whichever allowance is
  tightest draws the rays towards it, and it does so as a breath that both
  attracts and repels — reaching out on the positive half-cycle, drawing back
  on the negative. The fuller the allowance, the faster the breathing. The two
  sides run in opposite phase, so the whole corona sways.
• Cursor gravity. As the pointer approaches — from outside the window, not
  just within it — the rays are drawn towards it, the body leans in slightly, the
  eyes follow, and the grin widens. While dozing this reverses: the rays shy away
  and the body draws back.
• Dozing. With no session running the sun turns grey, closes its eyes and
  drifts a few z's. The usage signal survives even then, in the brightness of the
  ray tips, so the folded state is never entirely mute.

Session blocks

One block per running Claude Code session, up to four:

• Session title, what it is doing, and how long the current turn has been running.
• Context consumption (for instance 824.8k / 1.0M), read from the ring on
  the right of the block. This figure needs no subscription.
• Status: Thinking · Waiting for you (a session asking a question jumps to
  the top) · Background task running · Unread · just finished ·
  Not responding · no update for N min.
• Click a block to dismiss the "finished but unread" marker.
• Blocks roll in and out, with the ones below sliding up in step, rather than
  appearing and vanishing on the spot.

The dial on the right of each block carries two readings at once, which only
works because they sit on separate tracks. How full the context window is is
a static arc from twelve o'clock, neutral and deepening as it fills, with the
figure in the middle — the one thing on the card with no colour of its own, so
that the two dials and the sun keep theirs. What the session is doing is motion on the track outside it: a
comet travelling round while it thinks, the whole halo pulsing while it waits for
you. A finished turn you have not read yet is marked by a breathing dot in front
of the word Unread instead, next to the thing it qualifies. A spinner could not
have absorbed the context reading — its legibility came from the arc length
itself oscillating, so length was already spoken for.

Working out when things happened turned out to be the fiddly part, and several
faults have been fixed along the way: the turn's start is anchored to the user's
message itself (locating it via last-prompt runs 112 seconds late); pressing
Esc clears the start; placeholder records left by API errors are no longer taken
as the end of a turn; and a timeout reports not responding rather than
pretending the work finished.

The interface

• When idle, only the sun remains, floating on the desktop with no card and
  no backing.
• Hovering expands it; moving away folds it up. Folding uses an S-curve over
  0.62 s, and the dials fade out ahead of the window — otherwise they are cut off
  by the window edge and appear to snap out of existence.
• On macOS the card is the system's Liquid Glass (NSGlassEffectView); on
  Windows it is a hand-drawn translucent panel (see Known limitations).
• It follows the system light / dark setting, and both palettes have had
  their contrast measured item by item.
• Drag to move it; the position is remembered. The glass takes on a warm tint
  while a session waits for your input.
• There is a small sun in the menu bar / system tray too, and it turns
  while a session is running.

Everything else

• Minimise. A button appears in the top-left corner of the card on hover —
  a 14pt disc, the size and glyph proportions AppKit uses for a window's own
  miniaturise button. Press it and everything folds down to the sun alone, and
  stays there — hovering will not pop it back open. Click the sun to bring the card back. If a session starts
  waiting on an answer while you are minimised, the sun pulses rather than
  forcing the card open: the reminder still reaches you, without overriding the
  decision you just made.
• Interface language. English or 简体中文, or follow the system, from the
  Language submenu. Following the system is the default; choosing explicitly
  sticks, so a later change to the system setting will not override it.
• Context menu: sign in / sign out, refresh now, keep the usage breakdown open,
  minimise to just the sun, open the web usage page, language, clearer glass,
  always on top, launch at login, bring the pet back to the centre of the
  screen, quit.
• The current version number sits at the top of the menu — worth quoting in any
  bug report.
• System accessibility settings are respected: Reduce Motion disables the
  cursor-following displacement, Reduce Transparency substitutes an opaque panel.
• Power: idle drops to 24 fps and disk polling slows down. While a session is
  running, however, it does use CPU continuously — full-frame custom drawing
  plus a transcript poll every 0.8 s, measured at roughly a third of one core
  (28–37% on macOS). On a laptop it will sit fairly high in Activity Monitor.
  The macOS build stops entirely when the display sleeps; the Windows build does
  not yet manage this.

Using it without a subscription

The two halves of the app are independent:

Without a subscription, Claude's authorisation page states plainly that
connecting Claude Code requires Max or Pro, and refuses. That is expected —
simply skip signing in. The sun and the session blocks carry on as usual.

The "or use an API key" option on that page does not help here: it is a
different billing arrangement, with no subscription allowance figure to show.

Even with a subscription, most people never sign in

There are two ways the dials can obtain credentials, and the first is the default:

1. Reuse the credentials Claude Code already holds (Keychain, or
   ~/.claude/.credentials.json). If you have signed in to the command-line
   Claude Code, this simply works — the dials are there on first launch, and no
   authorisation flow takes place at all.
2. Have Sundial sign in itself — needed only when the first route finds
   nothing. The usual reason is that you are using the desktop Claude Code,
   which keeps its sign-in elsewhere.

In other words, Sign in to Claude account in the menu is a fallback rather than
a required step. If the dials are already turning, you can ignore it.

Building it yourself

# macOS (requires the Xcode command line tools)
cd src
./build.sh              # local debug build, installed alongside the repository
./build.sh share        # universal binary (Intel + Apple silicon), packaged into dist/
./build.sh release      # requires a Developer ID certificate; includes notarisation

# Icons (only needed after changing the shape of the sun)
./icon/make-icons.sh          # light background
./icon/make-icons.sh dark     # dark background

# Windows build, cross-compiled on macOS (requires the .NET 10 SDK: brew install dotnet)
cd src-windows
./build.sh x64           # win-x64
./build.sh arm64         # win-arm64 (Snapdragon X and similar)
./build.sh check         # verification only: core logic plus offscreen renders to PNG

The VERSION file at the repository root is the single source of truth for the
version number; both build scripts read it.

Repository layout

VERSION                     single source of truth for the version number
src/                        macOS build (Swift + AppKit)
  ├ PetView.swift           all drawing and animation state
  ├ App.swift               window, menus, tray, power, accessibility
  ├ Activity.swift          reads Claude Code transcripts
  ├ Usage.swift             usage endpoint parsing and fetch scheduling
  ├ Auth.swift              OAuth PKCE and token storage
  ├ Model.swift / Theme.swift / Lang.swift
  └ icon/                   icon generator
src-windows/                Windows build (C# + Avalonia)
  ├ src/Sundial.Core/       pure logic, no UI dependency — testable on macOS
  ├ src/Sundial.App/        Avalonia interface
  └ tests/
     ├ LiveCheck/           runs the core layer against real local transcripts
     └ RenderCheck/         renders offscreen to PNG for frame-by-frame comparison with macOS
dist/                       packaged builds produced by `./build.sh share`
docs/                       images used by this README
  └ make-demo.swift         offscreen frame-by-frame renderer for the demo GIFs
                            (not a screen recording — reruns are identical)
NOTES.md                    maintenance notes: design decisions and the traps hit along the way

Both platforms share the same shape parameters and behavioural logic; fifteen
key constants are compared item by item to keep them in step.

Data and privacy

The session half only reads local files. What it reads is set out below in
some detail, because "it doesn't read your messages" is the sort of claim that
is very easily overstated:

That last row deserves to be spelt out: the parser does read the text of your
messages into memory — Activity.swift assembles it into
a string in order to test its prefix. It is not displayed, not retained and not
sent anywhere, but saying the app "never touches your messages" would not be accurate.

Note also that session titles are shown on your desktop. If a title contains
something sensitive, it is visible in screenshots and while screen-sharing.

• The sign-in token is stored locally only: on macOS in the application support
  directory (mode 0600), on Windows encrypted with DPAPI, so only your account
  can read it.
• Apart from the usage endpoint described below, nothing is sent anywhere. No
  analytics, no crash reporting.

⚠️ Please read this first

This is an unofficial personal project with no connection to Anthropic.

Two of its dependencies come with no guarantees whatsoever.

1. Usage figures come from an undocumented endpoint, GET /api/oauth/usage.
   Nothing about it is promised to remain stable; it may change or disappear at
   any time. When that happens the app will say it received data it could not
   make sense of, rather than inventing a figure for you.
2. The fallback sign-in route reuses Claude Code's own OAuth client_id
   instead of credentials registered for this app. The identifier itself is not a
   secret, but putting a third-party program through that authorisation flow
   may not be consistent with Anthropic's terms of service, and the route may
   well be tightened in future. The default route — reusing credentials that
   already exist — is unaffected, as it makes no authorisation request at all.

Realistically the consequence of both is that the dials stop turning one day,
not that something happens to your account: reading usage is a single GET,
writes nothing, and consumes no allowance.

One point does need stating plainly, though: the fallback sign-in requests
broader permissions than reading usage requires. The scope is
org:create_api_key user:profile user:inference
(Auth.swift:14) — Claude Code's own set, carried over
verbatim rather than pared down to what this app needs. Sundial uses it solely to
call the usage endpoint, but the scope you approve on the authorisation page is
genuinely wider than that. If that bothers you, do not take this route; reusing
existing credentials makes no authorisation request.

Both points affect the usage dials only. The session half reads local
transcript files, depends on no endpoint, and needs no account.

Known limitations

• The macOS build is ad-hoc signed and not notarised (only a free Apple
  Development certificate is available, which cannot produce a Developer ID
  signature), so the quarantine flag has to be cleared by hand on first launch.
• The Windows build supports only a natively installed Claude Code; it cannot
  see transcripts inside WSL. The usage dials are unaffected.
• The Windows card is a hand-drawn translucent panel rather than system acrylic.
  Acrylic applies only to a whole rectangular window, and this pet changes shape
  every frame, so enabling it exposes a rectangular backing outside the rounded
  corners. There is an experimental switch in the menu; either way this aspect
  remains a notch behind the macOS build.
• The icon does not follow the system light/dark setting — the traditional macOS
  .icns format cannot express that. A dark version lives at
  src/Sundial-dark.icns; run ./icon/make-icons.sh dark to switch.
• Not yet verified on real hardware: Intel Macs, macOS 13/14/15, VoiceOver
  actually speaking the interface, and on Windows the tray menu, launch at login
  and acrylic blur. The Windows sign-in flow has been verified on real hardware.

Supporting this

It is free, MIT-licensed, and built in spare time. If it saves you from
opening /usage for the tenth time today, a small sponsorship is welcome and
entirely optional — nothing is gated behind it, and nothing ever will be.

Bug reports and reproduction steps are worth just as much. The awkward ones —
timing that looks wrong, a session block that says the wrong thing — are
exactly what is hardest to find alone.

Licence

MIT — see LICENSE.