spacebar

Quick Look for every file. Press Space.

spacebar is a free, open-source replacement for Quick Look on macOS 13 and later (Apple silicon and Intel). Space in Finder opens Markdown, folders, code, JSON, YAML, logs and archives in spacebar. Turn on Use spacebar for every file, which is optional and needs Accessibility, and Space opens any file in a spacebar window that stays open: photos and camera RAW, PDFs, video, CSV and the rest. It aims to be the best Quick Look, not an IDE.

• Every file, one window. PDF, HEIC and RAW, video, CSV tables, JSON trees, zips without unzipping, Markdown, and the folder beside them.
• One press. Space opens a window that stays open, resizes, goes full screen, and sits in the Dock and ⌘Tab; ⌘W closes it.
• Find, copy, edit, privately. ⌘F, Copy and Raw; a click edits text, code and data in place. Sandboxed, no telemetry, MIT.

Download spacebar.dmg, open it, drag spacebar to Applications and open it once. Or paste this in Terminal:

curl -fsSL https://spacebar.patebryant.com/install.sh | sh

Then select a file or folder in Finder and press Space. Install has the details.

Markdown is rendered properly (tables, task lists, highlighted code, math and Mermaid diagrams, in six themes), and Obsidian vaults read as they do in Obsidian. Word, Keynote and other Office and iWork files show in Apple's own preview inside spacebar's window. Apps and packages stay with Apple's Quick Look, and ⌘Y still opens it.

Guides: Markdown in Quick Look, folder preview, Obsidian vaults, HTML files, Mermaid, CSV, HEIC and RAW photos and every file type.

What Space opens in spacebar

In Finder, Space opens spacebar for Markdown, folders, code and scripts, JSON, YAML, XML, TOML, property lists, logs, archives, disk images (.dmg), and files with no extension (a Dockerfile, a CHANGELOG, a dotfile). The full list is scripts/quicklook-types.txt.

Unless you turn on Use spacebar for every file, plain text, rich text, HTML, CSV, PDF, images, video and audio keep Apple's own preview in Finder: Quick Look never hands a file of those types to another app's extension, so spacebar cannot take them. Inside spacebar's sidebar every one of them opens, as the table below shows. Another installed app that claims one of spacebar's types (a Markdown or code previewer) may still win it: install.sh lists the ones it finds and how many of spacebar's types each claims, and Settings lists each one that is on with a Turn Off button.

What spacebar shows for each file in the sidebar, and, with Use spacebar for every file on, for each file you press Space on in Finder:

File	Shown as
Markdown (.md, .markdown, .mdown, .mkd, .mkdn)	rendered, with inline editing and task toggles; Raw shows its source, read only
Images (.png, .jpg, .gif, .webp, .bmp, .ico, .svg)	fitted to the window, its dimensions and zoom in the toolbar; a double-click (or, in Quick Look, a two-finger double tap) toggles fitted and actual size, a pinch zooms about the pointer in Quick Look, two fingers or a drag move it, ⌘+ ⌘− ⌘0 zoom and fit; SVG as an image only
HEIC, AVIF, TIFF, camera RAW (.dng, .cr2, .cr3, .nef, .arw, .orf, .raf, .rw2), Photoshop (.psd), OpenEXR, TGA, JPEG 2000, icons (.icns)	decoded by macOS's own ImageIO and drawn natively, turned as the camera recorded it, with the same fit, zoom and pan
PDF	drawn natively by PDFKit, fitted to its width, pages in one scroll
HTML (.html, .htm)	rendered in its own web view: with its scripts and web content unless it was marked as downloaded, with neither when it was (see below)
Video (.mp4, .m4v, .mov, .3gp, .mpg, .mpeg, .m2v)	played by AVKit, paused on its first frame until you press play
Audio (.mp3, .m4a, .m4b, .aac, .wav, .aif, .aiff, .flac, .caf, .amr)	the same player, under the file's artwork or icon
Code and config (.js, .ts, .tsx, .py, .rb, .go, .rs, .swift, .sh, .c, .java, .kt, .css, .xml, , , , , and more)

