tabby-fleet

A Tabby Terminal plugin that turns one git repo into one tab with a grid of agent panes — one per worktree.

You point a profile at a repo. The plugin spawns an orchestrator pane at the repo root, plus one worker pane per git worktree (anywhere on disk — git worktree list is the source of truth), each cd'd into its own worktree directory and running the agent of your choice. New worktrees appear as new worker panes within a second. Closed panes stay closed. Focus zooms.

Install

Three options, easiest first.

Option 1: Tabby's Plugin Manager (recommended)

1. Open Tabby → Settings → Plugins → Available.
2. Search tabby-fleet.
3. Click Get.

Tabby's plugin manager shells out to npm under the hood and drops the package into your user plugins folder.

Option 2: npm CLI

# Windows (Scoop install of Tabby):
npm install --prefix "$env:USERPROFILE\scoop\persist\tabby\data\plugins" tabby-fleet

# Windows (default install):
npm install --prefix "$env:APPDATA\tabby\plugins" tabby-fleet

# macOS / Linux:
npm install --prefix "$HOME/.config/tabby/plugins" tabby-fleet

Restart Tabby. You'll see an Agent Fleet template under "New profile".

Option 3: From source (development)

git clone https://github.com/PatrickRuddiman/Tabby-Fleet.git
cd Tabby-Fleet
npm install
npm run build

Link the clone into Tabby's plugin folder so every npm run build is live:

# Windows (Scoop install of Tabby): replace <CLONE> with your absolute clone path.
$plugins = "$env:USERPROFILE\scoop\persist\tabby\data\plugins\node_modules"
New-Item -ItemType Directory -Force -Path $plugins | Out-Null
New-Item -ItemType Junction -Path "$plugins\tabby-fleet" -Target "<CLONE>"

# Windows (default install):
$plugins = "$env:APPDATA\tabby\plugins\node_modules"
New-Item -ItemType Directory -Force -Path $plugins | Out-Null
New-Item -ItemType Junction -Path "$plugins\tabby-fleet" -Target "<CLONE>"

# macOS / Linux:
PLUGINS="$HOME/.config/tabby/plugins/node_modules"
mkdir -p "$PLUGINS"
ln -s "$(pwd)" "$PLUGINS/tabby-fleet"

Restart Tabby.

Run

1. Tabby → Settings → Profiles → New profile → Agent Fleet.
2. Configure the profile:
   • Config tab:
     • Repo path — root of the git repo (Browse… opens a folder picker).
     • Pre-launch command — optional, runs once at launch (e.g. pnpm install).
     • Shell — picks one of your installed Tabby Local profiles (pwsh, bash, wsl, …).
     • Worker command — what runs in each worker pane. E.g. claude, copilot, codex, opencode. Cwd is the worktree directory.
     • Filters — include/exclude detached / prunable / locked worktrees.
     • Notifications — focus-on-add and worktree-change toasts.
     • Advanced (collapsed) — override the orchestrator command separately and tweak title patterns. Blank orchestrator command falls back to the worker command.
   • Themes tab:
     • Orchestrator sub-tab — color scheme for the orchestrator pane.
     • Worker sub-tab — color scheme for every worker pane.
3. Save the profile. Open it from the profile launcher.

What to expect

On open:

• One tab opens with N panes arranged in a square-ish grid (cols = ceil(sqrt(N)), rows = ceil(N / cols)).
• The orchestrator pane runs at the repo root. Every other pane is a worker pane cwd'd to its worktree path. Both run the worker command unless you set an Advanced orchestrator override.
• About 400 ms after the last pane is constructed, the plugin triggers a final layout pass so xterm + PTY + agent are all sized correctly before the agent's banner renders.

Click a pane:

• That row gets the larger row weight; that pane gets the larger column weight within its row. The other panes shrink. Focus another pane and the ratios swap.

git worktree add from anywhere:

• The plugin polls git worktree list adaptively (500 ms while activity is recent, backing off to 10 s after one minute of quiet). A new worktree appears as a pane within ~500 ms. Layout rebalances to the new grid. Your typing focus is preserved — the new pane doesn't steal it.

git worktree remove from anywhere:

• Within ~500 ms the watcher sees the worktree disappear. The plugin tree-kills the agent process and all its descendants (taskkill /F /T /PID on Windows; kill -group + recursive pgrep -P on Unix), releases file handles, then removes the pane. The orchestrator can clean up any leftover directory.

Close a pane (× button or exit in the shell):

• The plugin tree-kills the agent before Tabby tears the shell down. Then it adds that worktree path to a session-local "dismissed" set so the watcher does NOT reopen the pane even if the worktree is still on disk — letting you safely git worktree remove after.

Close the orchestrator pane:

• Confirmation modal: closes the whole fleet tab.

Quit and reopen Tabby:

• The fleet tab is restored from Tabby's tab-recovery system with each pane in a dead state. Click a pane to relaunch its agent.

Compatibility

• Tabby 1.0.230+ (Angular 15)
• Windows, macOS, Linux
• Tested daily on Windows 11 + Tabby 1.0.233 + pwsh 7 + Claude Code

Develop

npm install
npm run watch   # rebuild on every change
npm test        # run the test suite (mocha)

The dev junction (above) means every npm run build is immediately visible to Tabby on next launch — no reinstall needed.

License

MIT