clepso

skill
Guvenlik Denetimi
Uyari
Health Uyari
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 6 GitHub stars
Code Gecti
  • Code scan — Scanned 12 files during light audit, no dangerous patterns found
Permissions Gecti
  • Permissions — No dangerous permissions requested

Bu listing icin henuz AI raporu yok.

SUMMARY

Clepso: a native macOS menu-bar monitor for your AI coding agents' usage limits (Claude Code and Codex). Local-first, private by design.

README.md

Clepso: a pixel heartbeat inside a ring, beside the word CLEPSO

Your coding-agent limits, before you hit them.
A local-first macOS menu bar app that shows how much of your Claude Code and Codex
usage limits you have used, when they reset and how fast you are going,
from what those agents report on your own Mac.

CI status Latest release, including pre-releases Licence: MIT Platform: macOS 14 or later Swift 6 Status: pre-release

Download · Website · Docs · Privacy · Design system · Progress · Changelog

The Clepso menu bar panel with demo data: the 5-hour limit at 83% and approaching, the 7-day limit at 21% and available, reset times, a pace estimate, and the current session's model, context, cost estimate, cache hits, lines changed, API time and agents

Every screenshot shows Clepso's built-in demo scenario (each screen is badged DEMO) with a synthetic statistics file and the made-up profile name "Sam", rendered by the app itself (see Run it safely).


[!NOTE]
Alpha: v0.4.0-alpha.2 is out. A signed, notarized build for Macs with Apple silicon on macOS 14 or
later (download). It is an early pre-release: expect rough edges. From v0.4.0-alpha.1 it can update
itself (see Download). You can also build it from source.
This repository (clepso, formerly tokone) builds Clepso.app.

Contents: Why Clepso · What it does · Private by design ·
How it works · Design system · Docs · Get started ·
Troubleshooting · Quality gates ·
Optional accounts backend · Project status and roadmap ·
Contributing, security and conduct · Licence and trademarks ·
Contributors · Acknowledgements

Why Clepso

Subscription plans for AI coding agents meter usage in rolling windows (for Claude Code: a 5-hour window and a
7-day window). Hitting a limit mid-task is disruptive, and the built-in view is a command you have to remember to
run. Clepso keeps the numbers in the menu bar, says how fresh they are, estimates where your current pace is heading,
warns you before a limit runs out, and keeps a local history, without sending your prompts, code or file paths
anywhere.

Clepso reports only what the agent itself reports. When a value is missing it says so instead of showing "0%", and it
never guesses your plan from your usage.

What it does

Everything below exists in the code on main. Items marked opt-in stay off until you turn them on.

In the menu bar

  • A dynamic menu bar readout that rotates Claude Code and Codex's 5-hour and 7-day used percentages every six
    seconds, with the agent and window beside each number. Most pressing limits lead the cycle. Settings lets you
    pin one window, keep the aggregate summary, or show the icon alone. Old readings say OLD; a passed reset
    says RESET? until a fresh reading arrives. Rotation pauses on hover, with Reduce Motion and with VoiceOver.
    The pixel states (live, approaching, limit reached, stale, demo, waiting, not connected) differ by shape
    (see Design system and readout states).
  • A panel with the 5-hour and 7-day limits: used %, status in words, reset time and countdown, freshness
    ("just now", stale), and a labelled estimate of when the current pace reaches 100%.
  • The current session: model, context used, cost estimate, prompt-cache hit rate, lines added/removed, API time,
    and how many agents the last task used.
  • Codex's 5-hour and weekly limits beside Claude Code's (opt-in).
The panel's Claude Code page with demo data: the 5-hour limit at 83% with its reset, countdown and pace estimate, the 7-day limit at 21%, the current session's model, context, cost estimate, cache hits, lines changed and API time, and the connection observed just now

Claude Code
Both limits with the pace estimate, the current session and how fresh the connection is.

The panel's Where this number comes from page with demo data for the 5-hour limit at 83%: provider field, source, measured and received times, quality, adapter and Claude Code version, when the reading counts as stale, and the last three readings

Where this number comes from
The field, source, times and quality behind a reading, and the readings before it.

Alerts before you hit a limit

  • Notifications at 80%, 95% and 100% of a limit, when a reset is expected, and when a limit is ready again; on once
    you allow notifications, with a one-hour snooze. Alerts too old to be news are dropped.
  • Quiet hours (off by default): during them the 80% and 95% alerts wait for one digest at the end, and everything
    else arrives without sound.
  • Reset reminders (off by default): a notice 5, 15, 30 or 60 minutes before a limit resets.

