GridBash

Fast, beautiful terminal grids for running lots of CLI agents at once.

GridBash is a Windows-native Rust TUI multiplexer built for agent-heavy development: launch a grid of Codex, Claude, Gemini, Aider, OpenCode, Goose, Amp, Cursor, Copilot, Git Bash, PowerShell, or any custom command, then select panes and send input only where you want it.

V1 is intentionally single-process. Closing GridBash closes its child agents. Daemon detach/reattach is the next major frontier.

Release Status & Devlogs

• Latest npm version is shown by the npm badge above and on the npm package page.
• Latest GitHub release is shown by the GitHub release badge above and on the GitHub Releases page.
• Devlogs live in docs/devlogs/.
• Versioned release notes live in docs/releases/ and are used for GitHub release notes.
• npm packages include docs/devlogs/ and docs/releases/ so published package contents carry the logs too.

Highlights

• Real PTY-backed panes through Windows ConPTY via portable-pty.
• Up to 100 panes in one terminal process.
• Configurable default terminal profile: Git Bash, PowerShell, cmd, agents, or custom.
• Pane-contained drag selection that copies selected terminal text without crossing into sibling panes.
• Sleeping panes stay visually hidden until hovered, then wake without crossing input into other panes.
• Normal terminal keys pass through to the focused pane, or to selected panes when multiple panes are selected.
• Modeless Alt shortcuts for pane focus, selection, rename, settings, and quit.
• Compact dark theme with focus, selection, sleep, exit, usage, and quiet-output cues.
• Claude, Codex, and other agent panes show a compact conversation summary in the footer line.
• Built-in launch profiles for common CLI coding agents.
• Startup dimension picker with a live grid preview.
• Optional managed git worktrees so every pane can work in an isolated checkout.

Demo

Watch the OpenVid-style demo: docs/assets/gridbash-openvid-demo.mp4.

The source scene and OpenVid recreation recipe are in docs/demo/openvid-gridbash-demo.md.

Install With npm

From this repo:

npm run install:local

Then run it from anywhere:

gridbash

Build a publishable npm tarball:

npm pack

The package ships a Node command shim that launches the bundled Windows x64 gridbash.exe.

Release automation and devlog workflow are documented in docs/RELEASING.md.

Use npm run install:local for local development installs. It installs from a packed tarball so the global gridbash command points at a stable package copy, not whichever .worktrees/ checkout last ran npm install -g ..

PR Workflow

Pull requests can be merged directly after they have been reviewed. Before merging, check the diff, confirm the intent is clear, and make sure the relevant validation has passed.

Install From Source

Install Rust first:

winget install --id Rustlang.Rustup -e

Build GridBash:

git clone https://github.com/jasonsuhari/gridbash
cd gridbash
cargo build --release

The executable will be:

target\release\gridbash.exe

Use

Open the startup grid picker:

gridbash

On first launch, if no default profile is configured, GridBash opens an animated setup screen and asks you to choose from the detected terminal profiles. The choice is saved to:

%APPDATA%\GridBash\config.toml

The startup picker asks for rows and columns, updates the preview grid as you change them, and launches every pane in the directory where you started gridbash.

Set the default terminal profile:

gridbash --set-default powershell

Open a specific grid:

gridbash 2x3 --profile git-bash

Open 12 panes and auto-arrange them:

gridbash --count 12 --layout auto --profile claude

List detected profiles:

gridbash --list-profiles

Start in a repo:

gridbash 3x4 --profile codex --cwd C:\Users\Jason\Documents\GitHub\fluent

Passing grid, count, profile, or cwd arguments bypasses the startup picker and uses the direct launch path.

Launch every pane in a separate repo-local git worktree:

gridbash 2x3 --profile codex --worktrees

With --worktrees, GridBash creates or reuses .worktrees/gridbash-<base>-NN folders and gridbash/<base>-pane-NN branches. Panes keep the same relative folder as the directory where you launched GridBash, so starting from repo\app opens each terminal in the matching app folder inside its managed worktree. GridBash refuses this mode outside a git repo or when tracked changes are present in the base checkout.

