OpenCode Walkthrough

A Visual Studio Code extension that provides an interactive walkthrough and quick actions for OpenCode, an AI-assisted CLI for software engineering tasks.

Publisher: AlejandroAdorjan | License: SEE LICENSE IN LICENSE | Pricing: Free

Table of Contents

• Architecture
• Extension Entry Point
• Activation Events
• Contributions (package.json)
  • View Containers
  • Views
  • Commands
  • Views Welcome
  • Menus
  • Submenus
  • Walkthrough
  • Start Entries
• Project Structure
• Development
• Testing
• Publishing
• Release History

Architecture

The extension is a plain JavaScript VS Code extension (no transpiler) that follows the standard activate/deactivate lifecycle. It registers commands, status bar items, and contributes a walkthrough, views, and menus declaratively via package.json.

Core Flow

VS Code starts
  └─ Activation events trigger activate()
       ├─ Register 18 commands (all push to context.subscriptions)
       ├─ Create 2 status bar items (OpenCode + Agents)
       └─ All commands use sendToTerminal() except:
            ├─ showWalkthrough → opens the walkthrough page
            ├─ showActions    → opens a quick-pick menu
            └─ showCliHelp    → opens a CLI reference quick-pick

sendToTerminal()

The shared utility function routes command output to the VS Code integrated terminal:

function sendToTerminal(text) {
  const terminal = vscode.window.activeTerminal
    ?? vscode.window.createTerminal('OpenCode');
  terminal.show();
  terminal.sendText(text);
}

• Reuses the active terminal if one exists.
• Falls back to creating a new terminal named OpenCode.
• Focuses the terminal before sending text.

Extension Entry Point

File: extension.js

Module Exports

module.exports = { activate, deactivate };

Lifecycle

Commands Registered

Status Bar Items

Quick Pick Menus

showActions — 16 items:

$(book) Show Walkthrough
$(cloud-download) Install CLI
$(play) Run Inline Prompt
$(terminal) Start Interactive
$(robot) Create Agent
$(list-tree) List Agents
$(key) Auth Login
$(key) Auth List
$(plug) Add MCP Server
$(list-tree) List MCP Servers
$(symbol-parameter) List Models
$(list-tree) List Sessions
$(graph) Stats
$(server) Start Server
$(globe) Start Web
$(arrow-up) Upgrade CLI

showCliHelp — 14 CLI reference items with command descriptions:

Activation Events

The extension activates lazily on any of these triggers (package.json activationEvents):

Contributions (package.json)

View Containers

Two view containers are contributed:

Activity Bar — opencode-walkthrough

• ID: opencode-walkthrough
• Title: "OpenCode"
• Icon: media/opencode-icon.png

Panel — opencode-mcp

• ID: opencode-mcp
• Title: "MCP Servers"
• Icon: media/opencode-icon.png

Views

Commands

18 commands contributed with $(product-icon) references:

{
  "opencode-walkthrough.showWalkthrough": "$(book)",
  "opencode-walkthrough.install":          "$(cloud-download)",
  "opencode-walkthrough.runInline":        "$(play)",
  "opencode-walkthrough.runInteractive":   "$(terminal)",
  "opencode-walkthrough.createAgent":      "$(robot)",
  "opencode-walkthrough.listAgents":       "$(list-tree)",
  "opencode-walkthrough.authLogin":        "$(key)",
  "opencode-walkthrough.authList":         "$(key)",
  "opencode-walkthrough.addMcp":           "$(plug)",
  "opencode-walkthrough.listMcp":          "$(list-tree)",
  "opencode-walkthrough.listModels":       "$(symbol-parameter)",
  "opencode-walkthrough.sessionList":      "$(list-tree)",
  "opencode-walkthrough.stats":            "$(graph)",
  "opencode-walkthrough.serve":            "$(server)",
  "opencode-walkthrough.web":              "$(globe)",
  "opencode-walkthrough.upgrade":          "$(arrow-up)",
  "opencode-walkthrough.showActions":      "(no icon)",
  "opencode-walkthrough.showCliHelp":      "$(question)"
}

Views Welcome

Sidebar view (opencode-walkthrough.overview):

OpenCode is a CLI for AI-assisted software engineering tasks.

