Skip to content

About

Listary's Ctrl+G for macOS: jump open/save dialogs to any folder, with search backed by Tinycast's own file index. Raycast-format extension, installable in Tinycast.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

Repository files navigation

Panel Jump

Listary's Ctrl+G for macOS: when a save or open dialog is in front of you, send it to the folder you are browsing in Finder — or to any folder or file you search for — without touching the mouse.

It is a Raycast-format extension, so it runs in Raycast and in Tinycast (which runs Raycast extensions natively in JavaScriptCore). Assign a global shortcut to a command and it works from any app, including inside save panels.

The two problems it fixes

  1. "Save somewhere else." Save dialogs open wherever the app last saved. Press your shortcut, and the panel jumps to the Finder folder you are looking at. No more dragging folders into the dialog or clicking through Macintosh HD › Users › ….
  2. "What was that file called?" You are in a save/open box and the file is somewhere you would have to click through. A sheet does not block other apps from coming forward, so Search Files and Jump opens the palette over the panel, searches your files, and puts the panel in the result's folder with the file selected (open panels).

Commands

Command What it does Suggested shortcut
Panel Jump (smart-jump) One key, decided by what is in front: panel → jump to the Finder folder; no panel (Finder included) → opens Search Files and Jump; pressed twice in a panel → search instead of jumping ⌃G
Search Files and Jump Search Tinycast's file index; goes to the result's folder (or the folder holding the file) ⌃⇧G
Jump to Finder Folder Jump only, no menu — the bare Ctrl+G ⌃⌥G
Jump to Recent Folder Pick from recent folders, Finder's folder, or Desktop/Downloads/Documents/Home —

jump-to-folder is the background half of the two palettes — it takes the folder they picked and moves the panel (or the Finder window) there. It has no shortcut of its own.

⌃G is the whole Listary habit in one key: in a save/open box it sends the panel to the folder you are browsing in Finder; anywhere else it drops you into the file search, whose result either moves the panel or navigates Finder.

Do not bind ⌘⇧G as the global shortcut

The jump works by sending ⌘⇧G (Go to the Folder) to the panel. A global shortcut on the same chord is swallowed before the panel sees it, and the synthetic keystroke can re-trigger the command — so the panel never receives it. Use ⌃G / ⌃⇧G; inside a panel, ⌘⇧G stays the panel's own folder field.

The search backend

The search is Tinycast's own file index — nothing else. It reads the snapshot the launcher already keeps:

~/Library/Application Support/com.abueammar.tinycast/FileIndex/index.bin (magic TCFIDX01, version 2: a 96-byte header, then 8-byte aligned sections; paths are rebuilt by walking block owners, there is no parent column).

Query Time
panel 3 ms
insights 5 ms
文献 (CJK) 4 ms
cold start (2 MB read + parse) 20 ms, once per run

No index is built, no directory is walked, no process is spawned — a query is a binary search over blocks. That also means it covers what a scan cannot: hidden folders (~/.pi, ~/.gemini) and the cloud paths (~/Library/CloudStorage).

There is no fallback backend. If the snapshot is missing, unbuilt, or reports an unknown format version, the command says so instead of scanning: enable Settings ▸ File Search in Tinycast (it needs Full Disk Access) and the command starts answering.

