The vibe-coding cockpit.
Spin up a grid of AI agent CLIs and SSH terminals in seconds, talk to them out loud,
and keep your files, Git, and a live app preview in the same window.
| A grid, not a tab pile | Pick 1, 2, 3, 4, 6, or 8 panes, pick a target per pane, hit launch. SSH, WSL, PowerShell, cmd, or a local repo — side by side, resizable, splittable. |
| Agents are a dropdown, not a chore | Six agent CLIs are first-class pane types, most with an Auto mode toggle. GridVibe detects them on the target machine before you launch, so you find out about a missing binary before the pane opens. |
| Talk to your agents | Fully offline voice input (Vosk or faster-whisper) dictates straight into any pane. Push-to-talk keybind included. Off by default. |
| Set it up once | Save a tab as a preset, save the whole workspace, restart, get it all back — right down to which group you were working in. |
Everything else — the file explorer, the Git sidebar, the browser preview — exists so you never have to leave the grid mid-flow.
| Launcher | Agents | Terminal Workspace | Browser | App Settings |
|---|---|---|---|---|
 |
 |
 |
 |
 |
Python 3.10+ is the only prerequisite. The launcher scripts create and repair the virtual environment, install dependencies, and start the app.
# Windows
.\START_HERE\Start GridVibe.bat# Linux / macOS
sudo apt install python3 python3-venv python3-pip # Debian/Ubuntu
chmod +x GridVibe.sh && ./GridVibe.sh# Manual, any platform
python -m venv .venv
source .venv/bin/activate # Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install --upgrade -r requirements.txt
python main.py # → http://localhost:5050Both launchers ask for Desktop (native window) or Browser mode. Core requirements already include pywinpty on Windows, so local cmd/PowerShell/WSL panes work in browser mode too. For a native window, also install requirements-desktop.txt.
| Get it | Update it | |
|---|---|---|
| Clone (recommended) | git clone https://github.com/JSstudent/gridvibe.git |
The launcher's Check for updates button fast-forwards in place |
| Release ZIP (no Git) | Source code (zip) from Releases | Download the next release — in-app update needs a clone, and says so |
A Windows installer that bundles Python is planned for 2.0.0.
python main.py # browser mode on http://localhost:5050
python main.py --host 0.0.0.0 # bind all interfaces (opt-in)
python main.py --port 8080 # custom port
python webview_launcher.py # auto: native window, browser fallback
python webview_launcher.py --mode browser|nativePick an agent per pane in the launcher. GridVibe checks whether the binary is on PATH in the target environment (the remote host for SSH, the chosen distro for WSL, Windows for PowerShell/cmd) and shows install guidance when it isn't.
| Agent | Binary | Auto mode |
|---|---|---|
| Claude Code | claude |
Yes |
| OpenAI Codex CLI | codex |
Yes |
| GitHub Copilot CLI | copilot |
Yes |
| OpenCode CLI | opencode |
— |
| Kilo CLI | kilo |
Yes |
| Kimi Code CLI | kimi |
Yes |
GridVibe does not bundle the CLIs. If everything shows Missing, install it and put its folder on PATH — for npm-installed agents on Windows that is usually %APPDATA%\npm (check with npm prefix -g). Restart GridVibe after PATH changes.
Optional, fully offline, off by default. Turn it on in App Settings (the gear on either page), pick a backend (Vosk or faster-whisper), a language, and optionally a capture profile, microphone, and push-to-talk keybind. Then hit the 🎙️ button on any pane.
If the packages are missing, App Settings says so and offers Install voice dependencies — installed into GridVibe's own environment and loaded without a restart. Or do it yourself:
python -m pip install --upgrade -r requirements-voice.txtBrowser mode is the most reliable for microphone permissions. Settings apply live to open workspace tabs. Details: docs/voice_guideline.md.
| Session tabs | Keep related panes together in draggable tabs. Use Alt+1–Alt+9 to switch, middle-click to close, or broadcast typing to every pane in the active tab. |
| Saved sessions | Save a setup as a reusable preset, import one later, or choose New Session for a clean start. Stored SSH passwords are encrypted. |
| Save & restore | GridVibe autosaves your workspace and also offers Save Workspace. After a restart, restore the same tabs, pane layouts, directories, commands, and active group; passwords are never written to the workspace snapshot. |
| Multiple workspaces | Optionally keep separate projects in separate windows, move tabs between them without restarting terminals, and switch with Alt+W / Alt+Shift+W. |
| Updates | Check for updates fast-forwards a Git clone, with an option to save the workspace and restart. |
Closing a workspace ends its terminals but keeps it available to restore. Close and forget removes both the live workspace and its snapshot, while closing only the window leaves its terminals running. Closing the last tab removes an empty workspace.
Swap any pane between a terminal and a file explorer with one button — same directory, no re-navigation. Works on a local repo folder or a remote host over SFTP.
| Browse & preview | Use breadcrumbs, a lazy file tree, draggable file tabs, syntax-coloured source, rendered Markdown and Mermaid, inline images, downloads, and Ctrl+F find. |
| Edit | Edit complete UTF-8 text files in place and save with Ctrl+S. Saves are atomic, and a conflict prompt protects files changed on disk. |
| Git | See branch and file status, inspect current or historical diffs, and stage, unstage, commit, publish, or discard changes. Diff views also support line and block undo. |
| Search | Press Ctrl+Shift+F for repository-wide search with case, whole-word, regex, file-pattern, scope, and .gitignore controls. |
| Manage files | Create, copy, move, rename, and delete from the context menu. Every write stays inside the explorer root; collisions never overwrite existing files, and deletion requires confirmation. |
Uploading, cross-root transfers, and Git checkout, pull, or merge are intentionally left to the terminal.
Launched a pane in cmd and wanted PowerShell — or WSL? Click the pane's 🔄 button: on a Local Repo terminal it's a dropdown with Reset view on top and a Shell section listing Command Prompt, PowerShell, WSL (default distro) and every detected distro. Picking one restarts that pane's shell in place — same slot, same title, same startup command — starting in the directory the old shell was sitting in. Windows hosts only; SSH, explorer, and browser panes keep the plain one-click reset.
Flip a Local Repo pane to a browser preview (the 🌐 button) and watch the app you're building next to the terminal running it.
- Tabbed — up to 8 tabs, per-tab close, drag to reorder, + opens a blank tab at
http://127.0.0.1:3000. Each tab keeps its own live frame, so switching or reordering never reloads your app. - URL bar navigates the active tab (http/https only); Open kicks it out to a real OS browser tab.
- Same-origin popups get captured into new pane tabs instead of escaping — which is what lets you drive GridVibe's own launcher → workspace flow inside a pane. Named window targets reuse their tab rather than stacking up. Cross-origin pages can't be instrumented by anyone, so their popups still open externally.
- Nested preview is capped one level deep — a GridVibe page already inside a pane shows a Nested preview disabled notice instead of re-embedding itself forever.
- The whole tab strip saves and restores with the workspace and with session presets.
GridVibe does not proxy pages or bypass X-Frame-Options/CSP, so sites that block embedding need Open.
Pane header:
| Does | |
|---|---|
| 🔄 | Reset the view and replay recent output (reloads explorer and browser panes). On a Local Repo terminal it opens a dropdown: Reset view plus a Shell section that restarts the pane in cmd, PowerShell, or a WSL distro |
| 📁 ⇄ 💻 | Swap between terminal and file explorer at the current directory |
| 🌐 ⇄ 💻 | Swap a Local Repo pane between terminal and browser preview |
| 🪟 | Split side-by-side or stacked. A terminal clones its connection; an explorer or browser pane splits off a terminal instead — for both SSH and Local Repo — rooted where the explorer is currently browsing |
| 🧹 | Clear the display and purge the replay buffer |
| 🎙️ | Start/stop voice input (when enabled) |
| 🌙 ⇄ ☀️ | Toggle an explorer pane between dark and light |
| ⋯ | Overflow menu, shown when the pane is too narrow for the full row |
| ✖️ | Close the pane (confirms first — it's a live session) |
Explorer bar:
| Does | |
|---|---|
| 🔄 | Refresh the explorer (F5) |
| ⬆️ | Go to the parent directory (or mouse Back) |
| 🗂️ | Files tree sidebar |
| ⎇ | Git changes and history sidebar |
| 🔍 | Repository search sidebar (Ctrl+Shift+F) |
| 🖥️ | Reveal the current location in the system file manager (local panes only) |
Top bar: theme · refresh all · max surface · broadcast typing · fullscreen · App Settings · chevron to hide the bar. Plus a Workspace… menu and a Sessions… menu.
Session tab line: the back-to-launcher button sits at the head of the tab line, ahead of the first tab, so it stays reachable with the top bar hidden.
| Shortcut | Action |
|---|---|
Alt+` |
Open the launcher (the key left of 1) |
Alt+1–Alt+9 |
Switch session group |
Alt+W / Alt+Shift+W |
Next / previous workspace window (multiple workspaces only) — the window you land in pulses once |
Ctrl+Shift+F |
Terminal scrollback search — or, on an explorer pane, toggle repository search |
Ctrl+F |
Find in the open file |
Ctrl+Shift+V |
Toggle Markdown rendered preview |
Ctrl+S / Esc |
Save / cancel in the explorer editor |
F5 |
Refresh the focused explorer |
Drag the dividers between panes to resize them.
Everything lives in App Settings — same dialog from the gear on the launcher or the session window, so settings never need a trip back to the launcher. It covers theme, surface mode, terminal font and size, max sessions, workspace autosave interval, SSH host-key policy, and all voice options. The one exception is Multiple workspaces: it changes what every launch does, so its switch sits in the launcher's Workspaces card instead of the dialog.
On disk, settings load from config.json (git-ignored) falling back to default_config.json:
{
"server": { "host": "127.0.0.1", "port": 5050 },
"appearance": { "theme": "dark" },
"terminal": { "max_sessions": 16, "font_size": 14 },
"workspace": { "surface_mode": "normal", "autosave_interval_minutes": 5, "multi_workspace_enabled": false },
"ssh": { "host_key_policy": "auto-add" },
"explorer_search": { "max_files": 2000, "max_matches": 5000, "timeout_seconds": 20 }
}GridVibe generates a Flask session signing key at startup unless GRIDVIBE_SECRET_KEY, SECRET_KEY, or security.secret_key is set.
GridVibe is a local tool, not a public web service: it binds to 127.0.0.1 by default, has no built-in authentication, and should not be exposed to the internet.
- Socket.IO CORS defaults to same-origin; state-changing cross-origin requests are rejected. Set
security.cors_originsonly if you serve GridVibe from another origin. - SSH host keys persist to
.known_hosts;ssh.host_key_policycan beauto-add(default),known-hosts, orstrict. - Saved SSH passwords are Fernet-encrypted; the key lives in
.encryption_key.
See SECURITY.md for reporting and scope.
make check # test + lint, run this before handing work back
make test lint fix # individually
# Windows without make:
python tests/run_tests.py
python -m ruff check .Backend lives in the modular web/ package (app.py, api.py, agents.py, terminal_io.py, explorer.py, explorer_search.py, voice.py, …), session state in sessions/manager.py, the voice service in services/, and the two pages in templates/ with assets in web/static/. Root-level api.py, session_manager.py, cleanup.py, and webview_launcher.py are compatibility shims — edit the canonical modules.
More: CONTRIBUTING.md · CHANGELOG.md · docs/logging_guide.md · docs/voice_guideline.md
Created at runtime, never committed:
| File | Purpose |
|---|---|
config.json |
Local runtime configuration override |
saved_sessions.json |
Saved launcher presets (encrypted passwords) |
runtime_state.json |
Workspace-shape snapshot for restore-after-restart |
.known_hosts |
Persisted SSH host keys |
.encryption_key |
Fernet key for password encryption |
logs/gridvibe.log |
Main rotating log file |
MIT. See LICENSE.