Terminal Workspaces

A VS Code extension for managing terminal sessions with a visual sidebar interface. Supports WSL, tmux, Zellij, PowerShell, nested folder organization, profiles, and more.

Features

• Visual Sidebar - Manage all terminal tasks from a dedicated tree view
• Active Status Indicators - Green dot when terminal is open, grey when inactive
• Right-Click Integration - Add folders from Explorer, files, or terminals
• Nested Organization - Group tasks into folders for better organization
• Terminal Profiles - WSL, tmux, Zellij, PowerShell, CMD, bash with customizable settings
• Multiplexer Integration - tmux and Zellij support with attach-or-create sessions, discover untracked sessions
• Editor Area Terminals - Open terminals in the editor area for 2D grid layouts
• Quick Search - Find and run tasks instantly with fuzzy search
• Path Validation - Experimental feature to detect and fix broken paths

Quick Start

1. Install the extension
2. Click the Terminal Workspaces icon in the Activity Bar
3. Click the + button or right-click a folder in Explorer → "Add Folder"
4. Choose a profile and configure your task
5. Click the play button to launch your terminal

Requirements for tmux/Zellij

tmux and Zellij are Linux-only tools. On Windows, they require WSL.

Requirement	Details
WSL	Required on Windows. Install via wsl --install
tmux	Install via sudo apt install tmux (goes to /usr/bin/)
Zellij	Install to /usr/local/bin/ (see below)

VS Code Modes and Detection

Terminal Workspaces detects tmux/Zellij sessions in two VS Code modes:

VS Code Mode	How to Enter	Detection Method
WSL Remote (recommended)	code . from WSL terminal, or "Remote-WSL: New Window"	Direct Linux commands
Windows Local	Open VS Code from Start Menu, open Windows path	Via wsl.exe

Both modes work, but there's a critical PATH requirement for Windows Local mode:

Installation Requirements

Tools must be installed to a system-wide location (/usr/bin/ or /usr/local/bin/), NOT user directories like ~/.local/bin/.

Why? When VS Code runs in Windows Local mode, it uses wsl.exe -e which zellij to detect tools. This spawns a non-interactive shell that doesn't load ~/.bashrc, so ~/.local/bin/ isn't in PATH.

Install Location	WSL Remote Mode	Windows Local Mode
/usr/bin/ (apt install)	✅ Works	✅ Works
/usr/local/bin/	✅ Works	✅ Works
~/.local/bin/	✅ Works	❌ Not detected
~/.cargo/bin/	✅ Works	❌ Not detected

Installing tmux

sudo apt install tmux

Installing Zellij (System-Wide)

# Download and install to /usr/local/bin/
curl -L https://github.com/zellij-org/zellij/releases/latest/download/zellij-x86_64-unknown-linux-musl.tar.gz | tar xz
sudo mv zellij /usr/local/bin/

⚠️ Already installed to ~/.local/bin/? Move it: sudo mv ~/.local/bin/zellij /usr/local/bin/

Keyboard Shortcuts

Shortcut	Action
Ctrl+Shift+Alt+T	Run all terminal tasks
Ctrl+Shift+Alt+A	Add new task
Ctrl+Shift+Alt+O	Quick open task manager

Documentation

• User Guide - Complete usage instructions
• Configuration - Settings, profiles, and customization
• tmux Integration - Working with tmux and Zellij sessions
• Workflows - Recommended workflow patterns

For Developers

• Architecture - Codebase overview
• Contributing - How to contribute
• Building - Build and test instructions

Configuration Highlights

{
  // Default terminal profile
  "terminalWorkspaces.defaultProfile": "wsl-tmux",

  // Open terminals in editor area (enables 2D grid layouts) or panel
  "terminalWorkspaces.terminalLocation": "editor", // or "panel" (default)

  // Auto-generate tasks.json from terminal-workspaces.json
  "terminalWorkspaces.autoGenerateTasksJson": true,

  // Validate paths before running (experimental)
  "terminalWorkspaces.experimentalPathValidation": true
}

See Configuration for all options.

Why Terminal Workspaces?

Problem: Managing multiple projects means constantly cd-ing to different directories and setting up terminal sessions.