Two preferences: Search Folders (colon-separated, ~ allowed, empty = your home folder) and Index Path (only to point at another launcher's snapshot).

The index is as fresh as Tinycast's last build. Tinycast watches its scopes and rewrites the snapshot as things change, so a file created a second ago can lag behind — the launcher's own search lags the same way.

Where "Recent" comes from

Jump to Recent Folder shows two different recents, on purpose:

Section Source Rule
Jumped to this extension's own log (LocalStorage, key recent-folders) only successful jumps; newest first; dedupe by path; 40 entries
Recent folders Tinycast's index, mtime column folders only; mtime descending; at most one per parent and at most three levels below your search roots; hidden folders, Library, Caches, tmp, node_modules, DerivedData dropped

The first answers "where have I been with this command", the second answers "where was I working" — it mirrors what the launcher's own blank screen ranks by, because a folder's mtime moves when anything inside it changes.

Install

Tinycast — from GitHub

Tinycast ▸ Settings ▸ Extensions ▸ Install ▸ Install from GitHub, enter:

fabea87/panel-jump

Tinycast clones this repository, runs npm install --ignore-scripts and npm run build on your Mac (so it needs Node and a package manager; it finds Homebrew/nvm/asdf/pnpm itself), then keeps only the build. The build is plain esbuild — no Raycast CLI, no Xcode.

Tinycast — from the folder

Tinycast ▸ Settings ▸ Extensions ▸ turn extensions on (it is off by default) ▸ Add Folder ▸ this repository's dist folder. dist/ is committed and self-contained: package.json, one .js per command, assets/.

After installing

Open the palette and assign shortcuts:

Command Suggested
Panel Jump ⌃G
Search Files and Jump ⌃⇧G
Jump to Recent Folder —

Rebuilding into the copy Tinycast runs

Tinycast copies the folder it installs; a later npm run build does not reach it. Use:

npm run install:tinycast      # build + copy into ~/Library/Application Support/com.abueammar.tinycast/extensions/panel-jump

Raycast

npm install
npm run dev      # then "Import Extension" when Raycast asks

Or drop dist/ into Raycast's extension folder and reload.

Permissions (one-time)

macOS asks for both the first time:

  • Accessibility — needed to send keystrokes to the dialog and to read the front window (the sheet/dialog check). Without it osascript fails with -25211 "not allowed assistive access" when inspecting windows and 1002 "not allowed to send keystrokes". Reading Finder's front folder and the frontmost app name still works, which is why the failure looks partial. System Settings ▸ Privacy & Security ▸ Accessibility → enable Raycast/Tinycast.
  • Automation — needed to read Finder's folder and to press keys via System Events. Allow the prompt ("… wants to control System Events / Finder").

Panel Jump reports the missing permission in a toast instead of typing nothing. If the prompt was dismissed, add it manually in System Settings ▸ Privacy & Security ▸ Automation / Accessibility.

Press it twice to search

⌃G in a panel sends it to the folder open in Finder. When that is not where the file belongs, press ⌃G again within 1.2 s and the search opens instead of jumping a second time — search Tinycast's index, pick a folder, and the panel lands there.

  • the window is the Double Tap Window preference (ms, 0 disables it)
  • a press claims itself before it jumps, so the second press is recognised even while the first jump is still running
  • the two presses must come from the same app; a jump in one app and a press in another are unrelated
  • the first press still completes its jump, which is what you would have got anyway — the search simply opens on top of it

⌃⇧G reaches the same search directly, without the double tap.

Any characters, and how fast

A panel jump types a path into the panel's folder field (⌘⇧G). AppleScript's keystroke goes through the current keyboard layout, so 期刊投稿 used to arrive as aaaa — and a save panel accepted it, landing you in a folder that does not exist.

The path is therefore never typed as-is unless it is printable ASCII. Anything else goes through a symlink with an ASCII name, created with ln in the extension's support folder: typing a link is safe, and the panel resolves it, so you land in the real folder.

Two smaller things this had to get right:

  • the folder field arrives pre-filled with the panel's current folder, so ⌘A clears it first (⌘V pasting into that field proved unreliable, and so did posting CGEvents from the extension — both were tried and thrown away)
  • the panel's app can lose key status when the launcher handles the request, so it is brought back to the front before a key is sent

Timing, measured end to end against a real NSSavePanel (test/manual/, 14 fixtures, twice): 14/14 pass, ~450 ms inside the extension for the whole sequence — ⌘⇧G, 80 ms, ⌘A, type, 50 ms, Return. The rest of what you see is the sheet's own animation.

Category Example Verified
CJK 期刊投稿-研究资料, 中文父目录/子目录-😀 ✓
emoji 😀🎉-party-🚀 ✓
RTL עברית-sample ✓
full-width / half-width ABC123-ハンカク ✓
accents, NFC and NFD café-Crème-Brûlée ✓
spaces, parens, & spaces and (parens) & more ✓
quotes quotes-'single'-“double” ✓
shell symbols symbols-#$%&=+;,@!~\^` ✓
100-character name very-long-xxx… ✓
leading dash -leading-dash-folder ✓
deep nesting a/b/c/深 层/😀 end ✓

Nothing is typed at all unless a panel is really in front: no dialog means no keystrokes, so a stray key can never land in your document.

How it works

For a dialog, the extension sends ⌘⇧G (the built-in Go to the Folder sheet of every Cocoa open/save panel), types the POSIX path, presses Return, and — when you picked a file — types its name so the panel selects it.

Before any keystroke it checks, via System Events, that the frontmost app actually has a dialog (a sheet, or a window whose subrole is AXDialog). If not, it types nothing and reports why, so a stray keystroke can never end up in your document.

Focus is taken into account: the command waits for the launcher to close and re-queries the frontmost app, so keystrokes go to the app that owns the panel.

Limitations

  • Works with standard macOS panels (NSOpenPanel/NSSavePanel). Most apps use them, including Electron apps such as VS Code.
  • Apps with their own drawn file dialogs (some Adobe apps, some Java apps) do not respond to ⌘⇧G. The command detects the missing dialog and tells you instead of typing into the document.
  • The delays are fixed (0.15–0.5 s per step). On a heavily loaded machine a step may land too early; run the command again.
  • Selection after a jump relies on the panel's type-ahead, so the highlight may vary with the view mode (list, column, icons); the folder is always correct.

Troubleshooting

Symptom Cause / fix
"… has no open or save dialog" The dialog is not a sheet or dialog window, or focus is elsewhere. Click the dialog once, retry.
"… ignored the folder shortcut (⌘⇧G)" Custom-built dialog. Use the app's own search, or drag the folder onto the dialog.
Nothing happens, no message Accessibility permission missing for the launcher.
"Allow the launcher to control System Events…" Automation permission was denied; re-enable it in System Settings.
Jumps to the wrong folder Finder's front window is used — bring the folder you want to the front (⌘`) first.

No launcher? Hammerspoon fallback

If you would rather not run a launcher, this does the core Ctrl+G:

local function finderFolder()
  local ok, res = hs.osascript.applescript([[
    tell application "Finder"
      if (count of windows) is 0 then return POSIX path of (desktop as alias)
      return POSIX path of (target of front window as alias)
    end tell]])
  if not ok then return nil end
  return (res:gsub("/$", ""))
end

hs.hotkey.bind({ "ctrl" }, "g", function()
  local folder = finderFolder()
  if not folder then return end
  hs.osascript.applescript(string.format([[
    tell application "System Events"
      keystroke "g" using {command down, shift down}
    end tell
    delay 0.4
    tell application "System Events" to keystroke "%s"
    delay 0.2
    tell application "System Events" to key code 36
  ]], folder:gsub('"', '')))
end)

Development

npm install
npm run typecheck   # tsc --noEmit
npm test            # 10 unit tests for the pure helpers
npm run build       # bundles the commands into dist/

build.mjs replaces ray build with esbuild so the extension can be built on any platform. @raycast/api, react and react/jsx-runtime stay external — the host (Raycast or Tinycast) provides them — and Node built-ins (child_process, fs, os, path) are used only through the small wrappers in src/lib/.

What was verified off-device: TypeScript type-check, 10 unit tests for query building, fd arguments, ranking, routing, path normalisation and formatting, and the bundle layout. The AppleScript automation itself can only be exercised on macOS.

Privacy

Nothing leaves the Mac. Recent folders are stored in the launcher's own LocalStorage; searches run fd locally. Nothing leaves the Mac.

License

MIT.

About

Listary's Ctrl+G for macOS: jump open/save dialogs to any folder, with search backed by Tinycast's own file index. Raycast-format extension, installable in Tinycast.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages