Imperator FinderTerminal

// Overview

A keyboard-triggered terminal that docks onto the frontmost real Finder window, the way sheru.app does ⌘J — but without replacing Finder. Finder stays untouched, so every native view keeps working, column and gallery included. The app shrinks the Finder window, attaches a themed terminal in the freed space, and keeps the two pointed at the same folder.

// Requirements

macOS 14 or later on Apple silicon. Built and tested on macOS 26 only; older versions are expected to work but have not been verified.

The app is signed with a self-signed certificate and is not notarized, so macOS cannot vouch for it. Install at your own risk. Provided as is, no warranty, under the MIT license.

// Install

Download the latest zip from the releases page, unzip, and move Imperator FinderTerminal.app to /Applications.

Gatekeeper blocks the first launch. Right-click the app and choose Open, or clear the quarantine flag:

There is no Dock icon. The app lives in the menu bar.

// Permissions

Three grants in System Settings ▸ Privacy & Security. The app starts without them and degrades rather than failing, but docking only works once Accessibility is on.

Accessibility — without it there is no docking at all. The terminal falls back to a quake panel at the top of the screen and the Finder window is never moved, resized or followed.

Automation ▸ Finder — without it the folder sync stops in both directions. Prompted the first time you press the hotkey.

Input Monitoring — without it a close happens with no warning. ⌘W and the red close button are intercepted so the terminal can ask first, and the interception never fires without the grant.

Accessibility and Input Monitoring have to be ticked by hand. macOS shows no prompt for either.

// Use

Open a Finder window and press ⌘⌥§ — the section key, top left on an ISO keyboard, and rebindable in Settings. The Finder window shrinks and the terminal takes the freed strip, opened in the folder Finder is showing. Press again to close it and give Finder its size back. With no Finder window open, the app opens one and docks to it.

Folder sync runs both ways: click into another folder in Finder and the shell follows, cd in the shell and Finder follows. Drag the pill in the gap to resize both windows at once, or the terminal's outer edge to resize only the terminal. A Finder window in native fullscreen docks like any other. ⌘C, ⌘V, ⌘X and ⌘A work inside the terminal. Minimizing Finder fades the terminal out with the Dock animation and brings it back on restore. Closing a Finder window with a terminal attached asks first, and cancelling keeps both the window and the folder.

Everything else sits behind the menu bar icon: theme, custom themes, the keyboard shortcut, font size, dock side, which window keeps focus when the terminal opens, and whether the close warning always shows or only when a process is running.

// Theme

The terminal reads your Terminal.app default profile by default — background, text, cursor and selection colours, all sixteen ANSI colours, font and line spacing. Ten classic presets ship with the app, and colours and font size can be set by hand.

// Why not a Finder extension

macOS exposes no API for embedding a view inside a Finder window. A FIFinderSync extension can add a toolbar button, a context menu, sidebar icons and file badges — never a panel. So the terminal cannot live inside Finder. This is the closest thing that keeps the real one: a separate window, anchored to the Finder window and moved with it.

// How it works

A background menu bar app, LSUIElement, no Dock icon, with no external package dependencies — SwiftTerm is vendored.

The frontmost Finder folder is read over Apple events. Position, size and fullscreen state are read and written over the Accessibility API, and an AXObserver reports moves, resizes, minimize, fullscreen transitions and closes. The panel follows from a CADisplayLink, one apply per frame, pausing when nothing moves. It hides whenever neither Finder nor the terminal is frontmost, and restores the Finder window's original size on close.

Fullscreen is the one case where the system drops Accessibility writes. Room is made instead with a private SkyLight call, SLSSpaceSetEdgeReservation, which reserves a strip of the fullscreen space. Every symbol is resolved at runtime, so a macOS release that removes it degrades to no fullscreen docking rather than crashing.

Folder sync works because the shell is spawned with TERM_PROGRAM=Apple_Terminal, so the system /etc/zshrc emits OSC 7 on every prompt and SwiftTerm reports it back. One shared current-directory value breaks the feedback loop.

// Build

Builds release, kills the running copy, installs to /Applications and launches. make and make clean are the other targets.

Both call ./build.sh, which compiles with SwiftPM, assembles the bundle and codesigns it with the local Imperator Dev identity so macOS keeps the permission grants across rebuilds. The Swift toolchain from the Command Line Tools is enough; full Xcode is not needed.

// Known limits

The Accessibility-to-Cocoa coordinate flip uses the menu bar screen's height, so docking can be off on secondary displays. Single display is exact.

OSC 7 comes from the system zsh wiring, so bash and fish do not emit it and only the Finder-to-terminal direction syncs there.

Mission Control shows the Finder window and the terminal as two separate windows. Picking either raises both, but they cannot be grouped into one.

Fullscreen docking depends on a private API and may stop working on a future macOS. Everything else uses public API.

The app is not sandboxed, so it is not App Store material — it needs to spawn a PTY, send Apple events and use the Accessibility API.

// Not yet built

An optional FIFinderSync toolbar button and "Open terminal here" contextual item, multi-window sessions per Finder window, panel size memory.

// Third-party

SwiftTerm by Miguel de Icaza, MIT licensed, vendored at v1.14.0 with one local patch.