Skip to main content

Open in Overdeck

pan open opens a file or folder in the Overdeck dashboard. A folder opens in the Files tab of the work dock, a file opens in a code tab, and both open in the deck of the project they belong to. You can also add Open in Overdeck to your file manager’s right-click menu, so a click does the same thing.

pan open

The target can be:
  • a path: absolute, relative to the current folder, or starting with ~;
  • a path with a position: <path>:<line> or <path>:<line>:<column>. --line <n> and --column <n> set the position too, and win over a suffix. A file whose name really ends in :12 still opens as that file;
  • an issue id such as PAN-123, which opens the issue’s feature workspace folder.
Before PAN-5349, pan open <issue> opened the issue’s workspace in an editor. That is now pan open <issue> --editor.

Which tab opens it

When several dashboard tabs are open, the tab you focused last opens the path, and its window comes to the front. If that tab is gone (it crashed or its record is older than a day), any visible tab opens it after a short wait. When no dashboard tab is open, pan open opens the link below in your browser instead. When a dashboard tab opens the path, pan open prints Opened <path> in <project>, naming the project as the project switcher shows it, or Opened the <issue> workspace in <project> for an issue workspace, or Opened root folder in <project> for a root folder. The path it names is relative to the project or workspace folder. The dashboard shows the same message. <dashboard>/open?path=<absolute path>[&line=<n>&column=<n>] opens the same thing in the tab that loads it, then moves that tab to the project’s deck. pan open builds this link for you (pan open --new-tab always uses it). The dashboard address comes from OVERDECK_DASHBOARD_URL, or http://localhost:3011 by default.

Paths Overdeck cannot open

  • A path outside every project. pan open prints <path> isn't in a registered project. Add it with: pan project add <folder>. The /open link asks Add it as a project? and Add project opens the add-project dialog with that folder already chosen. For a file, the folder offered is the file’s parent.
  • A folder under a project’s workspaces/ that is not a feature or scratch workspace. It answers <path> is inside <project> but not in a feature or scratch workspace.
  • Overdeck is not running. pan open prints Overdeck isn't running. Start it with: pan up. It does not start the dashboard for you.

Right-click “Open in Overdeck”

Every entry runs the absolute path of pan (on Linux and macOS the shim pan sync writes in ~/.overdeck/cli-bin, or the first pan on PATH; on Windows the first pan.cmd or pan.exe on PATH), so it works without a login shell. If no pan is found, the command stops and tells you to run pan sync first. All entries are per user; nothing needs root or an administrator. pan install offers the same entries after the Ollama step: on a terminal it asks Add "Open in Overdeck" to your file manager's right-click menu? (default No). pan install --file-manager-integration adds them without asking, and --skip-file-manager-integration neither asks nor adds them. A failed install of the entries is a warning; it never fails pan install.

Linux

Three entries cover the common file managers: After writing them, pan integrate runs update-desktop-database when it is installed. The entries use the dashboard icon, copied to ~/.overdeck/integrations/overdeck.svg.

macOS

pan integrate writes a Finder Quick Action, ~/Library/Services/Open in Overdeck.workflow, and refreshes the Services menu. In Finder, right-click a file or folder and choose Quick Actions → Open in Overdeck. If it is missing, turn it on in System Settings → Keyboard → Keyboard Shortcuts → Services. If the Quick Action still does not appear, build it by hand in Automator: File → New → Quick Action, set Workflow receives current to files or folders in Finder, add Run Shell Script with shell /bin/zsh and Pass input: as arguments, and paste:
Save it as Open in Overdeck. The generated macOS Quick Action is covered by unit tests only; it is untested on real hardware.

Windows

pan integrate adds three keys under HKCU\Software\Classes with reg add: one for files (*\shell\OpenInOverdeck), one for folders (Directory\shell\OpenInOverdeck) and one for the empty space inside a folder (Directory\Background\shell\OpenInOverdeck). On Windows 11 the entry is under Show more options in the right-click menu. The Windows entries are covered by unit tests only; they are untested on real hardware.

Checking and removing

pan integrate file-manager --remove deletes the files and registry keys the install recorded in ~/.overdeck/integrations/file-manager.json, then that record. With no record it prints Nothing to remove. When the record exists, pan doctor checks that the recorded pan still runs and every recorded file still exists. If one is gone it warns File-manager integration is stale: <path>; run pan integrate file-manager again to fix it.

The desktop app

A second launch of the desktop app with --open <path> opens that path in the running window, when the window shows this computer’s dashboard. pan open itself talks to the pan up dashboard (port 3011 by default). It does not reach the desktop app’s own embedded server, so with only the desktop app running, start the dashboard with pan up or use the desktop app’s --open. See Desktop app for installing and launching it.