https://github.com/kl0sin/clyde
A friendly Claude Code session monitor for macOS. Real-time session tracking, attention alerts, multi-session view.
https://github.com/kl0sin/clyde
claude claude-code developer-tools macos menu-bar menubar-app native sparkle swiftui switft
Last synced: about 2 months ago
JSON representation
A friendly Claude Code session monitor for macOS. Real-time session tracking, attention alerts, multi-session view.
- Host: GitHub
- URL: https://github.com/kl0sin/clyde
- Owner: kl0sin
- License: mit
- Created: 2026-04-07T19:25:38.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-25T07:54:27.000Z (about 2 months ago)
- Last Synced: 2026-04-25T09:24:56.832Z (about 2 months ago)
- Topics: claude, claude-code, developer-tools, macos, menu-bar, menubar-app, native, sparkle, swiftui, switft
- Language: Swift
- Homepage: https://kl0sin.github.io/clyde/
- Size: 15.1 MB
- Stars: 4
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Roadmap: docs/roadmap.md
Awesome Lists containing this project
README
# Clyde
**A friendly Claude Code session monitor for macOS.**
Know what Claude is doing β without alt-tabbing.
[Website](https://kl0sin.github.io/clyde/) Β·
[Download](https://github.com/kl0sin/clyde/releases/latest) Β·
[Changelog](CHANGELOG.md)
[](LICENSE)
---
Clyde is a tiny SwiftUI menu bar app that watches every
[Claude Code](https://claude.com/claude-code) session running on your Mac
and shows you, in one glance, whether they're working, ready, or need
your attention.
It connects to Claude Code's native hook events, so updates are
**instant** β no polling, no lag, no missed permission requests.
## Features
- π’ **Real-time session tracking** β busy / ready / needs-input, fed by
Claude Code's native hooks. No polling.
- π **Attention alerts** β sound and macOS notification the moment
Claude asks for permission. Never miss a prompt again.
- π **Multi-session view** β every Claude session, every terminal, in
one expandable panel. Drag to reorder, name them, click to focus the
matching window.
- π **Activity timeline** β recent prompts, permissions and session
lifecycle, in plain language.
- π― **Menu bar capsule** β dominant state at a glance, with two ticks
for the other states.
- π€ **Snooze** β 15 / 30 / 60 / 120 minute mute when you need quiet.
- β¨οΈ **Global hotkey** β `ββC` to expand from anywhere.
- π **Self-installs the hook** β Clyde adds and self-heals its hook
script in `~/.claude/hooks/` so you never have to think about it.
- π **Privacy-first** β no telemetry, no network calls, no accounts.
Everything stays on your Mac.
## Install
Grab the latest `.dmg` from
[Releases](https://github.com/kl0sin/clyde/releases/latest), open it,
drag `Clyde.app` into your Applications folder, and launch it.
On first run Clyde offers to install its Claude Code hook automatically β
accept and you're done.
> **Early releases are not yet code-signed or notarized.** On first
> launch macOS Gatekeeper will say the app is "from an unidentified
> developer". Right-click `Clyde.app` β **Open** β confirm in the
> dialog. macOS remembers the exception, so subsequent launches are
> clean. Signing and notarization are on the roadmap and will land in
> a later release.
### Updates
Clyde ships with [Sparkle](https://sparkle-project.org/) built in for
in-app auto-updates. The update channel is dormant until signed
releases start publishing to the appcast β until then, grab new
versions from
[Releases](https://github.com/kl0sin/clyde/releases) directly.
## How it works
Clyde reads two things from your local file system:
- `~/.claude/` β to install its hook script and discover Claude Code's
settings.
- `~/.clyde/` β where the hook script writes per-session state files
that Clyde watches via FSEvents.
When you submit a prompt, Claude Code fires a `UserPromptSubmit` hook β
the hook script writes a `-busy` marker β Clyde sees it
within milliseconds and updates the UI. When Claude finishes, the `Stop`
hook removes the marker. Permission requests fire `PermissionRequest` β
Clyde rings a sound and shows the attention pill.
That's the entire architecture. No polling, no daemon, no privileged
helpers.
## Screenshots
**The expanded view β every Claude session at a glance.**
Hero header tells you the dominant state, the list shows each session
with its directory, and the activity bar at the bottom keeps a
running tally.
**The collapsed widget.** Floats wherever you drop it. The big number
is the dominant state count; the two ticks on the right show the
others. Click to expand, drag to move, hide entirely if you only want
the menu bar.
**The menu bar item.** Pixelβaccurate Clyde silhouette plus a colour
capsule for the dominant state β purple = working, green = ready,
blue = needs attention.
## Build from source
Clyde is a single self-contained Swift Package. No Xcode project,
nothing to configure.
```bash
git clone https://github.com/kl0sin/clyde.git
cd clyde
swift run Clyde
```
For a release build wrapped in a proper `.app` bundle:
```bash
scripts/release/build.sh
open build/release/Clyde.app
```
See [`docs/release-process.md`](docs/release-process.md) for the full
release pipeline (signing, notarization, DMG, appcast, GitHub Releases).
## Project layout
```
Clyde/ Main app source
βββ App/ NSApplicationDelegate, panel + menu bar
βββ Models/ Session, ClydeState, ActivityEvent
βββ Services/ ProcessMonitor, AttentionMonitor, hook installer, ...
βββ ViewModels/ App + session list view models
βββ Views/ SwiftUI views
βββ Resources/ clyde-hook.sh (the hook script that ships in the bundle)
βββ Assets/ AppIcon.icns (generated by scripts/generate-icon.swift)
ClydeTests/ XCTest test target
scripts/ Build + release tooling
site/ GitHub Pages landing page (deployed via Actions)
Casks/ Homebrew cask formula
.github/workflows/ CI: deploy-site.yml, release.yml
docs/ Pre-launch checklist + release process docs
```
## Tests
```bash
swift test
```
The suite is hermetic β `HookInstallerTests` redirects every path
through a throwaway temp home via `AppPaths.homeOverride`, so nothing
under your real `~/.claude/` is ever touched. Runs deterministically
across reruns on dev machines and CI alike.
## Contributing
Bug reports and PRs welcome. For non-trivial changes please open an
issue first so we can discuss the approach.
## Support development
Clyde is free and MIT-licensed. If it's saving you time and you'd
like to chip in, there are two ways:
- β€οΈ [Sponsor on GitHub](https://github.com/sponsors/kl0sin) β recurring or one-time, processed by GitHub.
- β [Buy me a coffee](https://www.buymeacoffee.com/kl0sin) β one-off tip, no account needed.
Both are entirely optional and there's no paid tier β Clyde stays
fully featured for everyone.
## License
[MIT](LICENSE) β use it, fork it, sell it, do whatever.
---
Built in SwiftUI with care by Mateusz KΕosiΕski.