Terminal Detach

Detach VS Code's integrated terminal into a standalone, resizable floating window.

What It Does

Terminal Detach allows you to pop out VS Code's built-in terminal and debug console into their own standalone, draggable, resizable floating windows — while keeping all your running processes alive and your scroll position intact.

Key Features

• Detach Terminal — Right-click any terminal tab → "Detach Terminal" to pop it into a new window
• Attach Terminal — One click to bring it back into the main VS Code panel
• Toggle with Keyboard — Ctrl+Shift+D (Windows/Linux) or Cmd+Shift+D (macOS) to instantly toggle
• Debug Console Support — Detach the Debug Console too
• Session Persistence — Running processes (servers, builds, scripts) continue uninterrupted
• Scroll Position Preserved — You won't jump back to line 1 when detaching or re-attaching
• Window Memory — Position and size are remembered across VS Code restarts
• Cross-Platform — Works on Windows, macOS, and Linux

Installation

From VS Code Marketplace

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
3. Search for "Terminal Detach"
4. Click Install

From Open VSX Registry (for VSCodium, Gitpod, etc.)

1. Open your editor
2. Go to Extensions
3. Search for "Terminal Detach" by AceLozabe
4. Click Install

From VSIX (Manual)

1. Download the .vsix file from the Releases page
2. In VS Code, go to Extensions → ... (top right) → Install from VSIX...
3. Select the downloaded .vsix file

How to Use

Detach a Terminal

Method 1: Right-Click (Fastest)

1. Open the integrated terminal (Ctrl+`` / Cmd+ `)
2. Right-click on the terminal tab
3. Select "Detach Terminal"

Method 2: Command Palette

1. Press Ctrl+Shift+P / Cmd+Shift+P
2. Type "Detach Terminal"
3. Press Enter

Method 3: Keyboard Shortcut

1. Make sure the terminal is focused
2. Press Ctrl+Shift+D (Windows/Linux) or Cmd+Shift+D (macOS)

Attach (Re-Dock) a Terminal

Method 1: Right-Click

1. Right-click on the detached terminal tab
2. Select "Attach Terminal"

Method 2: Command Palette

1. Press Ctrl+Shift+P / Cmd+Shift+P
2. Type "Attach Terminal"
3. Press Enter

Method 3: Keyboard Shortcut

1. Press the same toggle shortcut: Ctrl+Shift+D / Cmd+Shift+D

Detach the Debug Console

1. Start a debugging session
2. Open the Debug Console
3. Right-click the Debug Console tab → "Detach Debug Console"
4. Or use Command Palette → "Detach Debug Console"

Configuration

Open VS Code settings (Ctrl+, / Cmd+,) and search for "Terminal Detach".

Example settings.json

{
  "terminalDetach.defaultWidth": 1000,
  "terminalDetach.defaultHeight": 600,
  "terminalDetach.rememberPosition": true,
  "terminalDetach.alwaysOnTop": false,
  "terminalDetach.windowOpacity": 1.0,
  "terminalDetach.showInTaskbar": true,
  "terminalDetach.preserveScrollPosition": true,
  "terminalDetach.debugConsoleSupport": true
}

Keyboard Shortcuts

You can customize these in File → Preferences → Keyboard Shortcuts and search for "Terminal Detach".

Known Limitations

• One detached terminal at a time — Only one terminal can be detached per VS Code window. If you need multiple detached terminals, open multiple VS Code windows.
• Terminal color themes — Custom terminal color themes may reset to default when re-attached. The running processes are completely unaffected.
• Linux opacity — The windowOpacity setting may not work on some Linux desktop environments (depends on compositor support).
• Debug console — Requires the debug console to be visible in the editor area before detaching.
• Window state — VS Code handles the actual window creation; this extension orchestrates the detach/attach commands and manages state persistence.

Contributing

Contributions are welcome! Here's how to get started:

1. Fork the repository on GitHub
2. Clone your fork locally
3. Install dependencies: npm install
4. Open in VS Code and press F5 to run the extension in a new Extension Development Host window
5. Make your changes and test thoroughly
6. Run tests: npm test
7. Submit a Pull Request

Please read our Contributing Guidelines for more details.

Development Setup

# Clone the repo
git clone https://github.com/AceLozabe/terminal-detach.git
cd terminal-detach

# Install dependencies
npm install

# Compile TypeScript
npm run compile

# Watch mode (auto-recompile on changes)
npm run watch

# Run tests
npm test

# Package as .vsix
npm run package

Publishing to Marketplaces

Prerequisites

Before publishing, ensure you have:

• Node.js 18+ installed
• A VS Code Marketplace publisher account
• An Open VSX Registry account (Eclipse Foundation account)

Step 1: Install Publishing Tools

npm install -g @vscode/vsce ovsx

Step 2: Login to Marketplaces

VS Code Marketplace:

vsce login AceLozabe
# Enter your Personal Access Token when prompted

Open VSX Registry:

ovsx create-namespace AceLozabe
ovsx login AceLozabe
# Enter your Open VSX access token when prompted

Step 3: Update Version

Update the version in package.json following Semantic Versioning:

# Patch (bug fixes)
npm version patch

# Minor (new features, backward compatible)
npm version minor

# Major (breaking changes)
npm version major

Step 4: Publish

Publish to VS Code Marketplace:

npm run publish:marketplace
# or
vsce publish

Publish to Open VSX Registry:

npm run publish:openvsx
# or
ovsx publish

Package as .vsix (for manual distribution):

npm run package
# Creates: terminal-detach-1.0.0.vsix

Step 5: Create GitHub Release

1. Go to your repo on GitHub → Releases → Draft a new release
2. Choose the tag matching your version (e.g., v1.0.0)
3. Add release notes from CHANGELOG.md
4. Attach the .vsix file
5. Publish the release

Adding This Extension to a New GitHub Repo

If you want to add this extension code to a newly created GitHub repository:

Step 1: Create the Repo on GitHub

1. Go to github.com/new
2. Name it terminal-detach
3. Make it Public
4. DO NOT initialize with README, .gitignore, or license (we already have these)
5. Click Create repository

Step 2: Initialize and Push

# Navigate to the extension folder
cd terminal-detach

# Initialize git (if not already)
git init

# Add all files
git add .

# Commit
git commit -m "Initial commit: Terminal Detach extension v1.0.0"

# Add remote (replace with your actual repo URL)
git remote add origin https://github.com/AceLozabe/terminal-detach.git

# Push to main branch
git branch -M main
git push -u origin main

Step 3: Verify

Your repo should now contain:

terminal-detach/
├── .eslintrc.json
├── .gitignore
├── .vscodeignore
├── CHANGELOG.md
├── LICENSE
├── README.md
├── images/
│   ├── icon.png
│   └── icon-small.png
├── package.json
├── src/
│   ├── extension.ts
│   └── test/
│       ├── extension.test.ts
│       ├── runTest.ts
│       └── suite/
│           └── index.ts
└── tsconfig.json

License

This project is licensed under the MIT License — see the LICENSE file for details.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: ace.lozabe1@gmail.com

Made with ❤️ by Ace Lozabe from the Philippines

Free and open source for the community 🌏