VS Code Sidebar Terminal

A powerful VS Code extension that displays a terminal in the sidebar for efficient development workflow. Seamlessly integrated into the Primary Sidebar (left side) alongside other views.

📸 Screenshots

Main Interface

Terminal integrated into VS Code sidebar with multiple tabs and controls

Multiple Terminals

Manage multiple terminal sessions with easy tab switching

Split Terminal View

Split terminal functionality for parallel command execution

🎬 Demos

Basic Usage

Quick demonstration of opening terminal and running commands

Terminal Management

Creating, switching, and managing multiple terminals

Settings Configuration

Customizing font size, theme, and other settings

🚀 Features

• Sidebar Integration: Terminal integrated into Primary Sidebar (left side)
• Multiple Terminal Management: Run up to 5 terminals simultaneously
• Session Persistence: Automatic terminal session restore after VS Code restart
• Full Terminal Functionality: Complete shell execution environment powered by node-pty
• ✅ VS Code Standard Behavior: Arrow keys work perfectly for bash history, tab completion, and cursor movement
• Special Key Support: Backspace, Ctrl+C, Ctrl+L, and other special key combinations
• Intuitive Controls: Clear, New, and Split buttons for easy terminal management
• IME Support: Multi-language input support including Japanese, Chinese, and Korean
• CLI Agent Integration: File reference shortcuts for Claude Code and GitHub Copilot
• Cross-Platform: Full support for Windows, macOS, and Linux with native binaries
• Alt+Click Cursor Positioning: VS Code-standard Alt+Click to move cursor (with CLI Agent detection)

📦 Installation

From VS Code Marketplace

1. Open VS Code
2. Open Extensions panel (Ctrl+Shift+X or Cmd+Shift+X)
3. Search for "Sidebar Terminal"
4. Click Install

Manual Installation

1. Download the latest .vsix file from Releases
2. Open VS Code and press Ctrl+Shift+P (Cmd+Shift+P on Mac)
3. Select "Extensions: Install from VSIX..."
4. Choose the downloaded .vsix file

🎯 Usage

Basic Operations

1. Open Terminal: Click "Terminal" view in the Explorer panel
2. Create New Terminal: Click the "New" button in the terminal header
3. Split Terminal: Click the "Split" button to create a split view
4. Clear Terminal: Click the "Clear" button to clear the active terminal
5. Execute Commands: Type commands as you would in any terminal

Sidebar Placement

Primary Sidebar (Left Side)

• Terminal appears in the Explorer panel on the left side
• Integrated with other sidebar views, switchable via tabs
• Maintains context when switching between views

Command Palette

• Sidebar Terminal: Create New Terminal - Create a new terminal instance
• Sidebar Terminal: Split Terminal - Split the current terminal
• Sidebar Terminal: Clear Terminal - Clear the active terminal
• Sidebar Terminal: Kill Terminal - Terminate the active terminal

✅ Terminal Functionality (v0.1.43 Update)

• Arrow Key Navigation: ↑↓ keys work perfectly for bash command history navigation
• Tab Completion: Shell completion functions exactly like VS Code integrated terminal
• Cursor Movement: ←→ keys provide natural text editing and cursor positioning
• Standard Terminal Shortcuts: All Ctrl+C, Ctrl+L, and other shortcuts work as expected

Alt+Click Cursor Positioning

• Standard VS Code Behavior: Alt+Click to move cursor to mouse position
• Visual Feedback: Blue highlight shows cursor position with fade animation
• Requirements: Both terminal.integrated.altClickMovesCursor and editor.multiCursorModifier: "alt" must be enabled

🤖 CLI Agent Integration

• File Reference Shortcuts: Use Cmd+Option+L (Mac) or Alt+Ctrl+L (Linux/Windows) to insert @filename references
• GitHub Copilot Integration: Use Cmd+K Cmd+C (Mac) or Ctrl+K Ctrl+C (Windows/Linux) for #file:filename format
• Advanced Status Management: Real-time CLI Agent state tracking with CONNECTED/DISCONNECTED/NONE status display
• Auto-Promotion Logic: Seamless transition from DISCONNECTED to CONNECTED when agents terminate
• Reliable State Sync: Full state synchronization system ensures accurate status display across multiple terminals
• Independent Operation: Works alongside CLI Agent extensions without conflicts
• Configurable: Both integrations can be independently enabled/disabled in settings

🔄 Session Persistence

• Automatic Restore: Terminal contents and state restored after VS Code restart
• Scrollback History: Up to 1000 lines of terminal history preserved per terminal
• Multi-Terminal Support: All terminals (up to 5) restored with their individual states
• Configurable: Session persistence can be customized or disabled

⌨️ Keyboard Shortcuts

• CLI Agent File Reference: CMD+OPT+L (Mac) / Ctrl+Alt+L (Windows/Linux) - Insert @filename reference
• GitHub Copilot Integration: CMD+K CMD+C (Mac) / Ctrl+K Ctrl+C (Windows/Linux) - Activate Copilot Chat with file reference
• Alt+Click: Cursor positioning (when enabled in VS Code settings)

⚙️ Configuration

Customize the extension through VS Code settings (settings.json):

🛠️ Development

Prerequisites

• Node.js 18+
• VS Code 1.74.0+
• npm or yarn

Setup

# Clone the repository
git clone https://github.com/s-hiraoku/vscode-sidebar-terminal.git
cd vscode-sidebar-terminal

# Install dependencies
npm install

# Development build
npm run compile

# Watch mode for development
npm run watch

Testing

# Run unit tests with coverage
npm run test:unit

# Run all tests
npm test

# Run linter
npm run lint

# Format code
npm run format

# Production build
npm run package

Debugging

For detailed debugging instructions, including how to launch the extension, check logs, and troubleshoot common issues, please refer to the Debugging Guide (Japanese).