Solution: Define your terminal configurations once, organize them visually, and launch them with a single click. Perfect for:

• Multi-project monorepos
• Microservices development
• Switching between work and personal projects
• Persistent tmux/Zellij sessions across SSH connections

Agentic Coding Workflows

Terminal Workspaces shines when working with Claude Code, Cursor, Aider, and other AI coding agents:

• Multi-Agent Sessions - Run multiple Claude Code instances in different project directories simultaneously
• Quick Context Switching - Jump between agent conversations across different codebases with one click
• Session Persistence - Keep agent sessions alive with tmux/Zellij even when VS Code restarts or SSH disconnects
• Organized Workspaces - Group related projects together (frontend + backend + docs) for full-stack agent workflows
• Session Recovery - Reconnect to running tmux/Zellij sessions where your agents are still working

Example workflow:

1. Create tasks for each project in your stack
2. Launch Claude Code in each terminal with tmux or Zellij profiles
3. Switch between agent conversations as needed
4. Close VS Code, come back later, reattach to all sessions still running

Mobile + Desktop Seamless Coding

The ultimate setup for coding anywhere with full session persistence:

┌─────────────┐     Tailscale      ┌───────────────────────────┐
│   Phone     │◄──────SSH─────────►│  Windows PC               │
│   Termux    │                    │  WSL + multiplexer        │
│             │                    │  (tmux or Zellij)         │
│             │                    │  + Claude Code            │
└─────────────┘                    └───────────────────────────┘
       │                                    │
       └────────► Same sessions ◄───────────┘

The Stack:

• Tailscale - Secure mesh VPN connecting all your devices
• WSL - Linux environment on Windows running your dev setup
• tmux or Zellij - Session persistence that survives disconnects (Zellij works better with some TUI apps like OpenCode)
• Termux - Full Linux terminal on Android
• Terminal Workspaces - Visual organization of all your project sessions

How it works:

1. Set up Tailscale on your PC and phone
2. Enable Tailscale SSH to your WSL instance
3. Create tmux or Zellij profile tasks for each project in Terminal Workspaces
4. Start Claude Code sessions in each terminal
5. Walk away from your PC...
6. SSH from Termux on your phone → tmux attach or zellij attach → you're right where you left off
7. Come back to VS Code → click to reattach all sessions

Your AI agents keep working. Your sessions never die. Code from anywhere.

VS Code Terminal Layout Tips

VS Code's bottom panel only splits horizontally. For complex terminal layouts:

Action	How
Split terminal side-by-side	Ctrl+Shift+5 or click split icon
Open terminals in editor area	Set terminalWorkspaces.terminalLocation to "editor" (enables 2D grid layouts)
Move existing terminal to editor	Right-click tab → "Move to Editor Area"
Focus between panes	Alt+Arrow keys
Rename terminal	Right-click tab → "Rename"
Secondary side panel	View → Appearance → Secondary Side Bar (drag terminals there)

Pro tip: Set terminalLocation to "editor" for full grid layouts. You lose "always at bottom" but gain the ability to split in any direction.

Terminal Lock Icon

You may notice a lock icon on terminal tabs in the editor area:

Icon	Meaning
Locked	Terminal tab won't be reused. New terminals create duplicate tabs.
Unlocked	VS Code can reuse this terminal tab when opening new terminals.

To toggle: Click the lock icon on the terminal tab.

Why this matters: When terminalLocation is set to "editor", VS Code may try to reuse existing terminal tabs. If you want each task to have its own persistent tab, keep them locked. Terminal Workspaces v0.4.5+ handles this automatically with improved terminal reuse logic.

Companion Extensions

These extensions pair well with Terminal Workspaces:

Extension	Why
Project Manager	Quick-switch between projects. Combine with multi-root workspaces to have multiple project folders + their terminals open together.
Multi-command	Chain commands together - e.g., open project + run all terminals in one keybinding.
Terminal Paste Image	Paste images directly into terminals - handy for AI coding agents that accept image input.

Multi-root workspace tip: File → Add Folder to Workspace lets you have multiple project folders in the sidebar at once. Each can have its own terminal-workspaces.json config.

License

MIT

Links

• GitHub Repository
• Report Issues
• VS Code Marketplace