diff --git a/README.md b/README.md index d8ac8950c..b98826a20 100644 --- a/README.md +++ b/README.md @@ -1,255 +1,83 @@ -

- - - Vorssaint logo - -

- -

Vorssaint

+

Claude sessions in your notch

- One menu bar icon doing the job of a dozen paid Mac apps.
- Install only what you use. + Every Claude Code session on your Mac, in the Dynamic Island.
+ Allow, answer and reply without switching to the terminal.

- Website · - Install · - Features · + What it does · + Set it up · + How it works · Privacy · - Changelog · - Contact · - Discord + About this fork

- Latest release - Downloads - CI status - macOS 14 and newer, Apple Silicon - License GPL 3.0 or later + Five Claude Code sessions working in the Dynamic Island, then a permission allowed, a question answered, a reply sent, a conversation enlarged, subagents at work and a Clawd getting a top hat

- - Buy Me a Coffee - + Watch it in 1080p

-

- For anything private, email - hello@vorssaint.com. -

+This is an unofficial fork of [Vorssaint](https://github.com/vorssaint/vorssaint-utils) that adds a Sessions section to its Dynamic Island. It is not affiliated with or endorsed by the Vorssaint maintainer. Everything in the video is the real app driving real Claude Code sessions, recorded on a MacBook. -

- vorssaint/vorssaint-utils | Trendshift - vorssaint/vorssaint-utils | Trendshift weekly ranking - vorssaint/vorssaint-utils | Trendshift monthly ranking -

+## What it does -

- Volume mixer with per app sliders, one app boosted past 100 percent - System tab with temperatures, usage graphs and memory pressure - Window controls with the app switcher and Dock features - Utilities with cleaner, Homebrew, media tools and clipboard -

- -Per app volume, a real system monitor, a better app switcher, window snapping, Dock previews, clipboard history, text snippets, a file shelf, an uninstaller. The utilities Mac users usually buy one by one, together behind a single menu bar icon, with no account, no telemetry and no subscription. - -## Install only what you use - -Choose individual features or start with a preset. Uninstalled features stop loading and disappear from the interface; reinstalling restores their settings. Setup asks only for the permissions your choices need. - -

- The Features hub in Settings, installing and uninstalling whole features -

- -Reorder or hide panel sections, choose a compact layout, and export settings to another Mac. The app supports more than a dozen languages. - -## Everything it does - -### Sound - -- **Volume mixer.** Set volume per app, boost quiet audio past 100%, and pin or reorder favorites. No audio driver required. -- **Per app output.** Play music through speakers while a call uses your headset. -- **Output switcher.** Switch audio outputs with a shortcut and lower the volume when headphones disconnect. -- **Microphone tools.** Choose a preferred input, adjust its level on supported devices, and mute all microphones with one shortcut. -- **Music app blocker.** Prevent unwanted Music launches after detected playback-button presses. Requires Accessibility. - -### Know what your Mac is doing - -- **System monitor.** CPU, GPU, memory, temperatures, battery health and power use, with history graphs and a view of energy-hungry apps. -- **Fan Control (beta).** Set manual fan speeds or temperature curves and monitor live RPM. -- **Menu bar readouts.** Put your chosen readings, usage bars, battery time or fan speed directly in the menu bar. -- **Network.** See live traffic, session totals and your local IP address, or run a speed test. -- **Alerts.** Get notified about sustained CPU load, high temperatures, memory pressure, low disk space or low battery. - -### Windows and the Dock - -- **App switcher.** Switch between apps and windows with live previews, search and display filters. A simpler mode works without screen capture. -- **Window layout.** Snap windows into layouts, move them between displays and restore earlier positions using shortcuts, screen edges or modifier-drag gestures. -- **Dock Preview.** Hover over Dock icons to preview windows across desktops. Switch, close, move or snap them from the preview. -- **Dock clicks.** Click an active app's Dock icon to minimize, hide or cycle through its windows. -- **Maximize windows.** Use the green button to fill the screen without creating another Space. -- **Fixed Space order.** Keep Spaces in the order you set instead of rearranging them by recent use. Turning it off restores your previous setting. -- **Quit on close.** Quit selected apps when their last window closes. -- **Quit and close protection.** Prevent accidental ⌘Q or ⌘W with a hold, double press or extra modifier, per app. - -

- The hold-to-confirm prompt showing progress below the Command-Q quit shortcut hint -

- -

- The window switcher showing live thumbnails of open windows -

+- **Every session at a glance.** Running sessions are listed beside the camera with their name, project, git branch and state: working, running a tool, waiting for permission, waiting for you, done or idle. Each project gets its own color, and a session that sat idle for a while fades out. +- **Allow from the island.** When Claude asks to run something, the island opens on its own with the whole command in view. Allow, Deny or Always, by click or with ⌘Y and ⌘N. +- **Answer Claude's questions.** Questions Claude asks with options show up as a card. Pick one, pick several, or write your own answer. +- **Reply without switching apps.** Type a reply in the island and it reaches the session in Terminal or Antigravity as if typed there. ⌘↩ sends, and ⌘V or a drop adds images. +- **Watch it work.** Enlarge a session's page to read the whole conversation as it grows, with recent tools, tasks, cost and the model beside it, or fold the details away. +- **Subagents too.** Agents a session starts get rows of their own, including the ones sent to the background, colored like their agent definitions. +- **A Clawd for every session.** Each session and subagent gets a pixel Clawd in a random costume. Open the wardrobe to change its shell, hat, eyewear and extras, or let Surprise me pick. -### Keyboard and mouse +## Set it up -- **Text snippets.** Expand short triggers into text with clipboard, date and time variables, or insert snippets from a searchable menu. -- **Smooth scrolling.** Give your mouse wheel a fluid glide with adjustable speed and response. -- **Pointer acceleration.** Disable mouse acceleration and restore your previous setting when turned off. -- **Linear scrolling.** Make every mouse wheel notch scroll the same number of lines, however fast the wheel spins. -- **Focus follows mouse.** Bring the window under the pointer forward after an adjustable pause. -- **Scroll direction.** Invert vertical and horizontal mouse scrolling independently of the trackpad. -- **Scroll sideways while holding a key.** Turn vertical wheel movement into horizontal scrolling while holding a chosen key. -- **Side buttons.** Use mouse Back and Forward buttons in Finder, browsers and compatible apps. -- **Mouse button shortcuts.** Assign keys to extra buttons and side wheels, or use button-drag gestures for Spaces and Mission Control. -- **Middle click.** Turn a three-finger trackpad press into a middle click. -- **Apps to leave alone.** Exclude chosen apps from mouse enhancements. -- **Extra click filter.** Ignore accidental rapid clicks from worn mouse buttons without delaying normal clicks. -- **Key debounce.** Filter repeated letters caused by a worn keyboard. -- **Super key.** Use Caps Lock or a right-side modifier as a shortcut combination, with a separate tap action and app exclusions. -- **Keyboard shortcuts.** Manage feature shortcuts in one place, including optional takeover of supported macOS shortcuts while a feature is active. +You need a Mac with Apple Silicon, macOS 14 or newer, the Xcode Command Line Tools and [Claude Code](https://docs.anthropic.com/en/docs/claude-code). -### Clipboard, files and links +1. Build and install it: -- **Clipboard history.** Search local text, image and file history, pin favorites, preview entries and paste with shortcuts. -- **Auto clear clipboard.** Clear the system clipboard after a delay, sleep or lock, while keeping saved history. -- **Paste as plain text.** Paste without formatting while preserving the original clipboard content. -- **Shelf.** Park files, text and links near your cursor while dragging, then drop or share them later. -- **Finder shortcuts.** Move files with ⌘X and ⌘V, rename with F2, or paste copied images as PNG files. -- **Clean URL.** Remove tracking parameters from links, manually or automatically. -- **Disk image installer.** Install an app from a mounted disk image and eject it, with optional download cleanup. + ```sh + git clone https://github.com/MF-DEEV/vorssaint-utils.git + cd vorssaint-utils + ./build.sh --dev --install + ``` -### Everyday tools + This installs a separate Developer build next to any official Vorssaint. Run only one of them at a time, or you get two islands. -- **Dynamic Island.** Keep music, notifications, calendars, timers, downloads and everyday controls around the camera cutout, or a simulated one on other Macs. Customize sections and shortcuts, with optional lyrics, a live equalizer, camera preview and file tools. -- **AI agents.** Follow Claude, Codex, OpenCode and GitHub Copilot in the Dynamic Island: plan limits and when they reset where available, tokens, API value, models, projects and live work, with a notice when a long task finishes. Codex's banked resets can be used from there too, and each extra Codex account (`CODEX_HOME`) can have a limits card of its own. Copilot uses local CLI/app session logs; its token totals update when shutdown metrics arrive, and aggregate API-value estimates use base rates. -- **Claude Code sessions.** See every Claude Code session running on your Mac in the Dynamic Island: its folder and branch, whether it works, runs a tool, waits on you or is done, its latest tools, tasks, subagents and cost. Answer its permission prompts with the whole command in view, pick an answer to the questions Claude asks, or write your own, jump to its Terminal tab or Antigravity window, and type a reply that reaches it as if typed there. Enlarge a session's page to read the whole conversation at a text size you pick and write a longer reply. Each session and subagent shows a pixel Clawd in an outfit drawn at random, which you can change from the session's page. Permission prompts and questions use opt-in Claude Code hooks; prompts and replies stay unread unless you turn on previews. -- **Command Bar.** Search apps, windows, files, clipboard history, snippets and app menu commands from one field. Calculate, convert units, find emoji or run saved scripts. -- **Quick panel.** Open a floating palette of favorite tools with ⌃⌘V. -- **Quick toggles.** Switch appearance, hide desktop icons, eject disks, empty the Trash, lock the screen and more. -- **Radial menu.** Open a customizable wheel of apps, files, shortcuts and tools around the pointer, with profiles and submenus. -- **Scratchpad.** Keep autosaved notes in tabs, with Markdown preview and export, in a floating window or Dynamic Island. -- **Cleaning Mode.** Lock keyboard input while cleaning, with a black screen or a small visible indicator. +2. In Settings, install the AI Agents feature from the Features hub, then turn on the Sessions section in the Dynamic Island settings. +3. In the Sessions settings, press **Install Hooks**. Hooks let the island show which tool runs and answer permission prompts and questions. They are added to `~/.claude/settings.json` next to your own, after a backup, and **Remove Hooks** takes them out again. +4. If you work in Antigravity, press **Install Extension** so replies can reach its terminals. For Terminal, macOS asks for Automation access the first time you send a reply. +5. Start `claude` in Terminal or Antigravity. The session shows up in the island. -### Capture and create +## How it works -- **Screen capture.** Switch between screenshots, recording, text recognition and color picking in one selector with a pixel magnifier. -- **Screenshot.** Capture an area, window, screen or scrolling page. Annotate, crop, redact, add backgrounds and watermarks, pin captures, send them through the Share menu or share an expiring link. -- **Screen recording.** Record with separate system-audio and microphone tracks. Trim, cut, add automatic zooms, blur private details and export video or GIFs, or share an expiring link. -- **Camera preview.** Check your camera in a floating mirror or Dynamic Island before a call. -- **Copy text from screen.** Recognize text offline from any screen area, or read a QR code. -- **Color picker.** Copy a screen color as HEX, RGB, HSL or SwiftUI code. -- **Media tools.** Compress and edit videos, batch-convert images, add watermarks, make GIFs and extract text, all locally. +The island reads the small records Claude Code keeps for each running session in `~/.claude/sessions`, then follows that session's transcript, subagents and tasks as they grow. Permission prompts and questions arrive through Claude Code's own hooks, which talk to the app over a local socket. Claude Code shows the same prompt in the terminal at the same time, and whichever answer comes first wins. With the app closed, Claude Code simply asks in the terminal as usual. -### App management - -- **App updates.** Check store apps, package-managed apps and supported developer feeds in one list. Install managed updates together or open an app's own updater. -- **Cleaner.** Remove caches, logs and app leftovers, manually or on a schedule. -- **Messaging downloads.** Review, organize or move messaging downloads to the Trash using retention rules. -- **Uninstaller.** Remove apps and review their related caches, preferences and helpers before moving them to the Trash. -- **Homebrew manager.** Search, install and remove formulae and casks without opening a terminal. -- **Port manager.** Find processes listening on network ports and stop them with Kill Process when installed. - -### Energy and display - -- **Keep awake.** Keep your Mac working on a timer, with the lid closed, or while selected apps, power or external displays are present. -- **Displays.** Control individual displays and brightness, with hardware control where supported, half or quarter steps for the brightness keys, optional extra dimming below a monitor's minimum, and software dimming as a fallback. -- **Extra brightness.** Use a MacBook Pro XDR display's HDR headroom to go beyond its normal maximum brightness. -- **Bluetooth on sleep.** Disconnect Bluetooth during sleep and restore it on wake only if Vorssaint turned it off. - -## Install - -With [Homebrew](https://brew.sh): - -```sh -brew install --cask vorssaint -``` - -Or grab the disk image from the [releases page](https://github.com/vorssaint/vorssaint-utils/releases) and drag Vorssaint into Applications. - -Builds are signed with an Apple Developer ID and notarized, so macOS opens them without a fuss and your permissions survive updates. - -## Uninstall - -With Homebrew: - -```sh -brew uninstall --cask vorssaint -``` - -To remove Vorssaint completely, including its settings and permissions: - -```sh -./Tools/uninstall.sh -``` +Replies are typed into the session's own Terminal tab, found by its terminal device, or into its Antigravity terminal through the extension. ## Private by default -Vorssaint is local-first, with no account, analytics or tracking. The network is touched only by things you can see: update checks, the speed test, Homebrew actions, optional online lyric lookup, temporary screenshot or recording links and feedback you explicitly send. The full story is in the [privacy notes](docs/PRIVACY.md). - -Permissions get the same treatment. Every one is optional, the app explains each in plain words, shows which features actually use it, and even tells you when a permission you granted is no longer needed by anything, with a shortcut to revoke it. +Nothing leaves your Mac. Prompts, replies, titles and commands stay unread until you turn on **Show previews**, which is off by default, and even then they are kept in memory only and cleared when you turn it off. The [privacy notes](docs/PRIVACY.md) list everything the Sessions page reads and writes, and the [permissions guide](docs/PERMISSIONS.md) covers the Automation access replies use. -

- The Permissions page showing what each permission does, which features use it, and an unused permission warning -

- -See the [permissions guide](docs/PERMISSIONS.md) for which features need access and what remains available without it. - -## What you need - -- A Mac with Apple Silicon -- macOS 14 Sonoma or newer - -### Build it yourself - -```sh -git clone https://github.com/vorssaint/vorssaint-utils.git -cd vorssaint-utils -./build.sh --dev # build the separate Developer variant -./build.sh --dev --install # install and launch it -``` +## About this fork -Xcode Command Line Tools are the only requirement. The [contributing guide](CONTRIBUTING.md) covers the layout and conventions. Official builds come only from the maintainer: the GPL covers the source, while the Vorssaint name, icon and look are covered by [TRADEMARKS.md](TRADEMARKS.md), so forks need their own identity. +The rest of the app is Vorssaint as it is upstream: volume mixer, system monitor, app switcher, window snapping, clipboard history, the Dynamic Island and much more. Its [README](https://github.com/vorssaint/vorssaint-utils#readme) describes all of it, and official builds come only from the [Vorssaint releases](https://github.com/vorssaint/vorssaint-utils/releases). -## When something misbehaves - -See [troubleshooting](docs/TROUBLESHOOTING.md) for launch problems, permissions and missing previews, or [support](SUPPORT.md) for help. - -## Documentation +This fork ships no builds of its own; you build it from source as above. The Vorssaint name, icon and look belong to its maintainer, as [TRADEMARKS.md](TRADEMARKS.md) explains. - [Privacy](docs/PRIVACY.md), what does and does not leave your Mac - [Permissions](docs/PERMISSIONS.md), every macOS permission in plain words - [Troubleshooting](docs/TROUBLESHOOTING.md), the common fixes - [Contributing](CONTRIBUTING.md), build, layout and conventions -- [Support](SUPPORT.md), where to get help -- [Security](SECURITY.md), how to report a vulnerability - -## Community - -Vorssaint went from first commit to the front of GitHub trending in three days, top of the Swift charts, and issues and pull requests have shaped every release since. Bug reports, feature ideas and translations are all welcome, starting from the [contributing guide](CONTRIBUTING.md). - -Vorssaint is free and will stay that way. If it earned its place in your menu bar, a star helps other people find it, and a [coffee](https://buymeacoffee.com/vorssaint) keeps the maintainer awake, with or without the Keep awake feature. - -## Acknowledgements - -- App icon designed by [@divisionseven](https://github.com/divisionseven) +- [Claude Code session notes](docs/claude-sessions-spike.md), what Claude Code exposes and how the island uses it ## License -[GPL 3.0 or later](LICENSE), copyright 2026 Vorssaint. The license covers the source code; the Vorssaint name, logo and look are covered separately in [TRADEMARKS.md](TRADEMARKS.md). +[GPL 3.0 or later](LICENSE). Vorssaint is copyright 2026 Vorssaint; the changes in this fork are copyright 2026 MF DEV under the same license.

- Made by @vorssaint + Fork by MF DEV · Based on Vorssaint

diff --git a/docs/assets/readme/claude-sessions.gif b/docs/assets/readme/claude-sessions.gif new file mode 100644 index 000000000..ac1403a91 Binary files /dev/null and b/docs/assets/readme/claude-sessions.gif differ