# VT Code Companion Extension Development Guide
This guide provides instructions for setting up, developing, and running the VT Code Companion VSCode extension.
## Prerequisites
Before you begin, ensure you have the following installed:
- [Node.js](https://nodejs.org/) (version 18 or higher)
- [Visual Studio Code](https://code.visualstudio.com/)
- [VSCode Extension Development tools](https://code.visualstudio.com/api/get-started/your-first-extension)
## Getting Started
### 1. Clone and Setup
```bash
# Navigate to your extension directory
cd /path/to/vtcode/extensions/vscode-extension
# Install dependencies
npm install
```
### 2. Build the Extension
To compile the TypeScript code and bundle the extension:
```bash
npm run bundle -- --production
```
This will:
- Compile TypeScript files to JavaScript
- Bundle the extension using esbuild
- Output the compiled code to the `dist` directory
## Running the Extension
### Method 1: Using VSCode Debugger (Recommended for Development)
1. Open this directory in VSCode:
```bash
code .
```
2. Press `F5` or go to the "Run and Debug" view (Ctrl+Shift+D or Cmd+Shift+D)
3. Select "Run Extension" from the launch configuration dropdown
4. Click the green "Run" button or press `F5` again
5. A new VSCode window titled "Extension Development Host" will open with your extension installed
### Method 2: Manual Build and Install
1. Build the extension:
```bash
npm run bundle -- --production
```
2. Package the extension:
```bash
npm run package
```
3. Install the packaged `.vsix` file in VSCode:
- Open VSCode
- Go to Extensions view (Ctrl+Shift+X or Cmd+Shift+X)
- Click the "..." menu button and select "Install from VSIX..."
- Select your packaged `.vsix` file
## Development Workflow
### Watching for Changes
To automatically rebuild when you make changes, use the watch command:
```bash
npm run watch
```
### Running Tests
`npm run typecheck` checks the shipped `src/extension.ts` import graph using
`tsconfig.extension.json`; `npm test` runs all isolated Node tests in `test/`.
The `compile` and `lint` scripts still print skip messages for the precompiled
distribution. The full `tsconfig.json` also includes legacy tests that mix Jest,
Vitest, and extension-host APIs, plus modules outside the shipped graph; that
broader check retains errors. Run the real source and focused module checks:
```bash
npm run typecheck
npm test
npm run typecheck:views
npm run test:views
npm run typecheck:services
npm run test:services
```
### Linting Code
To lint the extracted modules with the existing ESLint configuration:
```bash
ESLINT_USE_FLAT_CONFIG=false ./node_modules/.bin/eslint src/views/*.ts
ESLINT_USE_FLAT_CONFIG=false ./node_modules/.bin/eslint src/services/*.ts src/commands/configurationCommands.ts src/utils/vtcodeRunner.ts
```
## Extension Structure
```text
extensions/vscode-extension/
package.json # Extension manifest and configuration
src/
extension.ts # Activation, trust, commands, terminal/config coordination
views/
quickActions.ts # Quick-action descriptions and tree provider
workspaceInsights.ts # Workspace-status descriptions and tree provider
commands/configurationCommands.ts # HITL/MCP/policy command registration
services/processExecution.ts # Shared CLI process execution
services/interactiveTerminal.ts # Native CLI terminal lifecycle
services/workspaceTrust.ts # Stable manual trust flow and host-state checks
utils/vtcodeRunner.ts # Modular-command preflight and helpers
utils/manifestContributions.ts # Validated tool/participant manifest lookup
test/
views.test.cjs # View tests with an isolated VS Code fixture
services.test.cjs # Process/config tests with mocked spawning and config APIs
terminal.test.cjs # Terminal lifecycle tests with mocked VS Code API
trust.test.cjs # Proposed-API rejection, manual trust, and command admission
registry.test.cjs # Shared output channel and fresh command context
manifest.test.cjs # Literal contribution matching and malformed shapes
helpers/compileModules.cjs # Shared module compilation and fixture isolation
tsconfig.views.json # Focused view typecheck
tsconfig.services.json # Focused process/config/terminal/trust typecheck
tsconfig.extension.json # Shipped entrypoint and its imported modules
tsconfig.json # TypeScript configuration
.vscode/
launch.json # Debug launch configurations
syntaxes/ # Language syntax definitions
dist/ # Compiled output directory
```
The interactive terminal service flushes IDE context before creating a terminal
with the configured executable as `TerminalOptions.shellPath` and an argument
array as `shellArgs`. See the [VS Code terminal API](https://code.visualstudio.com/api/references/vscode-api#TerminalOptions).
It never sends a generated command string to a shell. Configuration and environment
callbacks are read after the flush. Concurrent requests share one pending launch;
shutdown or trust revocation prevents pending creation, and failures permit retry.
Terminal tests cover these states, literal metacharacters, and a real Node process
receiving the forwarded arguments. Full Extension Development Host and Windows
terminal process behavior remain unverified.
Workspace trust uses the stable information/warning dialogs and
`workbench.action.manageTrust`. The packaged extension does not enable the
`workspaceTrust` API proposal, so reading `workspace.requestWorkspaceTrust`
can throw before a request even starts. Keep that proposed API out of the flow.
Only `workspace.isTrusted` establishes approval after awaiting management;
opening the settings page, dismissing a prompt, or a command's return value does
not grant trust. The dedicated trust command remains available in restricted
workspaces, while ordinary execution commands retain their existing trust gate.
Activation still owns its one-time prompt key, and failures retain their original
error for the caller's command/activation handling. `npm run test:services`
includes the trust regressions; no Computer Use is required for these tests.
Activation supplies its output channel to `CommandRegistry`, so modular commands
and IDE-context warnings use the same channel. The registry never disposes a
supplied channel. No-argument callers receive one registry-owned fallback channel,
released on disposal; clearing command registrations leaves that channel alive.
Each invocation reads current editor, selection, terminal, and workspace state.
AI integration registration uses one manifest lookup that accepts only an array
of object entries and matches literal tool names or participant IDs. Malformed
manifest shapes do not enable an integration; the existing runtime API and
workspace-trust checks still determine availability and execution.
## Debugging the Extension
The Node view tests verify command gating, configuration branches, refreshes,
and item metadata. They do not exercise rendered views or terminal lifecycles.
Use an Extension Development Host to verify those interactions after extraction.
The service tests cover literal argument forwarding, stream callbacks, progress,
cancellation, command trust checks, configuration picker races, and error handling.
They mock configuration APIs and most child processes; one test launches Node to
verify literal arguments and an explicitly supplied environment. They do not verify
VT Code CLI execution, filesystem configuration writes, or full extension activation.
When using the "Run Extension" launch configuration:
1. Set breakpoints in your TypeScript files in the original VSCode window
2. Interact with the extension in the "Extension Development Host" window
3. Debug output will appear in the Debug Console of the original window
4. Extension logs can be viewed in the Output panel (select "VT Code" from the dropdown)
## Commands Available
The extension contributes the following commands:
- `vtcode.openQuickActions` - Open the quick actions panel
- `vtcode.askAgent` - Send a question to the VT Code agent
- `vtcode.askSelection` - Ask about the selected text
- `vtcode.openConfig` - Open the vtcode.toml configuration file
- `vtcode.launchAgentTerminal` - Launch an integrated VT Code terminal
- And more...
Access these commands via the Command Palette (Ctrl+Shift+P or Cmd+Shift+P).
## Terminal Environment
The agent terminal runs the VT Code executable directly with `chat` and the current
configuration arguments. Shell aliases, shell startup scripts, and Python virtual
environment activation commands are not evaluated before VT Code starts. The old
800 ms activation delay has been removed. The terminal inherits the VS Code window
environment and configured terminal environment settings, plus the extension's IDE
context environment values.
Set `vtcode.commandPath` to the installed executable name or path, rather than a
shell command containing flags or activation commands. If VT Code needs variables
from an activated environment, start VS Code from that environment or configure
`terminal.integrated.env.<platform>`. The process remains interactive in the
integrated terminal; exiting VT Code ends that process rather than returning to a
shell prompt.
## CLI Installation Requirements
The VT Code extension requires the VT Code CLI to be installed separately on your system. The extension cannot install
the CLI automatically for security and policy reasons.
The CLI can be installed via:
- Cargo: `cargo install vtcode` (if available)
- Homebrew: `brew install vtcode` (if available)
- Or by following the manual installation instructions
The extension checks for the CLI availability when activated and will show appropriate warnings if it's not found. Users
can update the `vtcode.commandPath` setting in VSCode to specify a custom path if the CLI is installed in a non-standard
location.
## Adding a Status Bar Icon
The extension already includes functionality to add a status bar icon that indicates VT Code status. In the
`extension.ts` file, you'll find:
1. A status bar item is created in the `activate` function
2. The status bar item has a tooltip and command associated with it
3. The `vtcode.launchAgentTerminal` command already exists to open the agent terminal
To customize the icon or add additional functionality to the status bar item:
1. Look for the status bar creation code in `extension.ts`
2. Modify the icon, text, or behavior as needed
3. The status bar already shows different states based on CLI availability
### Modifying Status Bar Click Behavior
By default, the status bar item opens the quick actions when clicked if the CLI is available. If you want to change this
behavior to launch the agent terminal instead:
1. In `extension.ts`, locate the `updateStatusBarItem` function
2. Find this line in the available (true) section:
```typescript
statusBarItem.command = "vtcode.openQuickActions";
```
3. Change it to:
```typescript
statusBarItem.command = "vtcode.launchAgentTerminal";
```
### Customizing Status Bar Icon
To show a dedicated VT Code icon in the status bar (similar to other extensions in VSCode):
1. The status bar item is created in the `activate` function in `extension.ts`:
```typescript
statusBarItem = vscode.window.createStatusBarItem(
vscode.StatusBarAlignment.Left,
100
);
```
2. The current implementation uses the "$(hubot)" icon in the text, which displays a robot icon:
```typescript
statusBarItem.text = `$(hubot) VT Code${suffix}`;
```
The `$(hubot)` part is a VSCode codicon that displays a robot icon, appropriate for an AI agent extension. You can
use other VSCode codicons like:
- `$(comment-discussion)` for a discussion/chat icon
- `$(terminal)` for a terminal icon (appropriate for VT Code chat)
- `$(rocket)` for a rocket icon
- `$(zap)` for a lightning bolt icon
- `$(tools)` for a tools icon
- And many others - you can browse all available codicons at
<https://microsoft.github.io/vscode-codicons/dist/codicon.html>
3. To change to a different icon, modify the text assignment in the `updateStatusBarItem` function:
```typescript
statusBarItem.text = `$(hubot) VT Code`; // Using a robot icon
```
4. For the VT Code chat functionality specifically, you might consider using the `$(terminal)` icon since it launches a
terminal with the VT Code chat interface.
5. VSCode status bar items do not directly support custom SVG/PNG images. They use built-in codicons. However, the
extension icon (shown in the Extensions view and marketplace) can be a custom SVG image stored in the media folder.
- VSCode status bar items don't directly support custom images via `iconPath`. Instead, they use built-in codicons.
- You can use any of the many available VSCode codicons in your status bar text:
- `$(hubot)` - Robot icon (used in the current implementation)
- `$(comment-discussion)` - Discussion/chat icon
- `$(terminal)` - Terminal icon
- `$(rocket)` - Rocket icon
- `$(zap)` - Lightning bolt icon
- And many others - you can browse all available codicons at
<https://microsoft.github.io/vscode-codicons/dist/codicon.html>
- To change the icon, modify the status bar text in the `updateStatusBarItem` function in `extension.ts`:
```typescript
statusBarItem.text = `$(hubot) VT Code${suffix}`; // Using a robot icon
```
- The media folder and custom icon files are still useful for other extension elements like the extension icon in the
VSCode marketplace:
```json
{
"icon": "media/vtcode-icon.svg",
"files": [
"dist/**/*",
"media/**/*",
"syntaxes/**/*",
"language-configuration.json"
]
}
```
6. For a cleaner look with just an icon (no text), you can set:
```typescript
statusBarItem.text = "$(hubot)"; // Just the icon
```
This will make the status bar icon launch the VT Code agent terminal when clicked instead of opening the quick actions
panel.
You can also customize the appearance of the status bar, including text and tooltip, in the same `updateStatusBarItem`
function.
The existing status bar item already has a command to open the agent terminal, and you can customize its appearance and
behavior by modifying the code in `extension.ts`.
## Common Issues
### Missing VT Code CLI
If you see messages about the VT Code CLI being missing:
1. Install the VT Code CLI according to the [official installation guide](https://github.com/vinhnx/vtcode#installation)
2. Or update the `vtcode.commandPath` setting in VSCode preferences
### Extension Not Loading
If the extension doesn't appear to be loading:
1. Check that you're running the "Run Extension" launch configuration
2. Verify the extension appears in the Extensions view in the "Extension Development Host" window
3. Check the Developer Tools console (Help > Toggle Developer Tools) for errors
### PreLaunchTask 'watch' Issue
If you see the message "Waiting for preLaunchTask 'watch'...", this means VSCode is trying to run the watch task but
it's not completing properly:
1. **Manual Solution**:
- Open a terminal in VSCode
- Run `npm run watch` manually in one terminal
- Then start debugging the extension in another terminal
2. **Alternative Launch**:
- Modify `.vscode/launch.json` to use the "compile" task instead of "watch"
- Or temporarily change the launch configuration to not use a preLaunchTask:
```json
{
"name": "Run Extension (without watch)",
"type": "extensionHost",
"request": "launch",
"args": ["--extensionDevelopmentPath=${workspaceFolder}"],
"outFiles": ["${workspaceFolder}/dist/**/*.js"]
}
```
3. **Task Configuration**:
- Ensure the watch task is properly defined in `.vscode/tasks.json`
- The watch task should run `npm run watch` which executes the esbuild watch command
## Building for Distribution
To package the extension for distribution:
```bash
npm run package
```
This will create a `.vsix` file that can be installed in VSCode.
## Releasing the Extension
The extension includes an automated release script that handles version bumping, building, packaging, and publishing to
both VSCode Marketplace and Open VSX Registry.
### Quick Release
To release a new version, use the `release.sh` script:
```bash
# Patch release (0.1.1 -> 0.1.2)
./release.sh patch
# Minor release (0.1.1 -> 0.2.0)
./release.sh minor
# Major release (0.1.1 -> 1.0.0)
./release.sh major
```
### What the Release Script Does
The automated release script performs the following steps:
1. **Checks dependencies** - Verifies that all required tools are installed (node, npm, git, jq, vsce, ovsx)
2. **Bumps version** - Updates the version in `package.json` according to semver
3. **Updates CHANGELOG** - Adds a new version entry with the current date
4. **Builds extension** - Compiles and bundles the TypeScript code
5. **Packages extension** - Creates a `.vsix` file
6. **Commits changes** - Commits the version bump to git
7. **Creates git tag** - Creates a tag with the format `vscode-v{version}` (e.g., `vscode-v0.1.2`)
8. **Pushes to GitHub** - Pushes commits and tags (with confirmation prompt)
9. **Publishes to VSCode Marketplace** - Publishes to the official marketplace (with confirmation prompt)
10. **Publishes to Open VSX** - Publishes to Open VSX Registry for VSCodium and alternatives (with confirmation prompt)
11. **Cleans up** - Removes old `.vsix` files
### Tag Naming Convention
The extension uses a **different naming convention** from the main VT Code binary to avoid version conflicts:
- **Main VT Code binary tags**: `v0.39.0`, `v0.39.1`, etc.
- **VSCode extension tags**: `vscode-v0.1.0`, `vscode-v0.1.1`, etc.
This ensures that extension releases don't conflict with the core VT Code CLI releases in the same repository.
### Manual Release Steps
If you prefer to release manually without the script:
1. **Bump the version**:
```bash
npm version patch ```
2. **Update CHANGELOG.md**:
```markdown
## [0.1.2] - 2025-11-03
### Added
- New feature description
### Fixed
- Bug fix description
```
3. **Build and package**:
```bash
npm run bundle
npm run package
```
4. **Commit and tag**:
```bash
git add package.json CHANGELOG.md
git commit -m "chore: release vscode extension v0.1.2"
git tag -a vscode-v0.1.2 -m "VSCode Extension Release v0.1.2"
git push origin main --tags
```
5. **Publish to VSCode Marketplace**:
```bash
vsce publish
```
6. **Publish to Open VSX Registry**:
```bash
ovsx publish vtcode-companion-0.1.2.vsix
```
7. **Create GitHub Release**:
- Go to <https://github.com/vinhnx/vtcode/releases/new>
- Select tag: `vscode-v0.1.2`
- Add release notes from CHANGELOG
- Attach the `.vsix` file
### Prerequisites for Publishing
Before you can publish extensions, you need:
1. **VSCode Marketplace**:
- A [Visual Studio Marketplace publisher account](https://marketplace.visualstudio.com/manage)
- A Personal Access Token (PAT) with Marketplace permissions
- Login with: `vsce login <publisher-name>`
2. **Open VSX Registry**:
- An [Open VSX account](https://open-vsx.org/)
- A Personal Access Token from your Open VSX account settings
- The token will be requested when you run `ovsx publish`
### Testing a Release
After publishing, test the extension:
```bash
# Install from marketplace
code --install-extension nguyenxuanvinh.vtcode-companion
# Or install from local .vsix file
code --install-extension vtcode-companion-0.1.2.vsix
```
## Useful Links
- [VSCode Extension API Documentation](https://code.visualstudio.com/api)
- [Extension Development Tutorial](https://code.visualstudio.com/api/get-started/your-first-extension)
- [VT Code Companion GitHub Repository](https://github.com/vinhnx/vtcode)
- [Publishing Extensions](https://code.visualstudio.com/api/working-with-extensions/publishing-extension)
- [Open VSX Registry](https://open-vsx.org/)