You can also run gridbash --worktrees and choose the grid dimensions in the startup picker.

Agent Control MCP

GridBash can expose a local, opt-in control API for agents running inside its panes:

gridbash --agent-api 2x3 --profile codex

When enabled, child panes receive GRIDBASH_CONTROL_ADDR, GRIDBASH_CONTROL_TOKEN, and GRIDBASH_PANE_INDEX. Configure an agent MCP server command to run:

gridbash --mcp

The MCP server exposes:

• gridbash_show_image to display a local png, jpg, gif, or webp in a GridBash overlay.
• gridbash_send_command to send command text to one or more 1-based pane numbers.
• gridbash_set_status to update the GridBash status bar.

The control API binds to localhost, uses a per-session token, and is off by default.

Startup Picker Controls

Input	Action
Left / Right	Switch between rows and columns
Up / Down	Increase or decrease the active dimension
r / c	Select rows or columns
1-9 / 0	Set the active dimension directly, with 0 meaning 10
Enter	Launch the grid
Esc / q	Quit

Controls

GridBash captures drag selection so selected text stays inside the pane where the drag started. Releasing the drag sends the selected terminal text to the host clipboard through the standard OSC 52 terminal clipboard sequence. App controls use Alt shortcuts and do not require switching modes.

Input	Action
Drag mouse	Select/copy terminal text within the source pane
Alt+Left / Alt+Right	Focus previous / next pane
Alt+Up / Alt+Down	Focus pane above / below
Alt+Shift+Up / Alt+Shift+Down	Remove / add a row when safe
Alt+Shift+Left / Alt+Shift+Right	Remove / add a column when safe
Alt+s	Toggle focused pane selection
Alt+a	Select all panes, or clear selection when all panes are selected
Alt+r	Rename the focused pane
Alt+t	Restart exited focused pane; when multiple panes are selected, restart exited selected panes
Alt+z	Put the focused pane to sleep; when multiple panes are selected, sleep the selected panes
Hover sleeping pane	Wake the pane and make its terminal contents visible again
Alt+o	Open settings
Alt+q	Quit

Typing goes to selected panes whenever multiple panes are selected. With zero or one pane selected, input goes to the focused pane.

Renamed pane headers replace the numeric prefix for the current session. Saving a blank name restores the default number.

Pane titles add a small quiet-output marker after roughly three seconds without output. The marker means a pane produced output and then went idle; it does not mean the process exited or completed its task.

The settings screen includes sample controls plus live color controls for the accent, focus, selected, quiet, and exited grid roles. Palette changes apply immediately for the current run.

Profiles

Built-in profile keys:

git-bash pwsh powershell cmd codex claude gemini opencode aider amp goose copilot cursor

GridBash resolves Windows .exe and .cmd shims before extensionless npm shims, so common Node-based CLIs launch correctly.

Optional config file:

%APPDATA%\GridBash\config.toml

Example:

[defaults]
profile = "powershell"

[profiles.review]
command = "codex"
args = ["--model", "gpt-5.5"]
title = "Codex Review"

Then run:

gridbash 2x4 --profile review

Default profile resolution order:

--profile > GRIDBASH_PROFILE > [defaults].profile > git-bash

Design Goals

GridBash is inspired by agent-first multiplexers such as Mato and terminal workspaces such as Zellij, but V1 takes a different path: Windows-native, single binary, visual selection, scoped multi-pane input, and a hard bias toward fast multi-agent grids.

Community

• Read CONTRIBUTING.md before opening a pull request.
• See docs/ROADMAP.md for the release roadmap.
• Use GitHub Issues for actionable bugs, tasks, and feature requests.
• Use GitHub Discussions for questions, ideas, and longer design conversation.
• Follow SECURITY.md for private vulnerability reports.

Legacy Launcher

The old Windows Terminal launcher is still useful for quick split-pane grids, but it cannot support true subset pane input because Windows Terminal does not expose subset pane selection. The Rust app is the path forward.