[Show Walkthrough](https://github.com/aadorian/opencodeCLI/blob/HEAD/command:opencode-walkthrough.showWalkthrough)
[Install CLI](https://github.com/aadorian/opencodeCLI/blob/HEAD/command:opencode-walkthrough.install)
[Run Inline Prompt](https://github.com/aadorian/opencodeCLI/blob/HEAD/command:opencode-walkthrough.runInline)
[Start Interactive Session](https://github.com/aadorian/opencodeCLI/blob/HEAD/command:opencode-walkthrough.runInteractive)
[Create Agent](https://github.com/aadorian/opencodeCLI/blob/HEAD/command:opencode-walkthrough.createAgent)

[Read Documentation](https://opencode.ai)

MCP Panel view (opencode-walkthrough.mcp):

Manage Model Context Protocol servers for OpenCode.

[Add MCP Server](https://github.com/aadorian/opencodeCLI/blob/HEAD/command:opencode-walkthrough.addMcp)
[List MCP Servers](https://github.com/aadorian/opencodeCLI/blob/HEAD/command:opencode-walkthrough.listMcp)

[Read MCP Docs](https://opencode.ai/docs/mcp-servers/)

Menus

menubar — Help menu bar integration:

view/title — Toolbar buttons shown in view headers:

explorer/context — Explorer right-click (only on folders):

• Shows submenu opencode-walkthrough.submenu

Submenus

ID: opencode-walkthrough.submenu — Label: "OpenCode"
ID: opencode-walkthrough.helpSubmenu — Label: "OpenCode CLI" (shown in Help menu)

Items when right-clicking a folder:

Walkthrough

ID: opencode.gettingStarted — Title: "Get Started with OpenCode"

5 sequential steps:

Each step has a markdown media file in walkthroughs/ (e.g. 01-install.md) and an SVG illustration in media/walkthrough/.

Start Entries

A "folder" category start entry is contributed:

• Title: "Get Started with OpenCode"
• Command: opencode-walkthrough.showWalkthrough

Project Structure

opencode-vscode-walkthrough/
├── .vscode/
│   └── launch.json              # Debug configs: Run Extension + Extension Tests
├── .vscode-test.mjs             # Test runner config (mocha TDD, user-data-dir)
├── .vscodeignore                # Files excluded from VSIX packaging
├── .env.example                 # Environment variables template
├── extension.js                 # Main extension entry point
├── package.json                 # Manifest with all contributions
├── media/
│   ├── opencode-icon.png        # PNG icon (128x128, for marketplace)
│   ├── opencode-icon.svg        # SVG source (codicon-style, not packaged)
│   └── walkthrough/
│       ├── agent.svg
│       ├── inline.svg
│       ├── install.svg
│       ├── interactive.svg
│       └── tips.svg
├── walkthroughs/
│   ├── 01-install.md
│   ├── 02-run-inline.md
│   ├── 03-run-interactive.md
│   ├── 04-create-agent.md
│   └── 05-tips.md
└── test/
    └── extension.test.js        # 7 integration tests

File Details

Development

Prerequisites

• VS Code 1.74+
• Node.js 18+
• OpenCode CLI (optional, for testing commands)

Configuration Settings

This extension contributes OpenCode CLI settings that can be configured in Settings → OpenCode. Each maps to a CLI environment variable (full list) and is automatically exported when running commands.

Settings are read when sending terminal commands and prepended as export statements.

Environment Variables

Copy .env.example to .env and configure your paths and tokens:

cp .env.example .env

Setup

npm install

Run Extension

Using the path from your .env:

source .env && code --extensionDevelopmentPath="$EXTENSION_PATH"

Or directly:

code --extensionDevelopmentPath="/absolute/path/to/opencode-vscode-walkthrough"

You can also press F5 in VS Code with the "Run Extension" launch config.

For more on sideloading extensions, see the VS Code extension marketplace docs.

Package

npx @vscode/vsce package

Outputs opencode-walkthrough-0.0.1.vsix.

Testing

Uses @vscode/test-cli with @vscode/test-electron.

Test Suite

7 tests in test/extension.test.js:

Run Tests

npm test

The config .vscode-test.mjs sets user-data-dir to a short /tmp path to avoid the macOS IPC socket 103-character limit.

Debug Tests

Use the "Extension Tests" launch config in .vscode/launch.json.

Publishing

VS Code Marketplace

Publish using the token from your .env or pass it directly:

source .env && npx @vscode/vsce publish -p "$VSCE_PAT"

See the VS Code extension marketplace docs for token setup.

Open VSX Registry

source .env && npx ovsx publish opencode-walkthrough-0.0.1.vsix -p "$OVSX_PAT"

Get a token at https://open-vsx.org/user-settings/tokens

Release History

Known Issues

None. Report at GitHub Issues.

Contributing

See CONTRIBUTING.md.

License

MIT