agentleFS
jasperhan99jasperhan99/pulsession/CLAUDE.md

pulsession

CLAUDE.md1 starsChanged 53 days agoApache-2.0View on GitHub

AI entry for this repo. Human workflow, evidence rules, and the docs map live in CONTRIBUTING.md and Docs/README.md. Change the authoritative topic doc in the same patch as the code; do not grow this file. This repository is Pulsession, a fork of Pulse (upstream remote) that adds a session monitor: PI-Desktop, Claude Code and Codex sessions on the rail. Fork code lives in Sources/Pulse/Sessions/; upstream files are touched only at small commented seams — keep it that way so upstream/main…

  • In this repositoryOne other file it gives its agents.

The file

We split this CLAUDE.md into the rules it gives an agent

1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Panel frame while a card opens: do not resize the window and do not put card + rail in a shared stack.

    line 37

≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

CLAUDE.md

AI entry for this repo. Human workflow, evidence rules, and the docs map live in CONTRIBUTING.md and Docs/README.md. Change the authoritative topic doc in the same patch as the code; do not grow this file.

This repository is Pulsession, a fork of Pulse (upstream remote) that adds a session monitor: PI-Desktop, Claude Code and Codex sessions on the rail. Fork code lives in Sources/Pulse/Sessions/; upstream files are touched only at small commented seams — keep it that way so upstream/main merges stay tractable. Identity (bundle id io.github.jasperhan.pulsession, pulsession://, ~/Library/Application Support/Pulsession, no Sparkle feed) is set in Scripts/bundle.sh and the files it names. Docs/sessions.md.

Pulse is a macOS menu-bar usage monitor. SwiftUI draws the panel; a transparent, non-activating AppKit NSPanel owns size, placement, and input. Seventy-seven providers, no Pulse backend, no Pulse account. Per-provider routes, auth, cookies, and extra logins: Docs/providers/README.md.

Sources sit in six directories under Sources/Pulse: App (lifecycle, settings store, updates), Panel (the window, its placement, and everything drawn in it), Settings (the settings window), Usage (store, cache, ledger, forecast, alerts), Providers (one service per product, plus their helpers), Auth (keys, logins, cookies). Swift has no directory namespace and SwiftPM recurses, so a file's directory is a claim about what it belongs to and nothing else — move a file when that claim stops being true.

Commands

swift run Pulse
swift build
./Scripts/bundle.sh
./Scripts/dmg.sh
./Scripts/check-localization.sh
swift test
./build.noindex/Pulse.app/Contents/MacOS/Pulse --json

xcode-select must point at Xcode, not CommandLineTools. #Preview is expanded by an Xcode plugin; otherwise every build fails with PreviewsMacros plugin not found. Check with xcode-select -p. One-off: DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer swift build.

Never strip #Preview blocks to make the build green. That hides errors inside them and has already shipped a broken build. See Docs/decisions/never-strip-previews.md.

A clean swift build is not the Xcode check. Actor-isolation mistakes can be warnings here and hard errors there (every View is @MainActor). Before claiming a change builds:

swift build

Treat remaining warnings as failures. macOS 14+, Swift tools 6.0, no linter. swift test exists — rules, cache reconciliation and provider fixtures; run it, and add to it when you change a rule. Docs/testing.md. CI and release need the macOS 26 SDK (glassEffect). The SDK version stamped into the binary decides which control design macOS draws — Package.swift sets it in linkerSettings because SwiftPM stamps the deployment target instead, and bundle.sh reads it back off every slice. Below 26 the app is silently drawn the old way. Docs/decisions/sdk-stamp-and-appearance.md

Do not violate

  • Panel frame while a card opens: do not resize the window and do not put card + rail in a shared stack. Axis change (side ↔ top) may resize. Docs/ui/panel-geometry.md
  • Hover: SwiftUI .onHover does not work on this accessory, non-key panel. Enter from tracking areas, leave from sampling the pointer — never exit events. Drag and ring clicks belong to FloatingPanel.sendEvent. hitTest / synthesised events are not proof of real input. Docs/ui/input.md
  • Percentages: Pulse does not invent usage percentages. If a provider reports none, say so. Labelled exceptions only, each marked as inferred on screen and each drawing nothing rather than a zero when its inputs are missing: the money estimate; Command Code's monthly plan grant (reported remainder, unreported plan size); and every API account that reports money and no allowance (BalanceRing, DeepSeek's rule first) — its denominator is one Pulse watched, one the reader typed, or none, and only the provider's own flag may call it spent. Docs/refresh-and-data.md, Docs/providers/command-code.md, Docs/providers/deepseek.md
  • Localization: only String.localized(_:) / Text(localized:). No implicit Text("…"). No conditionals inside localized:. Interpolate String, not Int (%lld vs %@). Run ./Scripts/check-localization.sh. Translations are written, not converted: no English syntax, no term the reader has no word for, and a control agrees with its own sub-settings. The script checks keys, not whether the copy reads. Docs/development.md
  • Notifications say nothing Pulse did not witness. spent only when the provider says so, a reset only on unambiguous evidence, an unavailable reading is not automatically a failure, and a push route going quiet (Claude Code's status line) is not one either. A limit already past the line when the setting goes on is announced, once — silence then a wall is the feature failing. All off by default, all silent. UNUserNotificationCenter raises without an app bundle — every entry point is fenced by UsageAlerts.isSupported, so test from ./Scripts/bundle.sh, never swift run. Docs/notifications.md
  • Disabled providers are not fetched. Shared Unavailability copy names no provider.
  • Layout constants are budgets (PanelMetrics computed var, never static let). Anything new on the panel takes size from them.
  • Do not fetch or document provider auth here. Docs/providers/README.md

Read by task

TaskRead
Shell, settings, login, defaultsDocs/architecture.md
Panel size, dock, overlay, scaleDocs/ui/panel-geometry.md
Drag, hover, clicks, hit testingDocs/ui/input.md
Glass, rings, colour, activity markDocs/ui/rings-and-surface.md
Settings window copy/layoutDocs/ui/settings.md
Refresh, cache, activity, ledgerDocs/refresh-and-data.md
Session monitor, PI-Desktop control port (fork)Docs/sessions.md
Token spend pane, agents, spend readersDocs/token-spend.md
Notifications, alert rulesDocs/notifications.md
What is tested, fixturesDocs/testing.md
--json output contractDocs/json-output.md
Developer integrations, account linksDocs/integrations.md
Localization, resources, adding UIDocs/development.md
Bundle, tag, Sparkle, DMGDocs/releasing.md / Docs/build-from-source.md
Why / failure lessonsDocs/decisions/README.md
Provider routes / extra accountsDocs/providers/README.md

Current facts (verify in code if they matter)

Seventy-seven built-in providers (Provider.builtIn) — twenty-five written case by case, fifty-two as ProviderProfiles under Providers/Profiled/ (Docs/providers/README.md) — plus .pulseExtension, which carries every user-added extension as an account (Docs/extensions.md). Extra accounts: Claude Code, Codex, Grok, Grok Bot (supportsMultipleAccounts). Adaptive refresh is a one-shot timer, 2–30 minutes (AdaptiveRefresh.floor 120s / ceiling 1800s) — not a 60s loop. Liquid Glass drag: historical “material swallows input” diagnosis is uncertain; current approach is a hit-testable PanelSurface plus window sendEvent. Real-input verification is not claimed. Settings still say to drag by a ring while glass is on.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.