Release Process

For detailed instructions on how to release new versions of the extension, including automated and manual publishing steps, please refer to the Release Process Guide (Japanese).

🧪 Testing Strategy

This extension uses comprehensive testing with modern tooling:

• Unit Tests: 47 test cases covering utilities and core functionality
• Integration Tests: VS Code extension testing with mocked APIs
• Code Coverage: nyc (Istanbul) with detailed reporting
• CI/CD Pipeline: Multi-platform testing on Windows, macOS, and Linux
• Modern Tools: Mocha, Chai, Sinon, JSDOM, and @testing-library

Test coverage includes:

• DOM manipulation utilities (22 tests)
• Notification system (8 tests)
• Alt+Click functionality (17 tests)
• VS Code API integration
• Cross-platform compatibility

🧪 Test-Driven Development (TDD)

This project follows t-wada's TDD methodology for sustainable, high-quality development:

TDD Infrastructure

• 📊 Metrics Collection: Real-time TDD compliance tracking
• 🔄 Automated Workflows: Red-Green-Refactor cycle automation
• 📈 Quality Gates: CI/CD integrated quality checks
• 🎯 Interactive Sessions: Guided TDD development experience

Available TDD Commands

# Interactive TDD workflow
npm run tdd:interactive

# Phase-specific commands
npm run tdd:red      # Verify failing tests
npm run tdd:green    # Verify passing tests
npm run tdd:refactor # Quality check after refactoring

# Quality assessment
npm run tdd:check-quality    # Comprehensive quality analysis
npm run tdd:quality-gate     # CI/CD quality gate check

TDD Metrics Dashboard

• TDD Compliance Rate: 80%+ target (Red-Green-Refactor adherence)
• Test Coverage: 90%+ target
• Code Quality Score: 8.0+/10.0 target
• ESLint Compliance: ✅ 100% (0 errors) - Production ready code quality
• TypeScript Safety: ✅ 100% - Strict mode compliance with proper type assertions
• Real-time tracking with historical trend analysis

Documentation

• 📖 TDD Operations Guide - Complete workflow and daily usage
• 🎯 TDD Best Practices - Proven patterns and techniques
• 🚀 CI/CD Integration - Quality gates and automation

VS Code Integration

Access TDD workflows directly through VS Code tasks:

• Ctrl+Shift+P → "Tasks: Run Task" → "TDD: Interactive Workflow"
• Integrated quality checks in build process
• Real-time TDD metrics in development

This TDD infrastructure ensures maintainable, testable code while preventing technical debt accumulation.

🏗️ Architecture

src/
├── constants/          # Application constants
├── providers/          # WebView providers
├── terminals/          # Terminal management
├── types/             # TypeScript type definitions
├── utils/             # Utility functions
├── webview/           # Frontend components
│   ├── components/    # UI components
│   ├── managers/      # UI managers
│   └── utils/         # WebView utilities
└── extension.ts       # Extension entry point

Key Components

• TerminalManager: Multi-terminal state management
• SecandarySidebar: VS Code WebView integration
• WebView (xterm.js): Terminal UI rendering
• PTY Process: System-level shell integration
• SplitManager: Terminal split functionality
• HeaderManager: UI header management

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork this repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Contribution Guidelines

• Maintain TypeScript type safety
• Follow ESLint and Prettier rules
• Add tests to cover new functionality
• Use Conventional Commits format
• Ensure CI tests pass on all platforms

🐛 Troubleshooting

Common Issues

Q: Terminal doesn't appear
A: Restart VS Code or disable/enable the extension.

Q: Commands don't execute
A: This is a PTY communication issue. Restart VS Code and re-enable the extension.

Q: Backspace key doesn't work
A: Special key handling has been fixed. Please use the latest version.

Q: Buttons (Clear/New/Split) don't work
A: Button functionality has been implemented. Check WebView communication.

Q: Shell doesn't start
A: Verify that the sidebarTerminal.shell setting has the correct shell path.

Q: Japanese/Unicode characters are garbled
A: Change terminal character encoding to UTF-8. IME support has been added.

Q: Performance is slow
A: Reduce the number of concurrent terminals using the maxTerminals setting.

Q: Alt+Click doesn't work
A: Ensure both terminal.integrated.altClickMovesCursor and editor.multiCursorModifier: "alt" are enabled in VS Code settings.

Debug Information

When reporting issues, please include:

• VS Code version
• Extension version
• OS and version
• Shell being used
• Error messages
• Steps to reproduce

📄 License

This project is licensed under the MIT License.

📝 Changelog

See CHANGELOG.md for detailed changes.

v0.1.50 (Latest)

• AI Agent Status Management: Fixed proper status transitions (connected → disconnected → none)
• Session Persistence: Complete terminal session restore functionality with scrollback history
• CLI Agent Integration: Enhanced file reference shortcuts for Claude Code (@filename) and GitHub Copilot (#file:filename)
• Cross-Platform Native Binaries: Platform-specific builds for optimal performance
• Status Lifecycle: Improved agent termination detection and UI synchronization
• Code Quality: Comprehensive lint fixes and enhanced stability

v0.1.25

• WebView Architecture Refactoring: Modular system with focused managers
• Active Terminal Visualization: Border indication for active terminal
• SVG Icon: Updated extension icon for better scaling

🙏 Acknowledgments

This project uses these excellent libraries:

• xterm.js - Terminal emulator
• node-pty - PTY process management
• VS Code Extension API - Extension framework

🔗 Related Links

• VS Code Extension API
• xterm.js Documentation
• node-pty Documentation

Developer: s-hiraoku
Repository: vscode-sidebar-terminal
License: MIT
Support: Issues

This README was last updated on 2025-07-30.