Paneful

Your terminals,
organized

Split panes, organize by project, drag & drop from Finder, sync with your editor — all from a single npm install.

Install via CLI macOS App
Paneful — split pane terminal layout Paneful — project sidebar and terminals Paneful — multiple panes and git status

Features

Everything you need from a terminal

Split panes, project organization, editor sync, and smart detection — all built in.

Split Pane Layouts

Five layout presets: columns, rows, main + stack, main + row, and grid. Cycle through them with Cmd+T or auto-reorganize with Cmd+R.

Project Sidebar

Organize terminals by project. Each project gets its own layout, panes, and working directory. Switch instantly from the sidebar.

Drag & Drop

Drag folders from Finder into the sidebar to create projects. Drag files into terminal panes to paste their paths as shell-escaped arguments.

Editor Sync

Automatically switches the active project when you focus a different editor window. Click into VS Code, and your terminals follow. Learn how to set it up ↓

Favourites

Save workspace layouts as favourites — name, preset, and per-pane commands. Restore any setup with a single click.

Native macOS App

Install as a standalone app with its own Dock icon and WebKit window. No browser tab needed.

Dev Server Detection

Automatically detects when a dev server starts in a terminal. A green dot appears next to the project name in the sidebar while the port is alive, and disappears when it stops.

AI Agent Detection

Detects when Claude Code or Codex CLI is running in a terminal. A purple AI badge appears next to the project name — pulsing when the agent is actively working.

GPU Rendering

Terminals render via WebGL2 on the GPU by default — significantly faster for high-throughput output and multiple panes. Toggle from the sidebar or command palette. Falls back to DOM automatically.

Terminal Search

Press Cmd+F to search terminal scrollback. Navigate matches with Enter / Shift+Enter. Escape to close.

Command Palette

Press Cmd+P to open the command palette. Switch projects, launch favourites, change layouts, or run actions — all from one fuzzy-searchable list.

Git Branch Display

Shows the current Git branch next to each project in the sidebar as a styled pill badge. Updates automatically. Non-git directories show no badge.

Keyboard Shortcuts

Full keyboard control: split, close, focus by index, move focus, swap panes, toggle sidebar, and cycle layouts — all without touching the mouse.

Auto-Reorganize

Press Cmd+R to let Paneful pick the best layout for your current pane count. Smart defaults, zero effort.

Editor Sync

Your terminals follow your editor

Focus a VS Code window and Paneful instantly switches to that project's terminals. Zero clicking, zero context-switching.

VS Code Cursor Zed Windsurf

How it works

You focus an editor window

Switch to your VS Code window for my-api

Paneful detects the change

Reads the frontmost app and window title via the macOS Accessibility API

Matches to a project

Compares the folder name in the title against your Paneful projects

Terminals switch instantly

Sidebar, layout, and all panes switch to my-api

Setup

  1. Grant Accessibility permission

    Add Paneful (native app) or Terminal (CLI) in:

    System Settings › Privacy & Security › Accessibility
  2. Editor window title includes folder name

    This is the default in VS Code and Cursor. If you've customised your title bar, make sure ${rootName} is present:

    "window.title": "${dirty}${activeEditorShort}${separator}${rootName}"
  3. Toggle on in sidebar

    Click the monitor icon in the sidebar header. Enabled by default.

💡 After updating Paneful, you may need to remove and re-add it in Accessibility settings.

Get Started

Install in seconds

One command to install. One command to run.

1. Install from npm

Install the CLI globally — this is required for everything else.

$ npm i -g paneful

2. Run

Start the server and open Paneful in your browser.

$ paneful

3. Optional: macOS app

Get a native Dock icon and WebKit window — no browser tab needed.

$ paneful --install-app

4. Optional: VS Code extension

Spawn projects and send file paths from VS Code, Cursor, or any VS Code-based editor. Right-click context menus in the editor and explorer.

Install from VS Code Marketplace

Usage

CLI commands

Everything runs from the paneful command.

$ paneful # Start server and open browser $ paneful --spawn # Add current directory as a project $ paneful --port 8080 # Use a specific port $ paneful --list # List all projects $ paneful --kill my-project # Kill a project by name $ paneful --install-app # Install as a native macOS app $ paneful update # Update to the latest version

Updating

Stay current

$ paneful update

Checks npm for the latest version, installs it globally, and rebuilds the native .app if one exists. The Dock icon stays valid automatically.

Keyboard Shortcuts

Full keyboard control

Never take your hands off the keyboard.

Shortcut Action
Cmd+P Command palette
Cmd+F Search terminal scrollback
Cmd+N New pane (vertical split)
Cmd+Shift+N New pane (horizontal split)
Cmd+W Close focused pane
Cmd+1-9 Focus pane by index
Cmd+Arrow Line start / end in terminal
Ctrl+Shift+Arrow Move focus to adjacent pane
Shift+Arrow Swap focused pane with adjacent
Cmd+D Toggle sidebar
Cmd+T Cycle through layout presets
Cmd+R Auto reorganize panes