
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
- Open VS Code
- Open Extensions panel (
Ctrl+Shift+X
or Cmd+Shift+X
)
- Search for "Sidebar Terminal"
- Click Install
Manual Installation
- Download the latest
.vsix
file from Releases
- Open VS Code and press
Ctrl+Shift+P
(Cmd+Shift+P
on Mac)
- Select "Extensions: Install from VSIX..."
- Choose the downloaded
.vsix
file
🎯 Usage
Basic Operations
- Open Terminal: Click "Terminal" view in the Explorer panel
- Create New Terminal: Click the "New" button in the terminal header
- Split Terminal: Click the "Split" button to create a split view
- Clear Terminal: Click the "Clear" button to clear the active terminal
- Execute Commands: Type commands as you would in any terminal
- 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
):
Setting |
Type |
Default |
Description |
sidebarTerminal.shell |
string |
"" |
Path to shell executable. Leave empty to use system default. |
sidebarTerminal.shellArgs |
array |
[] |
Arguments to pass to the shell. |
sidebarTerminal.maxTerminals |
number |
5 |
Maximum number of terminals allowed. |
sidebarTerminal.cursorBlink |
boolean |
true |
Enable cursor blinking in terminal. |
sidebarTerminal.theme |
string |
auto |
Terminal theme. Auto follows VS Code theme. |
sidebarTerminal.defaultDirectory |
string |
"" |
Default directory for new terminals. Leave empty to use workspace root. |
sidebarTerminal.confirmBeforeKill |
boolean |
false |
Show confirmation dialog before closing terminals |
sidebarTerminal.protectLastTerminal |
boolean |
true |
Prevent closing the last terminal |
sidebarTerminal.minTerminalCount |
number |
1 |
Minimum number of terminals to keep open |
sidebarTerminal.maxSplitTerminals |
number |
5 |
Maximum number of terminals to display in split view |
sidebarTerminal.minTerminalHeight |
number |
100 |
Minimum height for each terminal in split view (pixels) |
sidebarTerminal.enableSplitResize |
boolean |
true |
Allow resizing split terminals by dragging splitters |
sidebarTerminal.statusDisplayDuration |
number |
3000 |
Duration to display status messages (milliseconds) |
sidebarTerminal.autoHideStatus |
boolean |
true |
Automatically hide status messages after specified duration |
sidebarTerminal.showStatusOnActivity |
boolean |
true |
Show last status message when user performs actions |
sidebarTerminal.showWebViewHeader |
boolean |
true |
Show title and command icons in the webview header |
sidebarTerminal.webViewTitle |
string |
Terminal |
Title to display in the webview header |
sidebarTerminal.showSampleIcons |
boolean |
true |
Show sample command icons in webview header (display only) |
sidebarTerminal.sampleIconOpacity |
number |
0.4 |
Opacity of sample icons (0.1 to 1.0) |
sidebarTerminal.headerFontSize |
number |
14 |
Font size for webview header title |
sidebarTerminal.headerIconSize |
number |
20 |
Size of terminal icon in webview header |
sidebarTerminal.sampleIconSize |
number |
16 |
Size of sample icons in webview header |
sidebarTerminal.altClickMovesCursor |
boolean |
true |
Controls whether Alt/Option + click will reposition the prompt cursor. |
sidebarTerminal.enableCliAgentIntegration |
boolean |
true |
Enable file reference shortcuts for CLI agents like Claude Code. |
sidebarTerminal.enableGitHubCopilotIntegration |
boolean |
true |
Enable GitHub Copilot Chat integration shortcuts. |
sidebarTerminal.enablePersistentSessions |
boolean |
true |
Enable terminal session persistence across VS Code restarts. |
sidebarTerminal.scrollbackLines |
number |
1000 |
Maximum number of lines to restore from terminal history. |
sidebarTerminal.scrollbackCompression |
boolean |
true |
Compress scrollback data to reduce storage size. |
🛠️ 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
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:
- Fork this repository
- Create a feature branch (
git checkout -b feature/amazing-feature
)
- Commit your changes (
git commit -m 'Add some amazing feature'
)
- Push to the branch (
git push origin feature/amazing-feature
)
- 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.
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:
Developer: s-hiraoku
Repository: vscode-sidebar-terminal
License: MIT
Support: Issues
This README was last updated on 2025-07-30.