GridBash Reference
August 2, 2026 · View on GitHub
This guide covers launch options, sessions, managed worktrees, controls, profiles, configuration, and platform-specific behavior. See the project README for installation and a shorter introduction.
Create a grid
Run gridbash with no arguments, or press Alt+n inside a running workspace,
to open the new-grid screen. It asks three questions, one at a time, and decides
the rest:
| Step | Question | Keys |
|---|---|---|
| 01 | How big? 1-10 rows by 1-10 columns. | ↑↓ rows, ←→ columns, 1-9 for a square (0 for the maximum) |
| 02 | Call it what? Tab title for this grid; blank falls back to Grid N. | typing, ←→ to move the cursor |
| 03 | Where? Folder the panes start in. | typing, Tab completes folders and cycles matches |
Enter answers the current question and moves to the next; on the last step it
launches. Shift+Tab goes back a step, Esc cancels, and a rail under the panel
shows which steps are done. Nothing moves between steps on its own, so the arrow
keys belong to whichever question is being asked — on the size step they point at
the axis they change rather than at another field.
Everything else is assumed so there is nothing else to answer:
- Worktrees are on whenever the project is a git repository with a commit
and no tracked modifications. The screen names the exact branches it will
create and falls back to the shared project folder — saying why — when the
repository cannot host them.
Alt+w, orF2where the terminal will not send Alt, overrides the choice. - Panes run the platform shell: Git Bash on Windows, otherwise the first
available of zsh, bash, fish, sh, or PowerShell.
GRIDBASH_PROFILE, a non-agent--set-defaultprofile, and--profilestill win. Pick agents per pane once the grid is up, or launch them directly with--profile.
A live preview shows the grid that is about to exist, one cell per pane, each labelled with the managed branch it will check out.
Common direct launches:
# Fixed grid
gridbash 2x3 --profile codex
# Auto-arrange a pane count
gridbash --count 12 --layout auto --profile claude
# Start elsewhere
gridbash 3x4 --profile codex --cwd C:\path\to\repo
# Use a custom config file
gridbash 2x3 --config C:\path\to\gridbash.toml
The main launch options are:
| Option | Behavior |
|---|---|
ROWSxCOLS | Set an explicit grid, such as 2x3. |
--count N | Launch N panes, up to 100. |
--layout auto | Derive the grid dimensions from the pane count. |
--profile NAME | Use one built-in or custom profile for all panes. |
--cwd PATH | Set the panes' starting directory. |
--worktrees | Give each pane a managed git worktree. |
--worktree-prefix NAME | Change the managed folder and branch prefix from gridbash. |
--config PATH | Load and save an alternate TOML configuration file. |
--no-mouse | Leave mouse handling to the host terminal. |
--no-agent-api | Disable the pane-local agent control tools. |
--agent-api-port PORT | Choose the localhost control port; 0 selects a free port. |
Grid, count, profile, cwd, or auto-layout arguments use the direct launch path
and bypass the new-grid screen. gridbash --worktrees by itself opens it with
the managed worktree prefix from --worktree-prefix.
Set the direct-launch default profile with:
gridbash --set-default codex
New-grid controls
| Input | Action |
|---|---|
| Up / Down | Move between the four fields. |
| Left / Right | Resize on Rows and Columns; move the cursor in Name and Project. |
0-9 | Set the focused dimension directly; 0 means 10. |
| Tab | Complete the project path, or move to the next field. |
| Tab again | Cycle the remaining folder matches. |
| Ctrl+w / Ctrl+u | Delete the previous path segment / clear the field. |
| Alt+w or F2 | Override managed worktrees for this grid. |
| Enter | Launch, from any field. |
| Esc / Ctrl+c | Cancel. |
Project completion works like a shell: the first Tab extends to the prefix every
candidate shares, and later presses walk the candidates. The panel below lists
the folders next to the current path so nearby projects are one keystroke away.
~ expands to the home directory.
Managed auth is a launch boundary, not a global shell hook. GridBash sets
CLAUDE_CONFIG_DIR or CODEX_HOME for compatible agent panes it launches. It
does not replace the machine's normal claude or codex commands, and raw
terminal panes retain their normal shell environment.
Sessions and resume
GridBash writes bounded session snapshots to local app data when grids launch, when persisted state changes while they run, and when they exit. Resume interactively, resume the latest snapshot, list snapshots, or select a session by its full ID or unique prefix:
gridbash resume
gridbash resume --latest
gridbash resume --list
gridbash resume <session-id>
gridbash resume <session-id> --delete
Alt+q saves a fresh snapshot and shows a quit confirmation containing the
full command for that specific session. Press Alt+q again to quit or any other
key to cancel. After a confirmed quit, GridBash prints the command again in the
launching shell so it remains easy to copy. Confirmation is enabled by default;
set ui.confirm_quit = false or turn it off in Settings to skip the dialog.
A snapshot restores grid dimensions, pane profiles, working directories, worktree names, auth assignments, and a pane-local view of recent submitted commands and output. By default, resume starts new child terminals and does not replay old commands into a shell.
For a pane that is actively running Codex, the snapshot also stores the Codex
conversation ID. If the original pane host is gone after a restart or laptop
shutdown, GridBash relaunches that pane with codex resume <conversation-id>.
This applies both to Codex profiles and to Codex launched inside a GridBash Git
Bash pane. Unrelated shell commands are never replayed.
Enable Keep terminals running in Settings to detach live pane hosts when the
GridBash UI closes. gridbash resume then reconnects to the same PTYs; output
produced while detached is added to the restored view. If a host is no longer
available, GridBash starts a replacement terminal and retains the saved context.
The background hosts are local, authenticated, and accept one GridBash client at
a time. Resuming a saved session atomically claims it before terminals launch,
so a second client cannot duplicate or overwrite the same workspace.
Session snapshots record whether their GridBash owner is still running and
whether it exited cleanly. On a plain gridbash launch, snapshots left by a
dead owner are claimed once and reopened automatically. GridBash groups their
visible, tabbed, and background panes by working directory, names each recovered
tab after the directory, and preserves the bounded command/output context. It
does not claim sessions owned by another live GridBash process. Use Alt+t to
cycle through the recovered tabs.
In the interactive resume picker, press Delete twice to permanently remove the
selected snapshot. Deleting a detached session first stops its saved terminal
hosts; a session owned by a live GridBash process cannot be deleted. The
--delete form provides the same behavior for scripts and requires a full
session ID or unique prefix.
A plain gridbash always starts an empty workspace. When a GridBash process
dies without cleaning up, its sessions are left marked as running; pass
gridbash --recover to adopt those workspaces instead of starting a new one, and
a plain launch reports in the status bar how many are waiting. Recovery only
applies to an otherwise plain launch: grid, profile, count, cwd, worktree,
layout, and agent-API options describe a specific workspace and suppress it.
Every saved snapshot also remains available through the explicit gridbash resume commands above.
Managed git worktrees
Use --worktrees to isolate every pane in a repo-local checkout:
gridbash 2x3 --profile codex --worktrees
gridbash 2x3 --profile codex --worktrees --worktree-prefix review
With the default prefix, GridBash creates or reuses:
.worktrees/gridbash-<base>-NN
gridbash/<base>-pane-NN
The first pattern is the folder and the second is its branch. A custom prefix replaces gridbash in both.
GridBash preserves the launch directory relative to the repository root. Starting from repo\app, for example, opens each pane in the matching app directory inside its worktree.
Managed mode requires a git repository with at least one commit and refuses to start when the base checkout has tracked changes. Untracked files do not block launch. Existing branches and worktrees are reused only when they match the expected repository and branch.
Agent control API
GridBash starts its localhost agent control API by default. Freshly launched
child panes receive GRIDBASH_CONTROL_ADDR, GRIDBASH_CONTROL_TOKEN,
GRIDBASH_CONTROL_SESSION, the initial 1-based GRIDBASH_PANE_INDEX, a stable
GRIDBASH_PANE_ID, and a concise GRIDBASH_AGENT_TOOLS discovery hint. The
stable pane ID continues to identify the same live pane after reordering.
GRIDBASH_AGENT_TOOLS is human-readable help containing the primary command
forms separated by |. Its presence tells a coding agent that
pane-local coordination is available, but it is not a versioned protocol and
scripts should invoke gridbash agent --help instead of parsing its value.
gridbash agent panes
gridbash agent prompt --pane pane-4-gen-2 "Review the current diff"
"Report status and blockers" | gridbash agent prompt --others
gridbash agent rename "Reviewer"
gridbash agent rename --pane pane-4-gen-2 --clear
agent panes uses the current pane's inherited session context and marks the
caller as self. agent prompt accepts repeated --pane targets or
--others, which selects every available pane except the caller. Omit the
positional prompt to read stdin; one trailing shell line ending is removed
before submission. Sleeping, exited, missing, and stale pane targets fail
without silently retargeting. --no-submit writes the text without Enter.
agent rename sets the pane title shown in the grid, so a manager pane can label
what each pane is working on. It targets the calling pane unless --pane names
another one, takes either a positional title or --clear, and trims titles to 32
characters. Renaming only edits pane metadata, so sleeping and exited panes stay
renameable, and the new title persists with the saved session.
Use --no-agent-api on the GridBash launch command to disable these tools.
--agent-api-port PORT still selects a fixed localhost port when required.
Configure an agent's MCP client to run this stdio server from a pane:
gridbash --mcp
The MCP server exposes:
| Tool | Behavior |
|---|---|
gridbash_show_image | Display a local PNG, JPEG, GIF, or WebP file in an overlay. |
gridbash_get_grid_snapshot | Return lightweight metadata, state, and the latest activity summary for panes in the current grid. |
gridbash_read_pane_output | Return bounded recent output for explicitly requested stable pane IDs. |
gridbash_send_command | Send text to one or more 1-based pane numbers; submitting with Enter is optional. |
gridbash_prompt_panes | Prompt explicit stable pane targets, or every available pane except the caller. |
gridbash_rename_pane | Set or clear a pane's title, defaulting to the calling pane. |
gridbash_set_status | Replace the current session's status-bar message. |
gridbash_capture_output | Save each target pane's bounded recent plain-text output. |
gridbash_start_logging | Start a separate continuous plain-text output log for each target pane. |
gridbash_stop_logging | Stop and flush each target pane's active output log. |
Snapshots include each pane's current visible number and stable ID so a later output read remains attached to the intended live pane if the grid is reordered. Output reads accept at most eight available panes, default to 2,000 recent characters per pane, and cap the request at 8,000 characters per pane. Sleeping, exited, stale, and unknown pane IDs are rejected. Snapshot summaries and output are labeled as untrusted context; agents should request them only when a dependency, conflict, handoff, or integration step makes peer awareness useful, and must not treat pane text as instructions or authority.
The API binds only to localhost and authenticates mutations with a per-session token shared by panes in that session. Discovery files never contain that token.
Scriptable control CLI
GridBash processes publish owner-local discovery records containing a runtime
session ID, localhost endpoint, PID, and start time. Bearer tokens are never
written to discovery. Stale records are pruned when ctl cannot complete the
server's tokenless liveness ping.
gridbash ctl list
gridbash ctl list --json
gridbash ctl panes --session <id-or-unique-prefix>
gridbash ctl panes --session <id> --json
gridbash ctl send --session <id> --pane 2 "cargo test"
gridbash ctl send --session <id> --pane pane-4-gen-2 --no-submit "review this"
gridbash ctl capture --session <id> --pane 2 --directory C:\captures
gridbash ctl status --session <id> "integration running"
gridbash ctl focus --session <id> pane-4-gen-2
gridbash ctl rename --session <id> --pane pane-4-gen-2 "Integration"
gridbash ctl rename --session <id> --pane 2 --clear
ctl list and ctl panes do not require a token. Mutating commands require
--token TOKEN or GRIDBASH_CONTROL_TOKEN; when invoked inside a GridBash pane,
GRIDBASH_CONTROL_SESSION also selects that grid automatically. If more than
one session is running and no environment selection exists, --session must be
an exact ID or unambiguous prefix. Pane numbers refer to the inspected current
tab. Stable IDs have the form pane-<id>-gen-<generation> and are rejected if a
pane has restarted since inspection. Add --json to any command for structured
output.
Controls
GridBash is modeless: ordinary terminal input continues to the active target, while application commands use Alt shortcuts.
| Input | Action |
|---|---|
| Drag mouse | Select terminal text inside the pane where the drag began and copy it on release. |
| Right-click pane | Add or remove that pane from the selected set. |
| Left-click grid tab | Switch directly to that grid. |
| Right-click grid tab | Add or remove that grid from the selected set. Ctrl-click and Shift-click work too. |
| Mouse wheel | Scroll only the pane under the pointer; selected panes use GridBash scrollback. |
| Alt+k | Open the searchable command palette. Type to filter, use Up/Down to select, and press Enter to run an action. |
| Alt+Left / Alt+Right | Focus the previous or next pane in the row, wrapping at the edge. |
| Alt+Up / Alt+Down | Focus the pane above or below, wrapping at the edge. |
| Alt+l | Resize the current grid. |
| Alt+x | Swap two selected grids when any grids are selected; otherwise swap the two selected panes. |
| Alt+n | Open the new-grid screen and launch another tab. |
| Ctrl+Alt+t | Re-root the focused pane at an outside Git Bash window's folder. |
| Alt+t | Switch to the next tab. |
| Alt+w | Open the current-grid close confirmation. |
| Alt+s | Toggle selection of the focused pane. |
| Alt+Shift+s | Toggle selection of the current grid. |
| Alt+a | Select all panes, or clear the set when all are selected. |
| Alt+c | Open or close the current grid's BashBot Director command center. |
| Alt+Shift+C | Save bounded recent plain-text output from the focused or selected panes. |
| Alt+Shift+L | Start or stop continuous output logs for the focused or selected panes. |
| Alt+f | Zoom the focused pane to the full grid area, or restore the grid. |
| Alt+b | Open keyboard scrollback search and copy mode for the focused pane. |
| Alt+Shift+V | Dictate one utterance, or cancel active listening. |
| Alt+h / F1 | Open or close help. |
| Alt+p | Open the focused-pane activity summary. |
| Ctrl+Alt+p | Open the agent port inspector. |
| Alt+Shift+P | Open the previous-panes list. |
| Alt+Shift+A | Open Auth Profiles to manage accounts or assign one to the focused pane. |
| Alt+Shift+B | Move selected panes, or the focused pane, into the background and launch fresh replacements. |
| Alt+Ctrl+B | Open the session-wide background-agents list. |
| Alt+r | Rename the focused pane. |
| Alt+Shift+R | Rename the current tab. |
| Alt+Shift+T | Restart the exited focused pane, or all exited selected panes. |
| Alt+z | Sleep the focused pane, or all selected panes. |
| Hover sleeping pane | Wake it and reveal its terminal. |
| Alt+o | Open settings. |
| Alt+q | Save the workspace and open quit confirmation with its exact resume command. |
Drag selection is contained to its source pane and copies through the standard OSC 52 clipboard sequence. Use --no-mouse if the host terminal, serial link, or multiplexer cannot forward mouse reporting.
Keyboard copy mode snapshots the focused pane's bounded terminal history while
live PTY output continues in the background. Navigate with arrows, Home/End,
Ctrl+Home/Ctrl+End, and PageUp/PageDown. Press / to edit an incremental search,
Enter to finish the query, and n or N for the next or previous match. Space
starts character selection, V starts whole-line selection, and y copies the
selection through the same clipboard path as mouse selection. With no active
selection, y copies the current line. Escape, q, or Alt+B closes the viewer
and restores ordinary terminal input.
Output capture writes the same bounded, ANSI-stripped pane tail used for session
context. Continuous logging appends only new PTY output; submitted input,
environment variables, and sibling panes are never added separately. With
multiple selected panes, capture and logging create one file per selected pane;
otherwise they target the focused pane. Active logs show a rec pane badge.
Default collision-safe files live under GridBash's platform-local data output
directory, and every operation reports its resolved path. Agent API capture and
start-log calls may provide an explicit output directory. A write failure stops
only the affected log and is reported in the status bar.
When multiple panes are selected, typing is broadcast to them. With zero or one selected pane, input goes only to the focused pane.
Alt+C opens a bottom command center attached to the current grid. Tab switches between Chat and Shell. Shell preserves the grid's cwd, captured output, and cd, pwd, clear, and cls built-ins. Chat sends bounded, labeled output only from the current grid to the configured Manager endpoint. Ask explicitly to send, tell, delegate, or prompt when you want a one-shot targeted follow-up; ordinary briefs and prompt-writing requests do not authorize dispatch. Use /goal <objective> to keep supervising that grid and /stop to end the goal. BashBot Director posts only changed pane statuses plus sent or skipped delivery receipts. Commands remain bound to stable pane identities and are skipped if a pane sleeps, exits, disappears, or changes during review.
Enter sends or runs, Ctrl+U clears the active input, PageUp/PageDown scroll, Ctrl+Up/Ctrl+Down resizes the panel, and Esc or Alt+C closes it. Each grid keeps its own in-memory transcript, shell state, and goal while GridBash is running. That state is intentionally not written to session files.
The command palette lists the available pane, tab, grid, manager, settings, help, and quit actions together with their configured shortcuts. Its query supports tolerant subsequence matching, pasted Unicode text, and cursor editing. Palette input is never sent to a child terminal; press Esc or the configured command-palette shortcut to close it without running anything.
The close-grid confirmation names the grid, reports its pane count, and requires Enter or Y before GridBash terminates all of its visible panes, even when Keep terminals running is enabled. Escape or N cancels. After confirmation, GridBash removes the tab and activates the next grid or the previous grid when the closed one was last. GridBash never closes the only remaining grid; use Alt+q to quit the workspace. Managed worktrees and their branches are preserved.
Pane Activity provides auth, rename, refresh, sleep/wake, deactivate, and shortcuts into the BashBot Director goal flow. Navigate with Up/Down and activate with Enter or Space. Direct keys inside the view are n to rename, r to refresh, z to sleep or wake, d to deactivate, g to prefill /goal, and u to stop the current goal. Close it with Esc, q, or Alt+p; Alt+Shift+A opens Auth Profiles and Alt+o switches to overall settings.
The bottom-right Ports control counts TCP listeners launched inside GridBash agent process trees. Click it or press Ctrl+Alt+p to see each port, process name, PID, and owning pane or tab. Use Up/Down to select a listener, R to refresh, and Enter or Delete followed by Enter to terminate its process. GridBash excludes unrelated system listeners and its own pane-host control sockets from this view.
The bottom-right Ports control shows the most recent count of TCP listeners launched inside GridBash agent process trees. Click it or press Ctrl+Alt+p to scan and see each port, process name, PID, and owning pane or tab. Use Up/Down to select a listener, R to refresh, and Enter or Delete followed by Enter to terminate its process. Scanning is paused while the inspector is closed. GridBash excludes unrelated system listeners and its own pane-host control sockets from this view.
Deactivating a pane ends its terminal process, compacts the remaining panes, and shrinks the grid whenever a smaller dimension can still hold them. Columns are removed before rows, so deactivating two panes from a 2x3 grid compacts it to 2x2. The final pane cannot be deactivated.
Alt+Shift+B backgrounds every explicitly selected pane, or the focused pane when the selected set is empty. GridBash first launches fresh panes with the same profile, command, auth, folder, and worktree; only after all replacements succeed are the original PTYs moved into the session-wide pool. Custom pane names follow the original jobs, while fresh replacements return to numbered labels.
Alt+Ctrl+B opens Background Agents. Rows show whether each job is working, quiet, exited, or offline, together with its agent, source tab, folder/worktree, and latest activity. Use Up/Down to choose a row and Enter or Space to swap it into the focused cell; the displaced visible pane goes into the pool instead of being terminated. R explicitly restarts an exited or offline row. Delete removes exited/offline rows immediately and requires a second press before stopping a live process.
When an agent launched by GridBash exits normally, including through /exit, GridBash replaces it with the preferred interactive terminal in the pane's current directory. If another focused pane exits, Enter, r, or t restarts it, while z sleeps it. Alt+Shift+T performs the same restart directly for exited target panes.
The leader key
Terminals differ on whether they send Alt at all. Apple Terminal, iTerm2, and
Ghostty map Option to character composition by default, so Option+C produces
ç and none of the Alt shortcuts ever reach GridBash. The leader key replaces
the modifier with a first keystroke: press it, release it, then press the
shortcut key on its own.
Ctrl+G then c opens the command center, Ctrl+G then an arrow moves focus,
Ctrl+G then Shift+C captures output, and Ctrl+G then Ctrl+P opens Ports.
Ctrl+G then q quits. Esc backs out, and pressing the leader twice sends it
to the focused pane, so no pane loses the key. The status bar names the leader
while it is waiting.
GridBash enables the leader on macOS and leaves it off elsewhere, where Alt
arrives intact. Set it explicitly, or turn it off, in the [keys] table:
[keys]
leader = "ctrl+g" # "off" disables it
Enabling the terminal's own Option-as-Meta setting is the alternative and makes the Alt shortcuts work directly; the two can be used together.
Configurable shortcuts
Override application controls in the top-level [keys] table. Action names
use kebab case and chord values combine ctrl, alt, or shift with one
letter, an arrow name, or f2 through f12:
[keys]
zoom-pane = "ctrl+shift+k"
settings = "f8"
Supported actions are quit, help, focus-left, focus-right, focus-up,
focus-down, toggle-selection, toggle-grid-selection, select-all, sleep-panes, restart-panes,
next-tab, new-tab, close-grid, resize-grid, swap-panes, zoom-pane, command-line,
command-palette, bashbot, voice-input, edit-goal, stop-goal, settings, previous-panes, ports,
pane-activity, copy-mode, auth-profiles, capture-output,
toggle-output-logging, rename-tab, rename-pane, and adopt-terminal, plus
leader for the leader key. Unlisted actions retain their
defaults. Duplicate chords and unmodified terminal keys are rejected. F1 and
Alt+q remain reserved help and quit recovery paths; in-app help displays the
effective bindings.
The former bashbot, edit-goal, and stop-goal key actions were removed when
their separate surfaces moved into Alt+C. GridBash reports a migration error if
an existing [keys] table still contains one of those names; remove it and
customize command-line instead.
The resize picker starts from the current dimensions and shows each existing pane's latest activity summary when one is available. Shrinking a grid deactivates live panes outside the retained upper-left rectangle; changing 3x3 to 3x2, for example, removes the rightmost column.
A pane's top border carries its number and name on the left and its state on the right. Opt-in AI activity summaries add a concise work headline after the name once output settles; GridBash never uses raw typing or terminal UI fragments as the displayed summary. A configured manager goal replaces pane summaries across the grid until removed. Saving a blank pane name restores its default number.
Adopting an outside terminal
Ctrl+Alt+T lists the Git Bash windows running outside GridBash and re-roots the focused pane at the folder one of them is sitting in. Pick a row, then confirm; the pane's current shell is closed and replaced by one starting in that folder, and its managed worktree name is recomputed for the new location.
The outside window is never touched. It keeps its process and stays open, because Windows binds a process to the console it was created with and offers no way to hand a live process to another pseudoconsole — so what moves is the location, not the session. A window whose title does not reveal a folder is still listed, greyed out and unselectable, rather than being silently dropped.
Folders are read from the window title, which is where MSYS shells publish them: MINGW64:/c/Users/you/project, MSYS:~, and Cygwin's /cygdrive/c/... all resolve, and a title a running program has overwritten resolves to nothing rather than to a guess. This is Windows-only; elsewhere the picker reports that nothing was found.
The tab strip draws each grid as a separate capped shape rather than one continuous highlight: the current grid is filled with the accent colour, a grid whose agent is waiting on you is filled amber and marked •, an exited grid is marked !, and grids selected by hand are underlined. When the grids outrun the terminal width the strip scrolls to keep the current one visible and marks the hidden ends with ‹ and ›. Remaining width goes to the keyboard hints, which drop from the end as it runs out.
The status bar centres the focused pane's number, name, and AI activity summary, followed by how long that summary stays cached and a ⟳ control that refreshes it now. The countdown reads due once the cache is stale and ··· while a request is in flight, and the whole clock is the click target. It is shown only for panes that can actually be summarized — never for a sleeping or exited pane, one with summaries switched off, or while a manager goal has suspended them. When summaries are off or unconfigured, the centre says so instead of guessing from the shape of the output; a transient status message takes the centre for as long as it lasts, and a narrow terminal drops the pane name before the summary. Left of centre are the clickable Panes, Summary, and background-jobs chips, plus the input mode and scope only when they are not the ordinary ones; the ports chip stays anchored to the right edge.
The state on the right is whichever one matters most: exited, asleep, needs you, or idle. needs you marks an agent pane that has stopped producing output for roughly three seconds, which is how an agent asks for input — it indicates output followed by inactivity, not completion or process exit. A non-agent pane that goes quiet reads idle instead. As a pane narrows, its header drops its usage figure first, then its activity summary; the number, name, and state are kept. Focused and selected panes are marked by a filled number chip and a coloured border, which outrank a pane's own state.
Voice mode
Press Alt+Shift+V to listen for one utterance, for up to 15 seconds. The transcript goes to the active Director Chat or Shell input, or to the panes targeted when listening began. GridBash never presses Enter for dictated text, so it can be reviewed before submission. Press the shortcut again to cancel.
Windows
Windows dictation uses Microsoft's online speech service. Enable Online speech recognition under Privacy & security > Speech, allow desktop applications to use the microphone, and install the speech language pack for the desired dictation language. GridBash reports the platform error when a requirement is missing.
macOS
GridBash asks for Speech Recognition and Microphone access on first use. It prefers on-device recognition and uses Apple's authorized speech service when the current locale does not support local recognition.
Linux
Linux voice mode uses offline Whisper. The first shortcut explains that a 57 MiB model is required; press it again to approve the one-time download. GridBash checksum-verifies the model and stores it in the local XDG data directory, and audio stays on the machine.
Set GRIDBASH_VOICE_MODEL to use another local Whisper model or GRIDBASH_SPEECH_HELPER to replace the packaged helper. Capture uses ALSA and may need explicit device access in containers or remote sessions.
Terminal compatibility
GridBash targets modern UTF-8, ANSI/xterm-compatible terminals, including Windows Terminal, Apple Terminal, iTerm2, GNOME Terminal, Konsole, Kitty, WezTerm, and Alacritty.
SSH and tmux work when the remote session advertises a color-capable TERM. TERM=dumb and Linux kernel consoles are unsupported. On macOS the shortcuts are reachable out of the box through the leader key; configuring Option as Meta/Alt in Apple Terminal, iTerm2, or Ghostty makes the Alt chords work directly as well.
Launch profiles
Built-in terminal profiles are platform-specific:
| Platform | Profile keys |
|---|---|
| Windows | git-bash, pwsh, powershell, cmd |
| macOS | zsh, bash, fish, sh, pwsh |
| Linux | zsh, bash, fish, sh, pwsh |
Agent profiles available on every platform are codex, claude, gemini, opencode, aider, amp, goose, copilot, and cursor.
Inspect every built-in and custom profile with:
gridbash --list-profiles
The diagnostic table identifies the selected default, source, availability, resolved executable, or missing-command reason. It never prints profile environment values, auth tokens, or manager credentials. On Windows, GridBash resolves .exe and .cmd shims before extensionless npm shims.
Direct-launch profile selection uses this precedence:
--profileGRIDBASH_PROFILE- The invoking Windows shell detected by the npm launcher
[defaults].profile- The platform default
The platform default is Git Bash on Windows, zsh on macOS, and bash on other
Unix systems. On Windows, the npm launcher can inherit PowerShell, PowerShell 7
(pwsh), cmd, or Git Bash from the shell that invoked gridbash. Bare
interactive startup instead lists detected agents first and keeps terminals as
a secondary selection.
Define custom profiles under [profiles.<name>]:
[profiles.review]
command = "codex"
args = ["--model", "gpt-5.5"]
title = "Codex Review"
agent_kind = "codex"
Then launch it by key:
gridbash 2x4 --profile review
agent_kind is optional. Set it to claude or codex when the profile should participate in that agent's auth handling.
Configuration
The default configuration file is platform-specific:
| Platform | Path |
|---|---|
| Windows | %APPDATA%\GridBash\config\config.toml |
| macOS | $HOME/Library/Application Support/GridBash/config.toml |
| Linux | ${XDG_CONFIG_HOME:-$HOME/.config}/gridbash/config.toml |
Use --config PATH to load and save another file. A representative configuration is:
[defaults]
profile = "codex"
pane_priority = "below-normal" # or "normal"
pane_workload = "adaptive" # or "unrestricted"
[ui]
compact_titles = false
activity_badges = true
confirm_quit = true
keep_terminals_running = false
scrollback_rows = 10000
refresh_ms = 16
[manager]
activity_summaries = false # opt in before pane output is sent
endpoint = "https://api.openai.com/v1/chat/completions"
model = "gpt-4o-mini"
api_key = "sk-..."
[todos]
idle_seconds = 90
prompts = [
"Review the latest changes and summarize anything risky.",
"Run the fastest relevant validation and report failures.",
]
[auth]
home = "C:\\Users\\you\\.gridbash-auth"
auto_cycle = false
usage_status = true
[auth.defaults]
claude = "claude-1"
codex = "codex-2"
Settings persist compact titles, activity badges, quit confirmation, background-terminal behavior, new-pane scrollback, refresh delay, todo prompts, auth and workload policy, and the interface palette. Supported runtime changes apply immediately.
BashBot Director
The BashBot Director and AI activity summaries use the OpenAI-compatible chat-completions endpoint, model, and API key under [manager]. These values can also be edited in Settings > Manager. The UI masks the API key, but the key is stored in the local TOML file.
AI activity summaries are disabled by default. Enable them separately in Settings > Manager only when you want bounded recent output from eligible panes in the active tab sent to the configured endpoint. GridBash batches panes after roughly three seconds of quiet output, pauses them while a manager goal is present, and preserves the last successful headline across temporary API failures. Each pane then caches its summary for three minutes before another request may be spent on it, so a nine-pane grid costs at most twenty batched calls an hour; failures back off separately, doubling from thirty seconds up to five minutes. The status bar's ⟳ control and the Pane Activity refresh control both skip the cache and request an immediate update for one pane; pending input is never used as a displayed summary.
/goal in Alt+C Chat creates a goal for the current grid. Each review sends pane role and folder metadata plus bounded recent output from that grid to the configured API. Sleeping and exited panes are never command targets. Reviews label output by pane, report changed statuses in the transcript, and keep validated follow-ups bound to their intended PTYs if panes are reordered. Goals keep running when another grid is active; /stop ends only the current grid's goal.
Pane priority and workload
On Windows, the GridBash interface remains at normal process priority while pane processes default to below-normal; child workloads normally inherit the pane priority. Set [defaults].pane_priority = "normal" to opt out.
The default adaptive workload policy gives focused and selected panes more CPU time than hidden or sleeping panes when Windows is contested, while every pane keeps running. Set [defaults].pane_workload = "unrestricted" or change Workload policy in Performance settings to disable adaptive sharing.
Auth profiles
GridBash can isolate Claude and Codex accounts in named directories. The auth home is resolved in this order:
GRIDBASH_AUTH_HOME > [auth].home > CLAUDE_PROFILES_HOME (legacy) > ~/.gridbash-auth
Claude panes receive CLAUDE_CONFIG_DIR=<profile-dir> and Codex panes receive CODEX_HOME=<profile-dir>.
The old default was ~/.claude-profiles; profiles are not moved automatically. Move them to ~/.gridbash-auth, point [auth].home at the old location, or keep the legacy CLAUDE_PROFILES_HOME override.
Assignment is manual by default: a new pane uses the configured default for its agent kind, while an explicit per-pane selection is retained. With auto_cycle = true, new compatible panes are assigned round-robin across ready profiles of the same kind. Changing the policy does not restart panes already running.
Press Alt+Shift+A to open the dedicated Auth Profiles view. A managed profile is an isolated Claude or Codex home: it keeps that account's login, agent settings, sessions, and usage separate from the normal agent home and from other profiles. The view keeps two actions distinct:
- Focused pane: highlighting a compatible profile and pressing Enter assigns it immediately, which restarts that pane.
- New pane policy: per-agent defaults or round-robin assignment apply only when compatible panes start. They do not change panes already running.
Auth settings controls
| Input | Action |
|---|---|
| Tab | Switch Settings tabs. |
| Up / Down | Move through profiles. |
| Enter | Assign the selected compatible profile to the focused pane and restart that pane. |
d | Make the selected profile the GridBash-wide default for its kind. |
c | Toggle per-agent defaults and round-robin assignment for new panes. |
n | Create a profile directory. |
l | Open the selected profile's login command. |
r | Refresh local account and usage status. |
Esc / q | Close settings. |
The focused pane can also be switched from Pane Activity: press Alt+p, select the auth control with Up/Down, choose a compatible profile with Left/Right, and press Enter. Applying a different account restarts only that pane. Press r in Pane Activity to refresh its snapshot.
Usage reporting is best-effort. GridBash reads local auth metadata, masks account email addresses, and makes short-timeout requests with curl.exe on Windows or curl on macOS only when the Auth view is refreshed. Disable it with usage_status = false.
Codex SQLite isolation
GridBash leases each pane a unique, persistent CODEX_SQLITE_HOME, including terminal-profile panes where Codex is started manually. Lanes are separated by CODEX_HOME, protected by cross-process file locks, and reused only after their previous pane releases the lease. This prevents concurrent Codex processes from contending for the same SQLite databases while auth, configuration, skills, and rollout files remain shared within CODEX_HOME.
The first use of a new lane can be slower while Codex indexes existing rollouts. SQLite-only state, including goals, memories, and thread relationships, remains local to that lane.
A non-empty CODEX_SQLITE_HOME inherited by GridBash opts out of automatic isolation and is preserved. Codex's sqlite_home configuration keeps its normal precedence. Do not point concurrent panes at the same override, or SQLite lock contention can return.