The Dashboard

  • Home: what needs attention now (limits, goals, a running task), both limits, the last 30 days, your level; after
    an update, a one-time "What's new" card (compiled into the app, no network).
  • Limits: each limit charted over its own window, with 80/95% bands, "now", and the dashed pace estimate
    (Claude Code's, and Codex's when that is on).
    Other agents, by hand adds dated readings for Claude Chat, ChatGPT, Gemini, Grok, Cursor, Copilot and Windsurf,
    explicitly labelled "Entered by you". These stay separate from automatic readings and do not trigger automatic alerts.
    With the Gemini CLI reader on (opt-in), Limits also shows Gemini CLI's recorded token activity. That is activity,
    not a quota: Clepso does not know Gemini's used percentage or reset time. A reported weekly reset can be added to
    Calendar, which asks before it adds the event.
  • Session: recent sessions, the selected session's details, agents per task, usage by model.
  • Overview and Models: a year activity calendar, tokens per day (Claude Code and Codex), streaks, model shares,
    and a "model arena" with levels earned from output tokens (opt-in: reads Claude Code's statistics file). Each model
    family has its own pixel character: an owl maestro for Opus, a fox storyteller for Fable, a verse keeper for Sonnet,
    a paper crane for Haiku, and a neutral robot for families Clepso does not know.
  • Card: a shareable pixel "player card" (copy image, save PNG, share). Nothing is sent unless you share it.
    In releases from v0.2 (v0.1.0-alpha.1 hid it).
  • Goals: active days per week, keep the 5-hour peak under a target, finish the week under a target; streaks.
    In releases from v0.2 (v0.1.0-alpha.1 hid it).
  • Account: profile name, chosen plan, optional sign-in (see Optional accounts backend).
  • Settings: appearance (System / Light / Dark) and colour theme (Phosphor, Amber, Cobalt, Orchid, Graphite; each
    with light and dark palettes), launch at login, notifications (alerts, quiet hours, reset reminders, a test
    notification), updates, the Claude Code connection (connect / remove), opt-ins (statistics file, agents per task,
    Claude desktop and VS Code limits, Codex, Gemini CLI), integrations (desktop widgets, MCP clients), export, demo data,
    diagnostics log, delete all.
Dashboard Home with demo data, dark: a greeting, what needs attention today (the 5-hour limit at 83%, two missed goals, a task running with two agents), both limits, a 30-day token chart and the current level

Home · dark
What needs attention today, both limits, the last 30 days and your level.

Dashboard Limits with demo data: the 5-hour and 7-day limits each charted over their own window, with 80% and 95% bands, a now marker and a dashed pace estimate

Limits · dark
Each limit over its own window: 80% and 95% bands, "now" and the dashed pace estimate.

Dashboard Session with demo data: context used, cost estimate, lines changed, cache hits and API time, the status line's details, and agents per task with three agents running now and the latest task

Session · dark
The current session in full, with agents per task: running now, the latest task and recent ones.

Dashboard Models with demo data, dark: a ranked roster of three models with tokens, share and level; the chosen model's dossier with tokens by kind, a level track to the next target, specialty and an activity band; and the ladder of levels with how to level up

Models · dark
Models: a ranked roster, the chosen model's dossier and the level ladder (only output tokens count towards a level).

Dashboard Home with demo data in light appearance: a greeting, what needs attention today (the 5-hour limit at 83%, two missed goals, a task running with two agents), both limits, a 30-day token chart and the current level

Home · light
Every theme has a light palette too, on warm paper instead of white.

Dashboard Models with demo data in light appearance: a ranked roster of three models with tokens, share and level; the chosen model's dossier with tokens by kind, a level track to the next target, specialty and an activity band; and the ladder of levels with how to level up

Models · light
The same roster, dossier and level ladder in light appearance.

Every self-drawn control has a pixel focus ring, charts and the calendar move with the arrow keys, ⌘,
opens Settings, and all animation goes through one Reduce Motion switch (docs/A11Y_CHECKS.md).
More screens: design/screens/ and the Screens page.

Outside the panel

  • Claude desktop app and VS Code (opt-in): Clepso's Claude Code mod reads the limits in sessions no terminal
    draws and hands them to the same helper. Clepso shows the two settings.json entries it adds before writing them,
    and takes both out again when you turn it off, byte for byte if nothing else changed
    (docs/specs/mod-bridge.md).
  • Desktop widgets (opt-in): small and medium widgets with the reported limits, their source, freshness and reset.
    macOS decides how often they refresh (docs/widgets.md).
  • Clepso MCP (opt-in): a local, read-only stdio server with two tools, get_limits and get_reader_health, for
    a client you allow by name in Settings and can revoke. It edits no client configuration
    (docs/integrations/mcp.md).
  • Signed updates: Settings › Updates checks for a new release when you ask. Daily checks and automatic install are
    off until you turn them on. Updates are signed and verified before they are unpacked
    (docs/in-app-updates.md).

Your data, under your control

  • Export my data: a JSON file (permissions 0600) of the local tables, with every string re-checked by the same
    scrubber the helper uses.
  • Delete all: removes Clepso's database and its files under ~/.claude/clepso, and restores your Claude Code
    settings; optionally also deletes the settings backups.
  • Retention: limit readings and engine events are kept 90 days; sessions, agent tasks and notification receipts 30 days.
    Settings › Your data offers shorter periods, including 1 or 3 days for diagnostics (7 by default). Shortening a
    period removes old records immediately; export records the chosen periods.
  • Demo mode: a fixed scenario run through the real engine and store, so you can explore without connecting anything.
Sources Clepso can read
Source What Clepso reads Default
Claude Code status line An allowlisted subset of the JSON Claude Code sends to its status-line command: limits, model, context, token and cache counts, durations, line counts, and the cost estimate (which you can switch off) On once you connect it in onboarding or Settings
Claude Code hooks For UserPromptSubmit, SubagentStart, SubagentStop and Stop: the event name, keyed hashes of the session and agent ids, and the built-in agent type ("custom" otherwise, unless you approved that exact agent name in Settings); on Stop and SubagentStop, how many background tasks Claude Code still has in flight, by type, status and agent type (counts only: no ids, descriptions or commands) Off (opt-in; shows the exact entry before writing it)
~/.claude/stats-cache.json Dates, counts, model ids and token totals through a field allowlist; never stored, logged or exported Off (opt-in)
Claude Code mod (clepso-limits) In Claude desktop and VS Code sessions that no terminal draws, after each turn: the limit percentages and reset times, context-window numbers and the session's model id, passed through the helper's allowlist Off (opt-in; shows the two entries before writing them)
~/.codex/sessions/**/rollout-*.jsonl Only token_count events (5-hour and weekly used %, reset, plan) and the model name, from the last 256 KB of the three newest files; other lines are skipped before decoding Off (opt-in in Settings)
Gemini CLI recordings (~/.gemini/tmp, ~/.cache/.gemini/tmp) Message ids (for deduplication), timestamps and numeric token fields from the 16 newest recordings; conversation content is discarded, and the counts stay in memory and are never uploaded (docs/integrations/gemini.md) Off (opt-in in Settings)

Where Claude Code runs. Limits come from the status line, which Claude Code draws in a terminal (including an IDE's
terminal). The Claude desktop app's Code tab runs hooks but not the status line (tested 19 Oct 2026). With the mod on,
its limits arrive after each turn. Without it, its tasks and agents are counted, and its usage still counts against
your plan, but the limit figures update only when a terminal session next reports.

Automatic adapters for Cursor, GitHub Copilot, Windsurf and Grok are on the roadmap, as are
Gemini's quota percentages and reset times. You can enter dated manual readings for them on Limits. The bundled plan
catalog lists plans with source links; only Claude Code and Codex limits are read automatically today.

Private by design

Clepso is built so that the part Claude Code runs cannot leak what it sees, and so that every change it makes to your
machine can be undone.

  • Allowlist, not blocklist. The helper copies only named fields, each with a type and range check
    (Sources/ShimProtocol/Allowlist.swift). Your working directory,
    transcript path, session name, prompt id and workspace folders are never forwarded. Strings that look like paths,
    emails or secrets are dropped. Session ids are replaced by an HMAC keyed with a random 32-byte key stored at
    ~/.claude/clepso/session.key (0600).
  • The helper cannot reach the network. clepso-statusline links only Foundation, CryptoKit and system libraries;
    make ci fails if it links any networking library or symbol.
  • Network code lives in one module. Only Sources/Sync may use networking APIs, and only the app imports it
    (make ci enforces both). Sync does nothing unless the build carries an accounts project and you sign in.
    Builds from source carry none, so they never sign in or upload anything. The one other network path is the
    updater (Sparkle, in the app target): it fetches the signed update feed when you check, or daily once you turn
    automatic checks on, and sends no system profile.
  • Your Claude Code settings are changed reversibly. Connecting changes exactly one key, statusLine.command,
    in ~/.claude/settings.json, after writing a byte-exact backup to ~/.claude/clepso-backups/. Writes are
    compare-and-swap with an atomic rename, and an interrupted install can be recovered. If you already had a status
    line, it keeps running and its output reaches Claude Code unchanged. Removing Clepso restores the original bytes.
  • Local IPC is restricted to your user. The app listens on a Unix socket at
    ~/Library/Application Support/Clepso/run/agent.sock (folder 0700, socket 0600), accepts only peers running as
    your user id, frames of at most 4 KiB, and at most 20 frames per second.
  • Logs are redacted by type. Values wrapped in Redacted<T> cannot be encoded; make ci audits every place that
    unwraps one.
  • If you sign in (optional, official builds), Clepso uploads once an hour: your profile name and plan label, and
    per-day counts (messages, sessions, active day, tokens per model, model totals by token kind, 5-hour peak and 7-day
    end %, agents per task by built-in type, goal targets and results). No prompts, replies, paths, project names or raw
    ids. Every table is protected by row-level security, and deleting your account deletes every row
    (backend/supabase/migrations/).

What Clepso does not do: read your prompts or replies, read transcripts, or send anything anywhere unless you sign
in. (Gemini CLI recordings hold conversations too: with that reader on, Clepso decodes only ids, timestamps and token
counts from them.) Widgets and MCP clients get only limit readings (percentages, resets, source and freshness), and
only once you turn them on; an MCP client may pass those readings on to its own AI service. The full design is in
docs/PRIVACY_AND_SECURITY.md; the Privacy
page
lists every uploaded field in plain words.

How it works

  1. Claude Code runs its status-line command on every refresh and pipes a JSON description of the session to it.
    Connecting Clepso points that command at a small wrapper (~/.claude/clepso/statusline.sh) that runs the helper
    embedded in the app, or your original command if the app has been removed.
  2. The helper (clepso-statusline) runs your original status line with the exact input bytes, so it looks the
    same, keeps only allowlisted fields, and sends them to the app over a local Unix socket within about 48 ms. It
    never writes to disk, never retries and has no network code; if the app is not running, the frame is dropped.
  3. The app validates the frame, stores a reading in SQLite when a value changes, and derives each limit's state
    (available, approaching, critical, exhausted, reset expected, available again) with pure, clock-injected state
    machines and a least-squares pace estimate.
  4. No usage data leaves the Mac unless you sign in to an official build; then only the daily counts listed above.
    An update check downloads the feed and sends none.
The full data flow (diagram and details)
flowchart LR
    subgraph CC["Claude Code (your terminal)"]
        SL["status line refresh<br/>(JSON on stdin)"]
        HK["hook events<br/>(opt-in)"]
    end

    subgraph Helper["clepso-statusline<br/>(Clepso.app/Contents/Helpers)"]
        RUN["runs your original<br/>status-line command"]
        AL["field allowlist + scrub<br/>HMAC of session ids"]
    end

    subgraph App["Clepso.app (menu bar)"]
        SOCK["IngestSocket<br/>same-user peers, 4 KiB, 20/s"]
        MAP["FrameMapper → observations"]
        DB[("SQLite via GRDB<br/>~/Library/Application Support/Clepso")]
        ENG["UsageEngine<br/>limit, reset and pace rules"]
        UI["SwiftUI: menu bar panel,<br/>Dashboard, onboarding"]
        SYNC["Sync (optional)<br/>the only module with network access"]
    end

    STATS["~/.claude/stats-cache.json<br/>(opt-in)"]
    CODEX["~/.codex/sessions tails<br/>(opt-in)"]
    CLOUD[("Supabase: daily counts,<br/>row-level security")]

    SL -->|stdin| Helper
    HK -->|"--hook"| Helper
    RUN -.->|"stdout unchanged"| CC
    AL -->|"frame v1 over a Unix socket"| SOCK
    SOCK --> MAP --> DB
    DB --> ENG --> UI
    STATS --> UI
    CODEX --> DB
    UI --> SYNC -->|"HTTPS, only when signed in"| CLOUD
  • The helper's time budget: connect within 20 ms, everything finished by about 48 ms after start (make perf checks a
    p95 of 20 ms or less over 200 runs on the maintainer's Mac).
  • Without a value change the app stores a check-in every 2 minutes. Limit states use hysteresis, so a reading hovering
    near a threshold does not flicker between states.
  • The SwiftUI layer reads a projection of that state. Colours, spacing, type and motion come only from the Theme
    tokens in DesignSystem, and icons are pixel glyphs (all enforced by make ci).
  • Clepso is a menu bar-only app (LSUIElement). It is not sandboxed, because it has to read and edit files under
    ~/.claude. Its only entitlements are the app group it shares with the sandboxed widget extension and the
    debug-only get-task-allow, and official builds use hardened runtime.

More: docs/ARCHITECTURE.md, docs/DATA_MODEL.md and the
Architecture page.

Design system

Clepso has its own identity, built in code: a heartbeat inside a ring. The ring is the limit, the same ring that sits
in the menu bar; the beat is the live reading. It is drawn on a 16-pixel grid with a 1-pixel stroke, so it reads at
menu bar size, in one colour, in any theme. The full guidelines, themes, components, voice and downloads are on the
design system page.

The menu bar family. One ring; the mark inside changes. It is a template image, so macOS tints it for light, dark
and tinted menu bars, and the shape alone carries the meaning:

The seven menu bar states, one ring with a different mark inside: beat (a live reading), approaching (an exclamation mark), flatline (limit reached), stale (a clock), demo (a broken ring), waiting (three dots) and not connected (an empty ring)

beat: live reading · approaching: near a limit · flatline: limit reached · stale: the last reading is old ·
demo: demo data · waiting: no reading yet · not-connected: no trace. A state that is no longer current opens the ring
at five o'clock with a dot in the gap (see the menu bar sheet).

Typefaces. Two faces drawn for Clepso on one grid. Clepso Pixel speaks in numbers and labels: capitals 7 pixels
tall, a dotted 0, a flagged 1 and tabular figures, so a number is never misread. Clepso Mono explains: a monospace
in Regular, Medium and Bold, built from the rounded rectangle behind the pixel face's corners.

Clepso's type in the Phosphor dark theme: 83% and 16.5B · OPUS 5.5 in Clepso Pixel, then Approaching limit · just now and RESETS 17:24 · IN 2H 14M in Clepso Mono

Colour. Components ask for a role (background, accent, status), and only the theme knows the value. Five themes,
each with a dark and a light palette, every text role checked at 4.5:1 or better against every surface.

Signature colour Hex Meaning
Phosphor #4DFF8F The signature: marks, accents, the live signal
Ink #060907 Near-black glass, the default ground
Paper #F3F1E7 The light ground: warm, never pure white
Deep #0A7238 Phosphor on paper: the accent in light mode
Amber #FFC04D Attention: approaching a limit
Rust #FF6B5E Blocked: a limit reached, an error

The brand kit (logo SVG masters in six colourways, PNGs, app icon, menu bar family, favicon, fonts, sheets and
specimens) lives in design/brand/ and is generated by
design/brand/pipeline/build.sh; the reasoning is in
design/brand/NOTES.md. The fonts are open (SIL OFL 1.1); the name, logo and icons are not
(see Licence and trademarks).

Docs

On the website

Page What's there
Overview What Clepso is, the build in numbers, a reading's path from Claude Code to the menu bar
Progress Every roadmap increment, its status and the evidence that it works
Metrics How every number is defined, where it comes from and what it does not mean, with three playgrounds
Architecture A reading's path, processes, modules, principles and quality gates
Privacy What stays on your Mac, and every field uploaded if you sign in
Changelog Every commit, newest first, with the gates it passed
Screens Every app screen, captured from the running app with demo data
Design system Logo, colour, typography, iconography, components, voice and downloads
Web dashboard Your own uploaded counts, for signed-in accounts

In this repository

Document What's there
docs/ARCHITECTURE.md How Clepso is put together (section numbers are cited from code comments)
docs/DATA_MODEL.md Types, schema and the state machines
docs/PRIVACY_AND_SECURITY.md What Clepso reads, keeps and can upload, and how it protects the files it touches
docs/STATUS.md What the current release implements, what it does not, and what is still unverified
docs/RELEASE.md The signing and notarization runbook (make release; first used for v0.1.0-alpha.1)
docs/in-app-updates.md Signed in-app updates: the feed, keys and release steps
docs/widgets.md Desktop widgets and what they share
docs/integrations/ Clepso MCP and the Gemini CLI reader
docs/specs/mod-bridge.md The Claude Code mod for the desktop app and VS Code
docs/A11Y_CHECKS.md Keyboard-only and Reduce Motion checks
docs/FIXTURES.md The status-line fixture corpus
docs/APPLE_PLATFORMS.md iPhone, Apple Watch and widgets: feasibility
docs/EMAIL.md The account sign-in emails
docs/open-source/ Open-source readiness: the audit, the go-public record and the GitHub settings
design/brand/README.md The brand kit and its build pipeline

Get started

Download

  1. Download Clepso-0.4.0-alpha.2.dmg from the v0.4.0-alpha.2 release. It needs macOS 14 or later on a
    Mac with Apple silicon
    . To check the file, download SHA256SUMS next to it and run shasum -a 256 -c SHA256SUMS.
  2. Open the disk image and drag Clepso into Applications, then open it from there.
  3. Follow the welcome window: it shows the one Claude Code setting it changes, and backs it up first.

This alpha offers optional email accounts. Local tracking needs no account; signing in syncs the documented daily activity summaries over HTTPS. The release notes list what is in it and its
known limitations.

Later releases arrive through Settings › Updates. Clepso checks only when you ask until you turn on automatic
checks. An app from before v0.4.0-alpha.1 has no updater: install the new release once by hand.

Install with Homebrew

brew install --cask obileonardo/clepso/clepso
open -a Clepso

The official Clepso tap installs the same signed, notarized alpha
for Apple silicon on macOS 14 or later, and links its clepso command-line tool. If Homebrew asks to trust the
third-party cask, review and approve Clepso. The cask declares auto_updates true, so a bare brew upgrade skips
it. Update in the app, or quit Clepso and run brew update followed by
brew upgrade --cask --greedy obileonardo/clepso/clepso, as the tap documents.

Already installed from a DMG? Use the tap's migration instructions
to adopt the identical app and keep one copy. Homebrew preserves Clepso's Library data and does not change agent
connections or opt-ins. The tap also documents uninstalling and release maintenance.

Requirements for building from source

Tool Version Notes
macOS 14 Sonoma or later (deployment target) Development runs on a current macOS release
Xcode 27.1 (pinned by make ci; make ci-contributor accepts any Swift 6 toolchain) Provides the macOS SDK and xcodebuild
Swift 6.4 (bundled with Xcode 27.1) Swift 6 language mode; warnings are errors
XcodeGen 2.46.0 Downloaded and SHA-256-checked into .tools/ by scripts/bootstrap.sh; no Homebrew needed
Claude Code A version with status-line support The fixtures were captured from 2.1.302. make ci also needs the claude CLI (2.1.287 or later) to check the mod; make ci-contributor skips that check without it
Node.js For make ci The character artwork check; CI also runs the MCP client test with npm
Docker and the Supabase CLI Optional Only for make backend-test
Python 3 For make ci The email template check, the documentation site and the fixture oracle

Two third-party Swift packages: GRDB.swift 7.11.1, pinned by revision in
Package.resolved, and Sparkle 2.10.0, pinned exactly in project.yml and linked only
by the app target.

Build from source

git clone https://github.com/obileonardo/clepso.git
cd clepso
sudo xcode-select -s /Applications/Xcode.app   # point at your Xcode 27.1 installation

swift build        # all libraries and command-line tools
swift test         # the full suite: no network, never touches your real ~/.claude
make app           # Clepso.app: XcodeGen → xcodebuild → codesign --verify

make app writes build/DerivedData/Build/Products/Debug/Clepso.app. The Xcode project (Clepso.xcodeproj) is
generated from project.yml and is not committed; Package.swift is the source of truth for all code.

Local configuration and make targets

All local configuration is optional; the files are gitignored, and each has a committed .example template in Config/.

File What it sets Without it
Config/Signing.local.xcconfig Your signing identity and team The app is signed ad hoc, which is enough to run it on the Mac that built it
Config/Sync.local.xcconfig An accounts project (host and publishable key) Sync is off: no sign-in, no uploads, no requests
Config/local.mk DOCS, the planning folder make site reads make site stops with an explanation

Config/Clepso.xcconfig holds the defaults and includes the local files when they exist.

Command What it does
make ci Every quality gate, strict (see Quality gates). Logs in .build/ci-logs/
make ci-contributor The same gates for machines without the maintainer's setup: any Swift 6 toolchain, ad-hoc signing, Sync off
make build swift build --build-tests -Xswiftc -warnings-as-errors
make test swift test
make perf Helper overhead budget: release build, 200 runs, p95 ≤ 20 ms (enforced on the maintainer's Mac; hosted runners are too noisy for absolute budgets)
make backend-test Starts a local Supabase stack (Docker) and runs the pgTAP row-level-security tests
make site Regenerates the documentation website in site/ (needs DOCS in Config/local.mk: planning documents that are not in this repository)

Run it safely

Debug builds accept two launch arguments that redirect everything Clepso reads and writes, so you can try it without
touching your real ~/.claude or Application Support folder:

build/DerivedData/Build/Products/Debug/Clepso.app/Contents/MacOS/Clepso \
    -ClepsoDataDirectory /tmp/clepso-data -ClepsoHome /tmp/clepso-home

Choose Show demo data instead in onboarding to see the screens above. Keep the data folder path short: the socket
path inside it must stay under the 104-byte Unix limit, otherwise the panel reports that it isn't receiving updates.

More on debug runs, and the screenshot probe

A debug build has the same bundle identifier as an installed Clepso, so macOS treats it as the same app. With either
argument (or -ClepsoProbeOutput) set, the run is isolated from everything macOS keeps per app: sign-in state is kept
in memory instead of the Keychain (it can never upload to, or sign out of, a real account), the login item and the
notification centre are stand-ins (permission reads as allowed; nothing is shown, scheduled or cancelled), Delete
everything leaves the Keychain alone, a sign-in link it did not ask for is ignored, and no window size or open window
is saved. With -ClepsoDataDirectory alone the run reads your real ~/.claude but never rewrites Clepso's files there.
The probe refuses to start without -ClepsoHome or -ClepsoDataDirectory. -ClepsoHome on its own stands in for your whole home folder: the data folder is
then <home>/Library/Application Support/Clepso, and an old <home>/Library/Application Support/Pulse and
<home>/.claude/pulse there are moved the way a real upgrade from a build named Pulse moves them.

Screenshots and popover timing (debug builds):

# synthetic ~/.claude/stats-cache.json, fixed seed
python3 -I scripts/probe-home.py /tmp/clepso-home

# add -ClepsoProbeLight YES for light mode
build/DerivedData/Build/Products/Debug/Clepso.app/Contents/MacOS/Clepso \
    -ClepsoDataDirectory /tmp/clepso-data -ClepsoHome /tmp/clepso-home \
    -ClepsoProbeOutput /tmp/clepso-shots -ClepsoProbeDemo YES &

swift scripts/probe-popover.swift /tmp/clepso-shots 40

The script posts 40 real clicks on the status item (your terminal needs Accessibility permission) and prints
popover-open p50/p95; the app then saves each screen as a PNG in the output folder and quits. The probe always uses
the profile name "Sam" (or -ClepsoProbeName <name>), never your Mac account's name.

Connect Claude Code

Launch normally and use Connect in onboarding or the Claude Code connection in Settings. Clepso shows the exact
change to settings.json before writing anything. The headless CLI does the same and only previews unless you pass
--confirm:

swift run clepso install --shim <path to clepso-statusline>             # preview only
swift run clepso install --shim <path to clepso-statusline> --confirm   # install
swift run clepso status
swift run clepso uninstall --confirm   # restore your settings
swift run clepso recover               # finish or roll back an interrupted install

The same tool runs the read-only MCP server (clepso mcp --client <name>) for a client you have allowed in Settings.

Troubleshooting

Start with Settings › Diagnostics. It counts the updates Clepso received from Claude Code and keeps a log of recent
events with paths and secrets removed.

  • "Waiting for Claude Code…" or "No limits reported yet." Clepso shows only what Claude Code reports, and Claude
    Code reports limits through its status line. Connect Claude Code (see Connect Claude Code),
    then send any message in a Claude Code session in a terminal. Clepso must be running too: the helper drops readings
    while the app is closed, so turn on Open at login in Settings.
  • A limit says OLD or RESET? A reading counts as stale after 10 minutes, and a passed reset waits for a fresh
    reading. Both clear when the agent next reports: send a message in Claude Code or Codex.
  • Connecting fails with "Couldn't update settings. Nothing was changed." Clepso refuses to edit
    ~/.claude/settings.json when the file is not valid JSON or its current statusLine is not a command it can wrap.
    Fix the file and connect again (docs/PRIVACY_AND_SECURITY.md §7).
  • No limits from the Claude desktop app or VS Code. Neither runs the status line. Turn on Desktop app and VS Code
    panel
    in Settings (it needs the Claude Code connection first); readings start with your next Claude session there.
    If Settings says "disableAllHooks is on in settings.json", Claude Code would run no mod and no status line until you
    turn that off. If your organisation turns mods off, Clepso still counts tasks there but not limits
    (docs/specs/mod-bridge.md).
  • Codex doesn't show. It is opt-in: turn on Read Codex's session files in Settings. "Codex hasn't written a
    session on this Mac" means there is no ~/.codex/sessions yet, so run Codex once. "On. Waiting for Codex's next
    session to report its limits" clears after your next Codex session.
  • No alerts. If Settings says "Notifications are off in System Settings.", choose Open System Settings, allow
    Clepso, then use Send a test notification.
  • The widget says "Open Clepso → Settings → Integrations to share widget readings." Sharing starts off: turn on
    Desktop widgets there, then add Clepso limits from the widget gallery. A build from source can't share
    ("Widget sharing is unavailable in this app signature"). macOS decides when widgets refresh
    (docs/widgets.md).
  • clepso: command not found. Homebrew links the clepso tool; the DMG does not. Run
    /Applications/Clepso.app/Contents/Helpers/clepso. For an MCP client, allow it in Settings › Integrations and use
    Copy setup, which uses that path. "Client permission is off" means that client name is not allowed there
    (docs/integrations/mcp.md).
  • No update arrives. Apps from before v0.4.0-alpha.1 have no updater: install the new release once by hand. A bare
    brew upgrade skips Clepso; see Install with Homebrew.
  • Reset or uninstall. Delete all Clepso data… in Settings restores your Claude Code settings from the backup,
    deletes ~/.claude/clepso and Clepso's database and log in ~/Library/Application Support/Clepso, and can also
    delete the backups in ~/.claude/clepso-backups. If the restore can't be done safely, nothing is deleted. Then move
    the app to the Trash. brew uninstall on its own keeps your data and leaves Claude Code's settings as they are; to
    disconnect only, use Remove from Claude Code… or clepso uninstall --confirm.
Building from source, and other checks
Symptom What to check
make ci fails at "toolchain pinned" or "app bundle" That is the strict mode. Use make ci-contributor unless you build official releases
make app fails with a signing error Remove or fix Config/Signing.local.xcconfig; without it the app is signed ad hoc
The panel says Clepso isn't receiving updates (debug run) The -ClepsoDataDirectory path is too long for a Unix socket; use a shorter one
Account says accounts aren't available Expected in builds from source (see Optional accounts backend)
The panel says "not connected" Claude Code only runs the status line while a session is open; check Settings for the connection state and the diagnostics log
My old status line disappeared It should keep running. Run swift run clepso status, then swift run clepso uninstall --confirm to restore the backed-up bytes, and open an issue
Want to see what Clepso stored Settings › Export my data writes a JSON copy

Quality gates (make ci)

scripts/ci.sh has 17 gates. It runs every one even if an earlier one fails, prints a summary, and exits non-zero if
any failed. make ci is strict: it pins the toolchain and requires the app to be signed with a real identity, with
hardened runtime, and with an accounts project configured, so an official build cannot quietly fall back.
make ci-contributor (scripts/ci.sh --contributor) runs the same checks but accepts any Swift 6 toolchain, an ad-hoc
signature and no accounts project. GitHub Actions runs the gates in contributor mode on every pull request and every
push to main (.github/workflows/ci.yml), on GitHub's xcode-27 macOS image with
Xcode 27.1.

Every gate and what it proves
Gate What it proves
toolchain pinned Xcode 27.1 and Swift 6.4 are selected (contributor mode: a Swift 6 toolchain)
strict build Everything, tests included, builds with warnings as errors
tests swift test passes
helper links no networking The release clepso-statusline links only allowed system libraries and no networking symbols
release build has no debug code A release build of the app and the helper contains none of the debug-only names (probe flags, debug launch arguments, test-only helper settings) listed in scripts/debug-only-names.regex, while the debug build shows them
networking only in Sync No URLSession/Network use outside Sources/Sync; only the app imports Sync
clock injected No direct Date() in the pure layers and the app (time is injected)
design tokens only Components and screens use Theme tokens and pixel icons, never raw colours, sizes or system symbols
motion through tokens Every animation goes through a motion token, and frame-by-frame motion pauses under Reduce Motion
keyboard reachable No plain buttons without the pixel focus ring; every tap gesture and hover readout has a keyboard path
redaction audit unsafeReveal only in Storage and the helper; Redacted is never Codable
secret scan No secret-shaped strings in the tree (a regex stand-in for a full scanner)
no committed accounts project No Supabase project host or publishable key in tracked files, and no Config/*.local.xcconfig tracked
email templates The account emails are current with their sources, and their logo is deployed with the site
character artwork parity The app's character art matches the approved website drawings
Claude Code mod The mod validates strictly, calls only what its spec lists, and its tests pass, all in a throwaway home (contributor mode skips it when claude is missing)
app bundle Clepso.app builds and is signed, embeds the helper and the clepso tool, embeds the widget extension at the app's version, has no unexpected entitlements, requires a signed update feed checked before extraction, runs as a menu bar app, registers the sign-in URL scheme, bundles the mod byte for byte, ships the third-party licences, and its helper links no networking. Strict mode also requires a real signature, hardened runtime and a configured accounts project
Project layout
App/ClepsoMac/             @main, the Sparkle updater, app icon and Acknowledgements.txt (Info.plist and entitlements are generated)
App/ClepsoWidgets/         The WidgetKit extension (small and medium widgets)
Config/                    Clepso.xcconfig defaults and templates for the uncommitted local settings
mod/claude-code/           The clepso-limits Claude Code mod, bundled into the app as is
Sources/
  Domain/                  Value types, provenance, Redacted<T>. No I/O, no clock reads
  ShimProtocol/            Frame v1, the field allowlist, the string scrubber, hook frames, mod hand-off
  StatusLineShim/          The helper's run loop: stdin, child process, socket send
  clepso-statusline/       The helper executable Claude Code runs (one-line main)
  ClaudeCodeAdapter/       Settings, hooks and mod installers, ingest socket, frame mapper, statistics reader
  CodexAdapter/            Codex session-file tail reader
  ProviderTelemetry/       Gemini CLI recorded-activity reader
  UsageEngine/             Pure limit, reset, session and pace state machines; alerts, quiet hours, reset reminders
  Storage/                 GRDB/SQLite schema v1–v6, migrations, ledger policy, retention
  SubscriptionCatalog/     Bundled plan catalog (plan-catalog.v1.json)
  DesignSystem/            Themes and tokens, status styles, pixel components and glyphs, bundled fonts
  IntegrationSnapshot/     The allowlisted limits snapshot shared with widgets and MCP
  ClepsoMCP/               The read-only stdio MCP server
  ClepsoApp/               Composition root, AppModel, projections, SwiftUI views, copy, diagnostics, export
  Sync/                    Optional accounts: PKCE email-link sign-in, Keychain session, upload
  clepso/                  Headless CLI: install, uninstall, status, recover, mcp
  FixtureTools/, clepso-fixture/   Developer-only capture listener and scrubber (never shipped)
  clepso-design-render/    Developer-only: renders real components to PNG for the design-system page
  TestFixtures/            Fixture corpus F01–F19 and one scrubbed real capture (C01)
Tests/                     Swift Testing suites per module, integration tests that run the built helper, and an MCP client check (MCPClient/)
backend/supabase/          Accounts schema with row-level security, pgTAP tests, local Supabase config
design/screens/            App screenshots (demo data, synthetic statistics)
design/brand/              The Clepso mark, app icon, typefaces and their build pipeline
docs/                      Architecture, data model, privacy and security, fixtures, open-source readiness
docs/readme/               Images drawn for this README by scripts/readme-menubar-strip.py and scripts/readme-screens.py
scripts/                   ci.sh, bootstrap.sh, site generators, fixture oracle, probe driver and synthetic home
site/                      Generated documentation website (static HTML)

Optional accounts backend

backend/supabase holds the schema for optional Clepso accounts: eight tables of daily counts keyed by the signed-in
user, each with forced row-level security (user_id = auth.uid()), no grants to anonymous users, and a
delete_account() function whose deletion cascades to every row. make backend-test runs 16 pgTAP checks against
a local stack.

The app's Sync client signs in with a one-time email link using PKCE, returns to the app through the
clepso://auth-callback URL scheme, keeps the session in the Keychain (this device only), and uploads
idempotently once an hour. Apple, Google and GitHub sign-in are shown as "Soon" and are not enabled. A static web
dashboard on the docs site (/app/) shows a signed-in user their own uploaded
counts and can delete the account (docs/PRIVACY_AND_SECURITY.md §9.1).

Official builds include optional email accounts. The app reads its project from Info.plist, which gets it from
Config/Sync.local.xcconfig at build time. A build from source has none: the Account page says accounts aren't
available in this build, Home never suggests signing in, and Clepso makes no network request unless you check for
updates. To use your own backend, apply backend/supabase/migrations/ to your Supabase project and copy Config/Sync.local.xcconfig.example
with your project's host and publishable key (the app refuses secret keys).

Project status and roadmap

The live view, with the evidence for every increment, is the Progress page.

Milestone State
M0 Foundation: domain, helper, fixtures, reversible installer, local CI, first real capture Done
M1 Mac vertical slice: socket, engine, store, design system, menu bar app, diagnostics, export, delete all, details and stats, dashboard, pixel UI, light mode Done
1.9 Agents per task through Claude Code hooks Done (opt-in)
1.15–1.18 Five colour themes; Clepso's own typefaces, app icon and menu bar family; keyboard and Reduce Motion Done
2.0 Accounts: schema with row-level security, Mac sign-in and upload, web dashboard Done (email sign-in); Apple, Google and GitHub sign-in on hold
2.1–2.4 Limit alerts, quiet hours, reset reminders, time-travel test harness Done
2.5 One-tap "add reset to Calendar" Available from v0.3: weekly reported resets, explicit Calendar import
Claude desktop / VS Code limits Available from v0.3 through the opt-in Claude Code mod
3.4 Codex limits: reader, store, panel, Limits page, Stats and Settings switch Done (opt-in)
3.2 Manual snapshots Implemented: dated readings on Limits, separate from automatic telemetry
Gemini CLI recorded token activity Available from v0.4.0-alpha.2 (opt-in); not a quota
3.5–3.9 Automatic Gemini quota, Grok, Cursor, GitHub Copilot, Windsurf adapters Planned; source and consent validation required
4.1 Signing and notarization (make release) Done: v0.1.0-alpha.1, 19 Oct 2026
Desktop widgets, read-only MCP, signed in-app updates Available from v0.4.0-alpha.1
4.2 iPhone and Apple Watch (feasibility checked) In progress
Known limitations
  • Claude Code's status line carries only the 5-hour and 7-day limits. Per-model weekly limits that /usage shows are
    not visible to Clepso; it says so and counts the limit windows it cannot read.
  • Readings arrive only while Claude Code refreshes its status line, so Clepso shows how old each value is.
  • Clepso always uses ~/.claude. A custom CLAUDE_CONFIG_DIR is supported by the installer code but not yet wired
    into the app.
  • The app is built for Apple silicon only. In-app updates start with v0.4.0-alpha.1; an older install has to be
    replaced by hand once.
  • Widgets need the official build's team-signed app group. A source build signed ad hoc reports widget sharing as
    unavailable.
  • make site reads planning documents that are not in this repository.
  • The local socket accepts any process running as your user; a code-signature check of the helper is planned
    (docs/PRIVACY_AND_SECURITY.md §3).

Contributing, security and conduct

Licence and trademarks

The source code is released under the MIT License, copyright (c) 2026 Elvis Obi. The Clepso Pixel and Clepso
Mono typefaces are released under the SIL Open Font License 1.1. Third-party components
keep their own licences, listed in THIRD_PARTY_NOTICES.md and shipped inside the app in
Acknowledgements.txt.

Neither licence covers the project's identity: the Clepso name, logo, app icon, menu bar mark and favicon are reserved. You can
refer to Clepso, link to it and show the logo unmodified when you write about the project; a fork is welcome under its
own name and icon. The terms are in TRADEMARKS.md.

Claude and Claude Code are trademarks of Anthropic; Codex and ChatGPT of OpenAI; Gemini of Google; other product
names belong to their owners. Clepso is an independent project, not affiliated with or endorsed by any of them; the
names are used only to say which tools Clepso works with.

Contributors

Acknowledgements

  • GRDB.swift by Gwendal Roué (MIT), for SQLite.
  • Sparkle 2.10.0 (MIT), for signed in-app updates.
  • three.js r160 (MIT), for the documentation site's footer scene.

Yorumlar (0)

Sonuc bulunamadi