SidePanel is a native macOS floating browser panel built with SwiftUI, AppKit, and WebKit. It stays above other apps, supports pinned and hover-expanded modes, restores tabs and navigation state across relaunches, and keeps a compact browser surface available without taking over the desktop.
Current repository version: 0.1.7
- Keeps a floating browser panel visible above other windows with
NSPanel - Supports pinned mode, unpinned mode, and hover-to-expand bubble mode
- Restores tabs, active tab selection, and per-tab back/forward history
- Persists browsing history locally and exposes it from the toolbar
- Uses a minimal settings window for real app preferences only
- Applies adaptive fitting for narrow responsive pages inside the panel
- Registers global shortcuts through macOS Accessibility permission
- Runs as an accessory-style macOS app without a Dock icon or Cmd-Tab entry
- macOS 14 or later
- Xcode 15 or later if you want to open the package in Xcode
Build and run directly with Swift Package Manager:
swift build
./.build/debug/SidePanelThis launches a GUI process from your shell, so the terminal stays attached while the app is running. Stop it with Ctrl+C.
If you prefer Xcode:
- Open
Package.swiftin Xcode. - Select the
SidePanelexecutable target. - Build and run.
- Launch the app.
- Browse in the floating panel as usual.
- Use the pin control to keep the panel fixed open or collapse it into the circular bubble.
- Hover the bubble to temporarily expand the panel.
- Move away from the temporary panel to let it collapse again.
The toolbar includes:
- Back
- Forward
- Pin or unpin
- History popover
- Settings
- Add tabs from the
+button in the tab rail - Switch between tabs from the left sidebar
- Close the current tab with the global shortcut
- Restored tabs reopen with their saved navigation history
The current settings window is intentionally minimal. It contains:
General- Remember last session
- Homepage
- Default search engine
Appearance- Theme
- Sidebar width
- Transparency
Behavior- Auto-collapse delay
- Show on all spaces
Privacy- Clear browsing history now
- Clear history on quit
Shortcuts- Shortcut list
- Accessibility settings shortcut
Browsing history is not a settings tab. It is available from the toolbar history button.
| Shortcut | Action |
|---|---|
Cmd+Shift+S |
Toggle sidebar |
Cmd+Shift+N |
New tab |
Cmd+Shift+W |
Close current tab |
Cmd+Shift+[ |
Previous tab |
Cmd+Shift+] |
Next tab |
Cmd+Shift+L |
Focus address bar |
SidePanel uses Accessibility access for its global shortcuts.
On first launch:
- Run the app.
- Approve the macOS Accessibility prompt if it appears.
- If the prompt does not appear, open
System Settings > Privacy & Security > Accessibility. - Enable
SidePanel. - Relaunch the app if macOS asks for it.
swift testswift build -c release --product SidePanel./scripts/build_app_bundle.shThis creates:
dist/SidePanel.app
./scripts/build_pkg.shThis creates:
dist/SidePanel-<version>.pkg
./scripts/check.shThis script currently runs:
- version metadata sync
swift test- release build
- app bundle build
- installer package build
version.txt is the single source of truth for the app version.
To bump the version:
./scripts/bump_version.sh 0.1.8That updates:
version.txtSources/SidePanel/App/Info.plist
The current settings window also shows the runtime version and build type.
Local builds use ad-hoc signing by default.
For Developer ID signing and notarization, provide the following environment variables:
CODESIGN_IDENTITYPKG_SIGN_IDENTITYAPPLE_IDAPPLE_TEAM_IDAPPLE_APP_SPECIFIC_PASSWORD
Manual notarization command:
./scripts/notarize_pkg.sh dist/SidePanel-$(cat version.txt).pkgTo enable the repository-managed pre-commit hook:
./scripts/setup-git-hooks.shThat wires .githooks/pre-commit so commits run the repo quality gate before they land.
Workflow: .github/workflows/ci.yml
- runs on pushes to
mainandmaster - runs on pull requests
- executes
./scripts/check.sh - uploads
dist/*as an artifact when available
Workflow: .github/workflows/release.yml
- runs on pushes to
mainandmaster - also supports manual dispatch
- only creates a release automatically when
version.txtchanged on that push, or when manually dispatched - skips release creation if the corresponding tag already exists
When a release is created, the workflow:
- runs
./scripts/check.sh - zips
dist/SidePanel.app - optionally notarizes the installer if Apple credentials are configured
- creates SHA256 checksums
- tags the repo as
v<version> - publishes a GitHub release with the
.pkg,.zip, and checksum file
The app currently stores data locally:
- open tabs in SwiftData
- session and window state in app preferences
- browsing history in app preferences
- user settings in
UserDefaults
Sources/
SidePanel/
App/
Data/
Tabs/
UI/
Components/
Settings/
Views/
Utils/
Web/
Window/
Tests/
SidePanelTests/
Assets/
AppIcon/
docs/
screenshots/
MIT