The Open button in the toolbar opens Markdown in your editor (Settings: Open files in). Code, JSON, CSV and text open there too. The button always says just "Open" (or "Reveal" where only Finder may show the file), so it stays in place as you move from file to file; its tooltip names the app, such as "Open in Visual Studio Code". A script (.sh, .py, a .command) opens in the editor as text and is never run; with Default App chosen it opens in your default text editor, never in Terminal or an interpreter. Files that often hold secrets (.env, .npmrc) are shown but never offered to another app; a .env can be edited in place.

The chevron beside Open (Unreleased, 0.4) lists the other apps that open the file, its default app first, at most 12. It offers what Open allows and no more: nothing for a script, an app or an executable; beyond the default app, never a terminal or script runner, a web browser, an office suite or an app outside the Applications folders, and for a text file only text editors.

In a Space window (Unreleased, 0.4), drag a file's row in the sidebar (a Contents search result too), the overview or the grid, or its kind in the toolbar, into Finder, Mail, a chat or an editor to hand it the file, as a drag from Finder would; Finder copies it. A file inside an archive is not on disk and does not drag. Quick Look's own window does not offer this. .diff and .patch files and Markdown diff fences are tinted line by line: added lines green, removed lines red, hunk headers dimmed.

Text over 2 MB shows its first 2 MB; a CSV or TSV table reads up to 16 MB, and one over 2 MB is shown but not edited. WebM, Matroska, Ogg, Opus and AVI files, which macOS cannot play, get the info card and a note saying so. A link that loops or leads nowhere is listed greyed in the sidebar, and Space on one says it can't be opened. An archive lists its first 5,000 entries, and says how many it holds. Images over 50 MB, and PDFs, video and audio over 512 MB, get the info card.

Editing. With Edit text in the preview on (the default; Settings, Advanced; one setting for everything), a click on the text of Markdown, code, text, JSON, CSV or TSV, YAML, TOML, XML, an INI or .conf file, or dotfile config (.env, .env.local, .gitignore) puts the caret there, and every change is saved as you type. Markdown is edited a block at a time; other files as a whole, highlighted as you type (plain while you type in files over 24 KB, highlighted again when the edit ends). A file is saved in the encoding and with the byte order mark it was read with, and keeps its CRLF or LF line endings and its last newline; a character the encoding cannot hold is not saved (the preview says which), and nothing is ever converted to UTF-8. Files over 2 MB, shown cut, a binary property list, text read with invalid bytes, and anything spacebar does not show as text are never editable, and nor are files the shell, git, npm or launchd run on their own (shell profiles such as .zshrc, .gitconfig, .npmrc, .command scripts, git hooks, LaunchAgents). JSON, CSV and the other formatted views are edited through Raw, which lasts while the preview stays open. While you edit, the toolbar says so (Esc finishes) and ticks after each save. ⌘Z undoes typing, and past the start of an edit it goes back to the text before the last edit, Enter or Backspace that split or joined blocks, or task tick, for as long as the file stays open; once an edit has ended, the toolbar's Undo does the same. A change on disk while you edit ends the edit; if it displaced text that was not saved, a banner keeps that text until you choose Use Disk Version, Copy My Text or, for Markdown, Keep Mine.

The preview sits in a thin outlined page under a toolbar row: the sidebar button and the path on the left, Aa and Open on the right, and beside them, in quiet text, the file's kind and size (an image's zoom too), so a PDF or an image fills the page under the row. Word count and reading time are off unless stats is on in settings.json; with them on, a Markdown file shows its words and a code file its lines there too. minimalChrome in settings.json goes back to floating buttons over the page.

Copy, Find and Raw

Copy sits at the bottom right of the page; Find and Raw are icon buttons beside Aa, each shown where it applies and keeping its place in the toolbar where it does not. A button with a key gives it in its tooltip.

