Docs
Getting started
Vellforge is one menu bar app with add-ons. It lives behind a single icon in the menu bar; each add-on you switch on gets a section of its menu and a page in Settings.
- Download Vellforge.zip, unzip it and move Vellforge to Applications.
- Open it. Until Vellforge is notarised, macOS refuses the first time: open System Settings → Privacy & Security, scroll down and click Open Anyway.
- The welcome window lists the add-ons. Switch on the ones you want and click Continue.
- If an add-on needs a permission, Vellforge asks for it and shows why. Switch Vellforge on in the list System Settings opens; the add-on starts by itself a moment later.
Change your mind any time in Settings (⌘, from the menu). Opening Vellforge again from Finder or Spotlight also opens Settings. Turn on Launch Vellforge at login there so it's always running.
Snap
Window snapping and layouts. Needs Accessibility, because macOS only lets an app move another app's windows if you allow it. Snap uses it for nothing else.
Drag to snap
Drag a window to a screen edge and a preview shows where it will land. Edges give halves, corners give quarters, and the top edge maximises. Hold ⌃ while dropping for a third, or ⌃⇧ for two-thirds.
Drag toward the top of the screen and a layout chooser drops down with seven templates: full screen, halves, thirds, wide left, wide right, quarters, and main plus stack. Drop into any cell. It appears once the pointer is in the top fifth of the screen.
Shortcuts
The defaults match Rectangle and Magnet. Change any of them in Settings → Snap: click a shortcut and press the new keys. Delete clears it, Escape cancels.
| Move the window to | Shortcut |
|---|
| Left, right, top, bottom half | ⌃⌥← ⌃⌥→ ⌃⌥↑ ⌃⌥↓ |
| Top left, top right, bottom left, bottom right | ⌃⌥U ⌃⌥I ⌃⌥J ⌃⌥K |
| Left, centre, right third | ⌃⌥D ⌃⌥F ⌃⌥G |
| Left, right two-thirds | ⌃⌥E ⌃⌥T |
| Maximise, centre | ⌃⌥↩ ⌃⌥C |
| Next, previous display | ⌃⌥⌘→ ⌃⌥⌘← |
If another app already owns a combination, macOS won't give it to Snap. Settings says which ones, and the menu stops showing them so it never advertises a shortcut that does nothing.
The grid and Move Window
The Snap section of the menu has a 6 × 4 grid: drag across cells to put the window in any region, even one with no name. Move Window lists every command with its shortcut, which is the easiest way to learn them.
Saved layouts
Layouts → Save Current Layout… records where every window is. Restore it later, optionally reopening apps that aren't running. Windows have no identity that survives an app restart, so Snap matches them by app, then title, then order: a good guess, not a guarantee.
Limits
- Full-screen windows can't be moved. Leave full screen first.
- Some apps (Electron, JetBrains, Java) resize late or partly. Snap retries once, then leaves the window alone.
- The gap between windows is set in Settings → Snap.
Scroll
Scroll direction per device. Needs Accessibility, which is what macOS requires to change scroll events before apps see them. Scroll flips the direction and does nothing else with them.
What it does
macOS has one “natural scrolling” switch for every device. Scroll flips the mouse wheel, the trackpad, or both, and optionally left-right scrolling too. It only ever flips, so the result depends on the system switch as well, which is why the menu says what each device actually does (“Trackpad scrolls natural, Mouse scrolls traditional”). If that's not the usual arrangement, the menu offers a one-click fix.
How it tells devices apart
macOS doesn't label scroll events by device. What it does report, for a trackpad, is the gesture: when the fingers start, move, lift, and the momentum afterwards. A wheel never reports that, even a smooth or free-spinning one, so Logitech's MX mice and similar count as mice. A Magic Mouse scrolls by gesture, so it counts as a trackpad. Settings → Scroll shows which device your last scroll came from.
If nothing changes
- Check Accessibility is on for Vellforge in System Settings → Privacy & Security.
- On some Macs the built-in trackpad's events never reach Scroll, so inverting the trackpad may do nothing. Inverting the mouse always works.
- Make sure Vellscroll isn't still running. Both flipping cancels out.
- Settings → Scroll → Diagnostics… shows whether events are reaching it and what it did to the last one.
Bar
Hides menu bar clutter. Hiding needs no permissions at all. The two optional ones only add to it.
How it works
- Switching Bar on adds two icons at the right end of the menu bar, beside the Vellforge icon: a divider (☰) and a chevron.
- Click the chevron. Every icon to the left of the divider hides. Click again to show them.
- To keep an icon on show, hold ⌘ and drag it to the right of ☰. To hide less, ⌘-drag ☰ itself further left.
Right-click the chevron for a list of every item, and click one to open it even while it's hidden. The Vellforge icon and the clock always stay visible. On a MacBook with a full menu bar this is also how you get icons out from behind the camera notch.
Permissions
| Permission | What it adds |
|---|
| Accessibility | The list of menu bar items, and clicking one for you. macOS only shows other apps' items to apps you allow. |
| Screen Recording | Each item's real icon in the list. There is no other way to read them, so Bar photographs one strip of the menu bar while it's expanded. It never records continuously, never saves an image, never sends one anywhere. macOS applies this grant only after Vellforge restarts; Settings → Bar has a Relaunch button. |
Buttons
The clicks macOS leaves out. Needs Accessibility, to turn one kind of click into another. Buttons also counts the fingers on the trackpad; it keeps nothing.
Middle click from the trackpad
Rest three fingers on the trackpad and press: that's a middle click. It opens a link in a new tab, closes a tab when you click it, and pastes the selection in Terminal. Middle-dragging works too.
Optionally, a quick three-finger tap (no press) is a middle click as well. It's off at first because it's easy to do by accident. Three-finger swipes, such as Mission Control and switching Spaces, carry on working: a swipe moves, a tap doesn't.
Two macOS settings use the same fingers. If three-finger drag is on (System Settings → Accessibility → Pointer Control → Trackpad Options), three-finger click stands down, because it would break dragging. If Look up is set to a three-finger tap (System Settings → Trackpad), Settings → Buttons warns you before both happen at once.
Side buttons
Most mice have two buttons under your thumb. macOS passes them to apps but few apps listen, so Buttons turns them into back (⌘[) and forward (⌘]), which work in browsers, Finder, Xcode, Mail, the App Store and most other apps. If your mouse has them the other way round, swap them in Settings → Buttons. If your mouse's own software already maps them, Buttons never sees them and nothing changes.
Vellsnap, Vellscroll and Vellbar
Vellforge replaces the three separate apps, which won't get further updates. On first launch Vellforge finds any that are installed, then for each one you tick:
- copies its settings: shortcuts, drag options and saved layouts from Vellsnap, the scroll choices from Vellscroll, the divider's position from Vellbar
- quits it if it's running
- moves it to the Bin if it's in an Applications folder (a copy anywhere else is left where it is)
Vellforge never overwrites a setting you've already changed in Vellforge. Run it again any time from Settings → General → Bring Settings Over…. You'll need to allow Accessibility once for Vellforge: macOS treats it as a new app.
Updates
Vellforge updates itself with Sparkle, the standard Mac updater. About once a day it fetches one small file, vellforge.com/appcast.xml, and tells you when there's a new version. Nothing about your Mac is sent with it.
Every update is signed, and Vellforge refuses one that isn't. Switch automatic checks off in Settings → General, or check by hand with Check for Updates… in the menu. Releases are also on GitHub.
Troubleshooting
“Vellforge can't be opened” or “Apple could not verify it”
Vellforge isn't notarised yet. Open System Settings → Privacy & Security, scroll to the message about Vellforge and click Open Anyway. You only do this once.
I can't see the Vellforge icon
On a full menu bar, macOS hides the newest icons behind the camera notch and gives no sign that it has. Open Vellforge again from Finder or Spotlight: if it's already running, that opens Settings. From there, switch on Bar and ⌘-drag its divider to hide some icons and make room, or remove icons you don't need. With several displays, Vellforge's windows open on the display your pointer is on.
A permission is on, but the add-on still says it's waiting
macOS remembers permissions by the app's signature. If you replaced Vellforge with a copy built elsewhere, the old entry no longer matches. In System Settings, select Vellforge in the list, remove it with the minus button, then allow it again.
Launch at login doesn't stick
Move Vellforge to Applications first. macOS won't register a login item for an app in Downloads.
Sending a report
Settings → General → Diagnostics… shows a plain-text report of permissions, add-ons and what each is doing, with a Copy button. A copy is saved at ~/Library/Application Support/com.vellund.Vellforge/diagnostics.txt. Paste it into a GitHub issue or email hello@vellund.com.
Privacy
Vellforge has no account, no analytics and no crash reporting. Its one network request is the update check above. Downloads come from GitHub, which sees them like any download.
Accessibility lets Snap move windows, Scroll flip scroll events, Buttons change clicks and Bar read the menu bar; none of it is recorded or kept. Bar's menu bar pictures stay in memory and are discarded when the item disappears. The source is on GitHub, MIT licensed, so you can check all of this.