Secondary Terminal - VS Code Extension

English | 日本語 | 中文 | 한국어 | Español | Français | Deutsch

Your sidebar, your terminal, your AI agents -- all in one place. A full-featured terminal that lives in the VS Code sidebar, with built-in AI agent detection for Claude Code, Codex CLI, Gemini CLI, GitHub Copilot CLI.

Why Secondary Terminal?

• Sidebar-native terminal -- Keep your terminal visible while editing. No more toggling the bottom panel.
• AI agent aware -- Auto-detects Claude Code, Copilot, Gemini (v0.28.2+), Codex. Shows real-time connection status and optimizes rendering for AI streaming output (up to 250fps).
• Full-featured -- Split views, session persistence, shell integration, find-in-terminal, command decorations, 90 configurable settings. Not a toy -- a production terminal.

Quick Start

1. Install: Search "Secondary Terminal" in the VS Code Extensions view
   • Also available on Open VSX (VSCodium, Gitpod) and via CLI: code --install-extension s-hiraoku.vscode-sidebar-terminal
2. Open: Click the terminal icon (ST) in the activity bar
3. Use: A terminal opens with your default shell. Run claude, codex, gemini, or gh copilot and watch the AI agent status appear in the header.

Feature Highlights

For AI Agent Workflows

Terminal Power Features

Developer Experience

Keyboard Shortcuts

Panel Navigation Mode (Zellij-style)

Note: Panel navigation is disabled by default to avoid conflicts with terminal multiplexers (zellij, tmux, screen). Enable it in settings: "secondaryTerminal.panelNavigation.enabled": true

Use Ctrl+P to enter a dedicated navigation mode (Cmd+P on macOS is reserved for VS Code Quick Open). While active:

• Use h, j, k, l or Arrow keys to switch between split terminals.
• Press r or d to create a new terminal.
• Press x to close the current terminal.
• Press Ctrl+P again or Escape to exit.
• A visual indicator appears in the top-right corner while in navigation mode.

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

Configuration

The extension has 90 settings. Here are the most impactful ones to customize:

{
  // Appearance
  "secondaryTerminal.fontSize": 12,
  "secondaryTerminal.fontFamily": "monospace",
  "secondaryTerminal.cursorStyle": "block",
  "secondaryTerminal.scrollback": 2000,

  // AI agent integration
  "secondaryTerminal.enableCliAgentIntegration": true,

  // Session persistence
  "secondaryTerminal.enablePersistentSessions": true,
  "secondaryTerminal.persistentSessionScrollback": 1000,

  // Split view
  "secondaryTerminal.maxSplitTerminals": 5,
  "secondaryTerminal.dynamicSplitDirection": true,

  // Panel navigation (Zellij-style Ctrl+P)
  "secondaryTerminal.panelNavigation.enabled": false,

  // Shell integration
  "secondaryTerminal.shellIntegration.enabled": true,
  "secondaryTerminal.shellIntegration.showCommandStatus": true
}

Search secondaryTerminal in VS Code Settings for the full list, or see package.json for all defaults.

Performance

Troubleshooting

Terminal not starting

• Check secondaryTerminal.shell points to a valid shell in your PATH
• Try setting an explicit shell path

AI agent not detected

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

Performance issues

• Reduce secondaryTerminal.scrollback value
• Check system resources via the debug panel

Session not restoring

• Verify secondaryTerminal.enablePersistentSessions is true
• Use "Clear Corrupted Terminal History" command if data is corrupted

TUI display issues

• Mouse tracking is automatically enabled for apps like zellij
• If display issues occur in split mode, try switching to fullscreen mode

Known Limitations

• Running processes: Long-running processes terminate on VS Code restart (scrollback preserved). Use tmux/screen for process persistence.
• Platform support: Alpine Linux and Linux armhf are not supported due to node-pty prebuilt binary limitations.

Development

npm install && npm run compile    # Build
npm test                          # 4,000+ unit tests
npm run test:e2e                  # E2E tests (Playwright)
npm run watch                     # Watch mode

Quality: TypeScript strict mode, TDD workflow, 4,000+ unit tests, E2E coverage with Playwright, 9-platform CI/CD builds.

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
• Open VSX Registry
• GitHub Repository
• Changelog
• Blog Article (Japanese)

License

MIT License - see LICENSE file.

Built for VS Code developers working with AI agents