• Copy puts the file's text on the clipboard: a Markdown file's source, a table's CSV, JSON as it is on disk (the first 2 MB of a larger file, as shown). Not offered for images, PDFs, media or archives. The page keeps clear of it, so it never covers a line, and "Copied" is announced to VoiceOver.
• Find searches the file on screen: Markdown, code, text, JSON and CSV, as each is shown. Matches are highlighted and counted; ↵ and ⇧↵ (or ⌘G and ⇧⌘G) go to the next and previous, Esc closes the bar. A long table and a JSON tree are searched whole, not just the rows drawn: a match in a collapsed branch opens it. At most 10,000 matches are counted.
• Raw switches a formatted view to the file as it is: Markdown to its source (read only), JSON and a notebook to their text, a table to its CSV, XML and a minified stylesheet to the file unindented. It lasts while the preview stays open. Minified JavaScript is shown as it is: there is no formatter for it.

Keys

Quick Look gives a preview no keys of its own. There these work while spacebar holds the keys: its sidebar list takes them as a preview opens (sidebarKeys in settings.json), and the filter and find fields hold them while you type. In a Space window (Use spacebar for every file, below) they work once you click into it. The buttons work in both.

Key	Does
⌘F	Find in the file
⌥⌘F	The sidebar's filter (a click in the field works too)
↵, ⇧↵, ⌘G, ⇧⌘G	In the find field: the next and previous match
Esc	Closes the find bar, clears the filter, or gives the keys back
⌘C	Copies the selection, or with nothing selected the whole file's text. In a Space window it copies the file too, as Finder's ⌘C does: paste in Finder for the file, in an editor for the text (an image, a PDF or another file: the file)
↑ ↓ ← → Home End ↵	Move through the sidebar, or through a folder's grid (↵ opens the picture)
← or ⌫	Back to the grid from a picture opened in it, or to the archive from a file inside it
⌘O	Open, in a Space window
⌘+ ⌘− ⌘0	Zoom

Use spacebar for every file

Quick Look hands spacebar only the types above. Turn on Use spacebar for every file (Settings, or the second step of the welcome sheet) and Space in Finder opens spacebar for any file you select, in a spacebar window with the same sidebar:

You press Space in Finder on	Without it	With it
Markdown, folders, code, JSON, YAML, XML, logs, archives, .dmg, files with no extension	spacebar, inside Quick Look	a spacebar window
Plain text, CSV, HTML, rich text (.rtf)	Apple's preview	a spacebar window (HTML with its scripts off)
PDF, images (HEIC and camera RAW too), video, audio	Apple's preview	a spacebar window
Office, iWork saved as a single file, fonts, 3D, certificates, calendars, e-books	Apple's preview	Apple's preview, inside a spacebar window
Installers and binaries as single files (.pkg, .mpkg, .exe, .dylib)	Apple's preview	spacebar's info card
Apps and other packages, iWork documents saved as packages, .rtfd packages	Apple's preview	Apple's preview: spacebar declines them and hands the Space back to Finder
Several files at once	Quick Look, one at a time	a spacebar window, with a sidebar of just those files

With it on:

• Space opens an ordinary app window: it is in the Dock and ⌘Tab, resizes, goes full screen with the green button, and stays open when you switch apps.
• Space on another file opens another window, as Finder does. Space on a file whose window is already open brings that window forward.
• New windows cascade from where you last left one on that display.
• The newest window follows Finder's arrow keys until you click into it. After that its keys are its own.
• While a window still follows Finder, Esc, ⌘W or ⌘. pressed in Finder close it. Once you have clicked into it, ⌘W or the red button closes it, and Esc does not.
• Space in a rename or the search field, with Apple's Quick Look already open, or in any other app is left alone. ⌘Y still opens Apple's Quick Look. A Space spacebar cannot answer within 150 ms is handed back to Finder.
• While a password field or another app has secure input on (Terminal's Secure Keyboard Entry, say), macOS gives spacebar no keys, so Space opens Apple's Quick Look; Settings shows the Space helper as Paused and names the app holding secure input.

What it asks macOS for

It works through the Space helper, a small app inside spacebar that macOS lists as spacebar Helper. Turning the setting on asks for two things, one after the other:

• Accessibility (System Settings, Privacy & Security, Accessibility: turn on spacebar Helper). This lets the helper notice a Space pressed in Finder and read which files are selected. It sees your key presses while it runs, but acts only on a plain Space in Finder and, while the newest window still follows Finder, on Esc, ⌘W and ⌘. pressed in Finder, which close that window. Every other key, the arrows included, goes to Finder or to the window you clicked into. It never records what you type, and no character you type leaves it.
• Running in the background (System Settings, General, Login Items & Extensions: spacebar, under Allow in the Background). macOS starts the helper at login and keeps it running.

The helper never opens a file. A separate viewer does, sandboxed like the Quick Look extension, and the first time it shows a file in Documents, Desktop, Downloads or iCloud Drive macOS may ask whether spacebar may access that folder. Settings shows whether the Space helper is on, waiting for Accessibility, blocked in Login Items, or paused by secure input. While the setting is on but the helper is not taking Space, the first Quick Look preview that spacebar draws says why in one quiet line, once (a click opens Settings). SECURITY.md has how the privileges are split.

Turning it off

Turn off Use spacebar for every file in Settings. The helper stops and leaves Login Items, and Space in Finder is Quick Look's again. Its Accessibility entry stays, unused, until you remove it in System Settings or uninstall spacebar, which removes it for you.

Default app

spacebar can also be the app a double-click opens, for Markdown, images (PNG, JPEG, HEIC, GIF, WebP, TIFF, SVG) and data files (JSON, YAML, CSV, logs and property lists). Choose which in Settings, Default App, or in the welcome sheet. The window's Open button never sends a file back to spacebar: Markdown and data files go to the editor chosen in Settings (else a text editor), and images to the app chosen there (else your other default image app, or Preview).

Folders and Obsidian vaults

Press Space on any folder. It opens on its own README (or an index or Home note, as a vault has) when the folder holds one at its top level, and otherwise on an overview of the folder (Unreleased, 0.4: it no longer opens a note found deeper down): how many folders, notes, images, PDFs and other files it holds (counted at most 3 folders deep and 5,000 items, never inside hidden folders, node_modules or packages), then the folder's own files and folders as a list with their sizes and dates, each a click away.

A folder mostly of pictures (at least six files, 60% or more of them images or videos) opens on a grid of thumbnails instead, like Finder's gallery, even when it has a README (Unreleased, 0.4). The arrows move through the tiles in two directions and Return or a double-click opens the picture; the buttons at the top right of the folder view switch between the grid and the list, and spacebar remembers the choice for folders of pictures and for every other folder. Only the tiles on screen are drawn, so a folder of thousands of pictures opens as fast as a small one.

App bundles and other packages, the top of a volume and system folders (/System, /Library, /usr and the like, and ~/Library) keep Quick Look's usual preview. Click the folder's name at the top of the sidebar, or the first step of the breadcrumb, to see its overview again; the breadcrumb's other steps open that folder in the sidebar. A picture opened from the grid has a Back button, and ← or ⌫ go back to the grid too. Folder previews are on by default; "folderMode": false in settings.json turns them off.

The sidebar lists a folder as Finder does: by name, folders among the files, unless Finder's own Keep folders on top (Finder › Settings › Advanced) is on, and hidden files while Finder shows them (⇧⌘.). The sidebar's sort menu can sort by date modified instead and keep folders first whatever Finder does; "folderReadmeFirst": true in settings.json puts a README at the top.

While the sidebar shows, it takes the arrow keys as soon as the preview opens, so they move through spacebar's list rather than Finder's selection: ↑ and ↓ move through the files and open each one in spacebar (a CSV or an image too, which Quick Look would otherwise show in its own previewer), → and ← open and close folders, Home and End jump to the ends and Return opens the file or folder under the cursor. Esc or Space gives the keys back to Quick Look without closing the preview (the preview cannot close Quick Look), and the preview says so: press Space or Esc again to close it. A click in the document gives them back too, and a click on a row takes them again. With the sidebar collapsed, or sidebarKeys off in settings.json, the arrows stay with Finder and Space closes the preview at once. Click the filter field at the top and type to narrow the tree to names that match (letters in order, so rdme finds README.md), in every folder under it, opened or not, and past a folder's first 5,000 files (Unreleased, 0.4); ↑, ↓, Home, End and Return still work while you type, and Esc clears the field, then goes back to the list. A folder that matches shows what it holds.

Search the text of the files (Unreleased, 0.4). Names | Contents under the filter switches it to Contents, for as long as spacebar stays open: type two or more characters and the list becomes the files whose text holds them, each with its folder, how many times it matches and the first matching line. Matching ignores case and is plain text, never a pattern. The files searched are the Markdown, code, JSON, CSV and text files the sidebar lists, in every folder under it (open or not), with hidden files only when the sidebar shows them; dependency and build folders (node_modules, .build, Pods and the like) are skipped, as are binary files and files iCloud has not downloaded. Each file is read to its first 2 MB, the whole search to 64 MB and 2 seconds, and at most 500 files are listed; a search cut short says how far it got ("Found in 12 files · 300 of 900 searched"). Every keystroke starts a new search. Opening a result, by a click or the arrows, runs Find (⌘F) in it for the same text, on its first match (in rendered Markdown, text that is only in the markup, such as a link's address, is not on screen to find; Raw shows it).

In a vault (a folder with .obsidian in it), and in any other folder:

• [[Note]], [[Note|alias]], [[folder/Note]] and [[Note#Heading]] open that note in the preview. A name is looked for anywhere under the folder the sidebar shows; a link that matches nothing is greyed out.
• ![[image.png]] (![[image.png|300]] for a width) shows the image; ![[Note]] shows the note inline, read only, one level deep.
• > [!note] Title callouts (note, tip, warning, danger, example, quote and the rest) are drawn as boxes, and #tags as pills.
• A note you press Space on inside a vault shows the whole vault in the sidebar, so its links reach every note.
• .obsidian is hidden, like every hidden file, unless Finder shows hidden files or you turn them on in Settings › Advanced.

spacebar.patebryant.com

Settings

Open spacebar to change its settings. The window holds only what most people change:

• Appearance: the theme, Automatic, Light or Dark, and the text size. The preview's Aa button changes these too, with the font and page width.
• Space Helper: Use spacebar for every file, and whether the Space helper is running.
• Open files in: the editor the preview's Open button uses.
• Default App: which of Markdown, images and data files spacebar opens on a double-click, and the app the Open button uses for images.
• About: the version, with Check Now; Check for updates, Report a Problem… and Uninstall spacebar….

Anything wrong with the setup (spacebar turned off in Quick Look, another app's previewer claiming its types, folder previews off in System Settings, an unreadable settings file) shows at the top while it is wrong; otherwise a quiet row there says Quick Look is on, for files and for folders.

Advanced, closed until you open it, holds scripts in HTML files, HTML in Markdown and remote images; editing in the preview and checking off tasks; hidden files in the sidebar; a custom theme and custom.css; and the settings file with Reset to Defaults…, which puts every key back, including the ones below, and leaves Use spacebar for every file as it is.

Everything else is a key in ~/Library/Application Support/spacebar/settings.json, which takes effect as soon as it is saved. spacebar keeps the file's "version" up to date; in a file you write yourself or link from elsewhere, set "version": 5, or an older version's defaults are applied to it (stats and folderReadmeFirst are read as off):

Key	Default	Values
bodyFont	"system"	"serif", "rounded", "mono"; also in the Aa button
width	"medium"	"narrow", "wide", "full"; also in the Aa button
monoFont	"system"	"menlo", "monaco", "courier"
lineHeight	1.6	1.2 to 2.0
codeTheme	"auto" (match the theme)	"apple", "github", "paper", "solarized", "nord", "contrast"
minimalChrome	false	floating buttons instead of the toolbar row
stats	false	word count and reading time
toc	"auto"	"on", "off"
frontMatter	"table"	"hide", "raw"
math, mermaid	true
mdLinks	"preview"	"editor" opens Markdown links in your editor
imageAppBundleID	null	the bundle ID of the app the Open button sends images to; also in Settings, Default App
folderMode	true	folder previews
foldersFirst	"finder" (Finder's own setting)	"always", "never"; also in the sidebar's sort menu
folderReadmeFirst

Install

Download spacebar.dmg from the latest release, open it, drag spacebar to Applications, and open spacebar once from there. Unless spacebar is also in ~/Applications, that first launch turns its Quick Look extensions on (or leaves them as you last set them). Or run the install command, which installs into ~/Applications and needs no administrator password:

curl -fsSL https://spacebar.patebryant.com/install.sh | sh

Then select a file or folder in Finder and press Space.

Either way there is one copy, and the install command, the Update button and the uninstaller all work on it: ~/Applications/spacebar.app, or /Applications/spacebar.app when that is the only one. An account that cannot change the copy in /Applications (one an administrator put there, seen from a standard account) is told so, and nothing is changed.

curl -fsSL fetches the script: -f stops on an HTTP error instead of passing an error page to the shell, -s hides the progress bar, -S still shows errors, and -L follows redirects. sh runs it: the script is plain POSIX sh, which every Mac has (/bin/sh is bash in POSIX mode), so it runs the same whatever your login shell is.

spacebar is notarized: from v0.3 every release is signed with an Apple Developer ID, checked by Apple's notary service and stapled, and the release fails if Apple refuses it. A copy downloaded in a browser opens as any notarized app does. The install command checks the release's SHA-256 before it changes anything.

Read scripts/install.sh before you run it. It:

1. refuses to run as root (no sudo), checks for macOS 13 or later, and picks the copy to update: ~/Applications/spacebar.app, or /Applications/spacebar.app when that is the only one. It stops here if this account cannot change a copy in /Applications, or if the copy, or a .spacebar.app.new or .old beside it, is a link;
2. downloads spacebar.zip and spacebar.zip.sha256 from the latest release (or SPACEBAR_VERSION=vX.Y.Z) through github.com/patebry/spacebar/releases/latest/download/, with no GitHub API calls, and stops unless the SHA-256 matches;
3. copies the new app beside that copy, or into ~/Applications for a first install (no sudo);
4. if there is a copy, quits it and its Quick Look extensions (the helpers that save edits first, so a save in flight finishes), unregisters them, moves it aside, moves the new copy into its place, quits the Space helper's viewer the same way, and only then deletes the old one (it is put back if the move fails). Nothing else is deleted;
5. registers it with lsregister and pluginkit, turns the preview on, turns folder previews on unless you turned them off, and resets Quick Look (qlmanage -r). If the Space helper is registered, it registers it again in the background, which takes about 15 seconds (macOS refuses a replaced helper until then; it retries for up to 10 minutes), logged to ~/Library/Logs/spacebar-helper.log. Opening spacebar's settings does the same when the helper is not answering;
6. lists other Quick Look extensions that are turned on and claim file types spacebar previews (QLMarkdown for Markdown, a syntax highlighter for code), with how many of spacebar's types each claims by kind, says how to turn them off, and warns if there is a second copy of spacebar in /Applications. It never turns off or deletes anything itself.

install.sh --help lists its options, including --dry-run, which downloads and verifies but changes nothing. Options go after sh -s --, and a variable goes before sh, not before curl:

curl -fsSL https://spacebar.patebryant.com/install.sh | sh -s -- --dry-run
curl -fsSL https://spacebar.patebryant.com/install.sh | SPACEBAR_VERSION=vX.Y.Z sh

Updates

Once a day spacebar asks GitHub for the latest release's version number, and nothing else (turn this off in Settings: Check for updates; Check Now in Settings asks at once). A newer version shows as an Update button in the preview's toolbar; it runs the app's own sealed copy of install.sh for that version, which downloads and checks the release exactly as above. The preview closes briefly while the installer replaces the extension; press Space again after. An edit in progress is saved first, and no edit, task toggle or sidebar filter starts while the update runs. The installer's output goes to ~/Library/Logs/spacebar-update.log.

The release zip is built by GitHub Actions from the tagged commit. From v0.3 releases are signed with spacebar's Apple Developer ID, so every release has the same signer and an update does not make macOS ask again about the extension's data (why). v0.1.1 to v0.2.2 were signed with a self-signed "spacebar Release" certificate and v0.1.0 ad-hoc, so the first update from one of them may show one prompt. Releases after v0.1.0 also carry a build provenance attestation, which the GitHub CLI checks:

gh attestation verify spacebar.zip -R patebry/spacebar

Uninstall

curl -fsSL https://spacebar.patebryant.com/uninstall.sh | sh

This stops the Space helper (its launchd agent, then the helper, the viewer and the viewer's writer), resets the Accessibility permission the helper had and every permission the viewer had, unregisters spacebar's Quick Look extensions and deletes ~/Applications/spacebar.app and /Applications/spacebar.app, whichever are there, which takes its Login Items entry with it. A copy this account cannot delete is left in place, and named. Uninstall spacebar… in Settings runs the same script from inside the app (not while an update runs), after removing the helper from Login Items. Both quit spacebar's Quick Look extensions first. To also delete your settings and themes in ~/Library/Application Support/spacebar and the helper's log in ~/Library/Logs:

curl -fsSL https://spacebar.patebryant.com/uninstall.sh | sh -s -- --purge

macOS asks before one app deletes another's sandbox container, so the uninstaller lists the containers spacebar leaves in ~/Library/Containers (md.spacebar.preview, md.spacebar.preview.folders, md.spacebar.viewer) for you to delete in Finder.

Build from source

Requirements: macOS 13+ and the Xcode command-line tools (xcode-select --install); the full Xcode app is not needed.

git clone https://github.com/patebry/spacebar.git
cd spacebar
./build.sh              # build, sign, install to ~/Applications and register
./build.sh --no-install # build into build/spacebar.app only

build.sh signs with the identity named in an untracked .sign-id file, else the first code-signing identity in your keychain, else ad-hoc (SIGN_ID=- forces ad-hoc). A stable identity keeps macOS from asking again about the extension's sandbox container after each rebuild. Other options are documented at the top of the script.

Tests that run off screen, without Quick Look (the test builds target Apple silicon):

for t in settings scheme linkpolicy cas dataless editkeys filterkeys pdfpane htmlpane mediapane qlpane imagepane diskimage richtext encoding archive claims rivals updates report welcome settingswindow movetoapps helper helperlink viewerlatency bigfiles; do test/$t/run.sh; done
python3 test/webcheck.py && python3 test/webthemes.py && python3 test/remoteimages.py && python3 test/htmlscripts.py && python3 test/sidebar.py

The other scripts in test/ drive real Quick Look windows and synthetic input; run them on a machine you are not using. test/helper_live.command is a checklist for the Space helper in Finder: you press the keys, and it grades each step from the helper's and viewer's logs. It sends no input itself.

How it works

spacebar.app                         settings window (SwiftUI)
└─ PlugIns/SpacebarPreview.appex     sandboxed Quick Look preview: WKWebView + markdown-it, KaTeX, highlight.js,
   │                                 Mermaid, DOMPurify, all bundled; no network code of its own
   └─ XPCServices/…writer.xpc        small unsandboxed helper: saves edits, opens links and files, owns the key panel for
                                     inline editing and the sidebar's keys, lists archives, checks for and starts updates
└─ PlugIns/SpacebarFolders.appex     the same preview for folders (on by default; turn off in Settings)
└─ Helpers/spacebar Helper.app       "Use spacebar for every file": a launchd agent with Accessibility and an event tap; reads
   │                                 Finder's selection, never a file; no sandbox, no entitlements
└─ Helpers/spacebar Viewer.app       the windows it opens: the same preview code, sandboxed like the extension, with its own writer

Quick Look extensions never receive key events, so inline editing (Markdown and text files alike) uses a click-through, non-activating panel owned by the writer service; Finder stays in front. Saves are compare-and-swap: if the file changed on disk, the external change wins. FINDINGS.md has the details and measurements.

Privacy and security

• No analytics, telemetry or accounts. The one request spacebar makes on its own is the daily update check: GitHub's latest release, of which only the version number is read (off in Settings). Report a Problem (Settings) opens a new GitHub issue in your browser with your versions, Mac model and the end of the update log filled in; nothing is sent unless you submit it there. Settings are a JSON file in ~/Library/Application Support/spacebar.
• Remote images are off by default (fetching one tells its server when you opened the document). A blocked image offers a one-time load for that document.
• A Markdown file is treated as hostile. The page runs under a strict Content Security Policy (bundled scripts only, no inline scripts, frames, forms or connections), and DOMPurify sanitizes everything before it reaches the page.
• The writer only writes to the file on screen, and only to a type spacebar edits (Markdown, code, text, JSON, CSV, dotfile config), never to a binary, a binary property list, text over 2 MB or a file it shows cut, and into anything but Markdown only what was typed in its own key panel; it only opens http(s) links or non-executable documents, and only accepts messages from the extension's own page. Apps and executables in the sidebar can only be revealed in Finder; a script shown as text opens only in a text editor (an app that declares the Editor role for text, never a terminal, browser or script runner), where it is not run.
• The file browser never leaves the previewed folder: links that lead out of it are not listed, a file or folder the page asks for must be one the sidebar listed and must still resolve inside the folder, and hidden files are left out unless you turn them on. A wikilink or embed resolves only to a file found inside the folder the sidebar shows; .., absolute paths and links that lead out of it resolve to nothing. Nothing in a Markdown file is ever run, and scripts are shown as source, SVG only as an image, a PDF by PDFKit (which runs no PDF scripts; the PDF is parsed in the sandboxed preview extension itself), and the page loads files only as images.
• An HTML file is shown in a web view of its own that shares nothing with the preview's page. One your browser, Mail or AirDrop marked as downloaded (the quarantine flag) always opens with scripts off and no network at all, resource hints included, and only files beside it load. Files from git clone, curl, unzip or a USB drive are not marked: by default (Settings, Advanced, Scripts in HTML files: Ask) such a page opens without its scripts, and a bar above it asks whether to run them, for files made on this Mac, or never. Files made on this Mac runs them and lets the page load from the web; Never turns both off for every HTML file. A page's scripts cannot fetch or frame the files beside it, though they can use one as their own script, stylesheet or image, as in a browser. A link in an HTML file is followed only when you click it, through the same policy as everywhere else.

Found a security problem? Please report it privately as described in SECURITY.md, not in a public issue.

Contributing

Issues and pull requests are welcome; CONTRIBUTING.md has the steps. Please run the off-screen tests above before sending a change, and keep new dependencies out of the extension unless they are vendored with their licence (see Preview/web/vendor/VERSIONS.txt and THIRD_PARTY_NOTICES.md).

Licence

MIT, © 2026 Pate Bryant. See LICENSE. Bundled third-party code and fonts keep their own licences, listed in THIRD_PARTY_NOTICES.md.

Not affiliated with Apple. Mac, macOS, Finder and Quick Look are trademarks of Apple Inc.