Secondary Terminal - VS Code Extension

The Essential Tool for the CLI Coding Agent Era - A production-ready terminal extension for developers who need more than VS Code's standard terminal. Manage up to 5 terminals in the sidebar with seamless AI agent integration for Claude Code, Codex CLI, Gemini CLI, and Copilot CLI.

Note: This extension is under active development. Please expect some bugs as we continuously improve the experience.

Quick Start

Installation

1. VS Code Marketplace: Search "Secondary Terminal" in Extensions
2. Open VSX (VS Codium, Gitpod, etc.): Search "Secondary Terminal" or visit Open VSX
3. Command Line: code --install-extension s-hiraoku.vscode-sidebar-terminal
4. Manual: Download VSIX from releases

First Use

1. Click the terminal icon (ST) in the activity bar
2. A terminal opens automatically with your default shell
3. Run your AI agent: claude, codex, gemini, or gh copilot
4. Look for "AI Agent Connected" status in the terminal header

Key Features

Terminal Management

AI Agent Integration

Automatic detection and status tracking for:

• Claude Code
• Codex CLI
• Gemini CLI
• GitHub Copilot CLI

Features:

• Real-time connection status indicators
• File reference sharing with Cmd+Alt+L (Mac) / Ctrl+Alt+L (Win/Linux)
• Session persistence across VS Code restarts
• Multi-agent workflows across terminals

Developer Experience

• Full Clipboard Support - Standard Ctrl/Cmd+C/V shortcuts
• IME Support - Japanese, Chinese, Korean input methods
• Link Handling - Click file paths to open in VS Code, URLs open in browser
• Alt+Click Positioning - VS Code-standard cursor placement
• Debug Panel - Real-time monitoring with Ctrl+Shift+D

Keyboard Shortcuts

Other UX features:

• Alt+Click moves the cursor (VS Code-style) when enabled.

Claude Code tips:

• Cmd+V on macOS pastes both text and images (screenshots) into Claude Code
• Use Shift+Enter or Option+Enter to insert newlines for multiline prompts

Command Palette

Access via Ctrl+Shift+P (Win/Linux) or Cmd+Shift+P (Mac):

Configuration

Basic Settings

{
  "secondaryTerminal.shell": "auto",
  "secondaryTerminal.maxTerminals": 5,
  "secondaryTerminal.fontSize": 14,
  "secondaryTerminal.fontFamily": "MesloLGS NF, Monaco, monospace",
  "secondaryTerminal.cursorBlink": true
}

AI Agent Settings

{
  "secondaryTerminal.enableCliAgentIntegration": true,
  "secondaryTerminal.enableGitHubCopilotIntegration": true,
  "secondaryTerminal.focusAfterAtMention": true
}

Architecture

Extension Host (Node.js)

• TerminalManager: PTY processes, lifecycle, AI detection
• Session Management: Persistent state across restarts

WebView (Browser)

• xterm.js: Terminal emulation
• Manager System: Input, UI, Performance, Splitting, Configuration

Performance

• Build Size: ~790 KiB extension + ~1.5 MiB webview
• Rendering: WebGL with auto DOM fallback
• Output Buffering: Adaptive 2-16ms intervals (up to 250fps for AI output)
• Memory: Efficient cleanup with LIFO disposal pattern
• Scrollback: <1s restore for 1,000 lines with ANSI color preservation

Troubleshooting

Terminal Not Starting

• Check secondaryTerminal.shell setting points to valid shell
• Verify shell is accessible from your PATH

AI Agent Not Detected

• Ensure secondaryTerminal.enableCliAgentIntegration is true
• Check debug panel (Ctrl+Shift+D) for detection logs
• Verify agent is properly installed

Performance Issues

• Reduce secondaryTerminal.maxTerminals if needed
• Check system resources via debug panel

Development

# Build
npm install
npm run compile

# Test
npm test              # Unit tests
npm run test:e2e      # E2E tests (Playwright)

# Development
npm run watch         # Watch mode
npm run lint          # ESLint check

Quality Standards:

• TypeScript strict mode
• 275+ unit tests
• E2E test coverage with Playwright

Known Limitations

• Running Processes: Long-running processes terminate on VS Code restart (scrollback preserved). Use tmux/screen for process persistence.
• Active Development: Some features may have rough edges

Privacy

This extension respects VS Code's telemetry settings. We collect only anonymous usage metrics (feature usage, error rates) - never terminal content, file paths, or personal data.

To disable: Set telemetry.telemetryLevel to "off" in VS Code settings.

See PRIVACY.md for details.

Contributing

1. Fork the repository
2. Create feature branch: git checkout -b feature/my-feature
3. Follow TDD practices
4. Run quality checks: npm run pre-release:check
5. Submit pull request

See GitHub Issues for open tasks.

Links

• VS Code Marketplace
• GitHub Repository
• Changelog
• Blog Article (Japanese)

License

MIT License - see LICENSE file.

Built with ❤️ for VS Code developers working with AI agents