vogella Blog

Visual Studio Code GitHub Copilot vs. Eclipse Theia AI

2026-03-31T00:00:00+00:00

If you plan to build applications with AI support, especially for software development, you first need to decide which platform to use. You can build a plain web application from scratch and implement everything yourself, or build on top of an existing platform. In my previous blog posts, I explained how to customize the AI experience in Visual Studio Code and how to create a custom AI extension in Eclipse Theia. While writing those posts, I noticed many similarities, both from a user perspective and from an extension-development perspective. In this post, I compare both approaches to give you a clearer view of where they align and where they differ. If you have not read my previous blog posts and want more details, have a look at:

Note:
This blog post is based on Visual Studio Code 1.113.0 and Eclipse Theia 1.70.0. There may be differences if you read it when newer versions have been released.

Strategic Comparison

In the article Why Extending GitHub Copilot in VS Code May Not Be the Best Fit for Your AI-Native Development Tool, you can already find a comprehensive overview of the differences between GitHub Copilot in Visual Studio Code and Theia AI. The article is around half a year old and is therefore not fully up to date with the latest features. However, the strategic perspective is still well described and remains valid, so the article is still worth reading if you plan to adopt either technology.

The following table extracts and summarizes an initial comparison of key aspects from that article:

	VS Code GitHub Copilot	Eclipse Theia AI
Platform	Product you can extend	Platform you can own
License	Mixture of open source parts (MIT) and proprietary parts (Microsoft products)	Completely open source (EPL)
AI customization options	Chat only	any part of the application
Licensing	Copilot subscription required	-
LLM Support	Depends on Copilot subscription AI language models in VS Code	Depends on existing providers LLM Providers Overview

AI Extension Comparison

Visual Studio Code GitHub Copilot extensions and Eclipse Theia AI extensions target similar use cases: extending the AI capabilities of the IDE. There are differences in terminology, implementation, extension capabilities, and features. In previous blog posts, I explained how to contribute Tools, MCP Servers, and Chat Extensions. The concepts already differ in naming, as shown in the following table:

VS Code GitHub Copilot	Eclipse Theia AI
Language Model Tool	Tool Function
MCP	MCP
Chat Participant	Agent

The following sections will explain the differences in more detail.

Language Model Tool vs. Tool Function

Tools provide additional capabilities to perform specialized tasks when interacting with an LLM. In Visual Studio Code, they are called Language Model Tools; in Theia, they are called Tool Functions.

Visual Studio Code

To contribute a Language Model Tool via Copilot Extension, you follow the typical contribution pattern in Visual Studio Code Extensions:

Configure the contribution via contributes/languageModelTools section in the extensions package.json
Implement a new class that implements the vscode.LanguageModelTool interface
Register it in the extension via vscode.lm.registerTool()

Further details can be found in Extending Copilot in Visual Studio Code - Language Model Tool.

Eclipse Theia

To contribute a Tool Function via Theia Extension, you follow the typical contribution pattern in Theia:

Implement a new class that implements the ToolProvider interface from the @theia/ai-core package
Register it in a ContainerModule for injection via bindToolProvider() from @theia/ai-core/lib/common

Further details can be found in Getting Started with Theia AI - Tool Functions.

MCP Support

MCP Servers are typically configured by users via a configuration file. The usage comparison is described later in Configuring MCP Servers. MCP Servers can also be contributed and configured programmatically, for example when you contribute an extension that provides an advanced AI use case requiring dedicated tools via MCP.

Note:
MCP servers that are programmatically registered via a Visual Studio Code Copilot extension can also be installed in a Theia application if the @theia/plugin-ext extension is available.

Visual Studio Code

To contribute a MCP Server via Copilot Extension, you follow the typical contribution pattern in Visual Studio Code Extensions:

Configure the contribution via contributes/mcpServerDefinitionProviders section in the extensions package.json
Register a McpServerDefinitionProvider in the extension via vscode.lm.registerMcpServerDefinitionProvider()
Add MCP servers via McpServerDefinitionProvider#provideMcpServerDefinitions()
- A local MCP server can be configured by creating a vscode.McpStdioServerDefinition
- A remote MCP server can be configured by creating a vscode.McpHttpServerDefinition
Dynamic resolution (e.g. asking the user for an authorization token) can be added via McpServerDefinitionProvider#resolveMcpServerDefinition()

There are some limitations:

To ensure that the MCP servers are registered automatically on start, you need to configure the activationEvents accordingly, e.g. onStartupFinished
There is no API to programmatically start or stop an MCP Server in Visual Studio Code.
Programmatically registered MCP servers do not show up in the MCP Servers section of the Extensions view.
Programmatically registered MCP servers do not get roots set based on the current workspace directory.

Further details can be found in Extending Copilot in Visual Studio Code - Add MCP server programmatically via VS Code Extension.

Eclipse Theia

To contribute a MCP Server via Theia Extension, you follow the typical contribution pattern in Theia:

Implement a FrontendApplicationContribution
Get the MCPFrontendService injected
Add MCP servers via MCPFrontendService#addOrUpdateServer()
- A local MCP server can be configured by creating a LocalMCPServerDescription
- A remote MCP server can be configured by creating a RemoteMCPServerDescription
Dynamic resolution (e.g. asking the user for an authorization token) can be added directly to the MCPServerDescription via the MCPServerDescription#resolve() function
Register it in a ContainerModule via bind()

Compared to the limitations in Visual Studio Code, programmatically registered MCP servers in Theia

are automatically registered if the FrontendApplicationContribution is registered correctly in a ContainerModule
can be started and stopped programmatically via MCPFrontendService#startServer() and MCPFrontendService#stopServer()
do show up in the AI Configuration view
Since Theia 1.69.0, roots are supported. This support was added via PR. You can configure whether the workspace should be used as a Root via the preference ai-features.mcp.useWorkspaceAsRoot.

Further details can be found in Getting Started with Theia AI - Add MCP server programmatically via Theia Extension.

Chat Participant vs. Custom Agent

To extend the AI capabilities of an IDE or application with a specialized assistant that provides domain-specific expert knowledge, you can implement and contribute a Chat Participant in Visual Studio Code or a Custom Agent in Eclipse Theia. In both cases, the benefits of such a programmatically created AI assistant are:

you can manage the end-to-end prompt/response conversation
you have access to the respective API, which allows deep integration with the underlying platform
you can distribute and deploy it via extensions

Custom Agents defined via configuration files can only interact with the underlying platform if the required functionality is available as a Language Model Tool or Tool Function, or via MCP. They are also available only when the corresponding configuration files are present in the user’s workspace. Custom Agents from a user’s perspective are covered in a later section. In this section, I focus on the differences in programmatically created AI extensions.

Visual Studio Code

As the name implies, a Chat Participant contributed via a Visual Studio Code Copilot extension is intended for and limited to chat. There are no other use cases where a Chat Participant can be integrated, such as the terminal.

To contribute a Chat Participant via Copilot Extension, you follow the typical contribution pattern in Visual Studio Code Extensions:

Configure the contribution via contributes/chatParticipants section in the extensions package.json
Define a vscode.ChatRequestHandler which sends the chat request and handles the response
Create a vscode.ChatParticipant via vscode.chat.createChatParticipant() by using the id defined in the package.json and the defined vscode.ChatRequestHandler
Register the vscode.ChatParticipant in the extension by pushing it to the context.subscriptions

To use the Chat Participant, you need to invoke it with the @ syntax, e.g. @joker tell me a joke.

Further details can be found in Extending Copilot in Visual Studio Code - Chat Participant.

Eclipse Theia

Compared to Visual Studio Code, a Custom Agent in Theia is not limited to the chat. It can also be integrated into other parts of the IDE, such as the editor, the terminal, or a custom widget.

To contribute a Custom Agent via a Theia Extension, you follow the typical contribution pattern in Theia:

Implement an AbstractStreamParsingChatAgent and define the necessary attributes such as id, name, description, prompt(s), Tool Functions, and Agent-Specific Variables, if needed.
Register it in a ContainerModule via bind()

When implementing a Custom Agent, there are several advanced features that can improve the user experience, for example:

Prompt Variants
Agent-specific Variables
Agent-to-Agent Delegation
Custom Response Part Rendering

To use a Custom Agent in Theia, you need to invoke it with the @ syntax, e.g. @Joker a joke about scarecrow.

Further details can be found in Getting Started with Theia AI - Implement a Custom Agent.

AI Usage Comparison

The sections above covered differences in programmatic AI customization. In the following sections, I compare AI usage differences from a user’s point of view.

Using tools in prompts

How tools are used in prompts differs between Visual Studio Code and Theia. In general, there are three types of tools:

Built-in tools provided by the platform
MCP tools added via MCP servers
Extension tools provided programmatically (Language Model Tool vs. Tool Function)

Visual Studio Code

In Visual Studio Code, a Tool is used when processing a prompt if:

the tool is in the list of enabled tools and is selected automatically

the tool is used explicitly by mentioning it using a leading #

#jokeFileCreator create a file that contains a joke in the folder test

For tools provided via MCP, the tool is also selected by name. Assuming you added the fetch MCP server, you can use the provided tool via #fetch. Unfortunately, this is not unique because there is also a built-in fetch tool in Visual Studio Code.

By default, you will be prompted before a Language Model Tool is executed.

In the Allow dropdown, you can choose whether to allow execution once, for the current session, or generally in the current workspace. This setting is not directly accessible at the time of writing this blog post. To reset saved tool approvals, run the Chat: Reset Tool Confirmations command from the Command Palette (Ctrl+Shift+P).

In Visual Studio Code, it is also possible to configure URL approval, which becomes active when a tool attempts to access a URL.

Further details about using tools in chat in Visual Studio Code can be found in Use tools with agents.

Eclipse Theia

In Eclipse Theia, a Tool is used by mentioning it with a leading ~. There is no automatic tool resolution for prompts, so you always need to mention the tool explicitly.

@Universal create a file that contains a joke in the folder test. Use a file name that relates to the joke. ~jokeFileCreator

The name of an MCP server tool in Theia is derived from the server name and function name. It uses the following syntax:

~{mcp__}

For example, to use the fetch function of the fetch MCP server, you could write a prompt like this:

@Universal show me the allowed directories ~{mcp_fetch_fetch}

By default, the Tool Confirmation Mode is Always Allow. Users can change this setting.

Open the AI Configuration view via Menu -> View -> AI Configuration
Switch to the Tools tab
Alternatively, edit settings.json and configure ai-features.chat.toolConfirmation. For example, if you want to be prompted for approval for every tool call but allow jokeFileCreator to execute without confirmation:
```
"ai-features.chat.toolConfirmation": {
  "*": "confirm",
  "jokeFileCreator": "always_allow"
},
```

The URL approval feature is currently not supported in Eclipse Theia.

Further details about using tools in chat in Eclipse Theia can be found in Tool Functions, Using MCP Server Functions, and Tool Call Confirmation UI.

Configuring MCP Servers

As a user, you typically add MCP servers to your development environment via a configuration file. There are two basic types of MCP servers:

local MCP servers, which are software installed on your system
remote MCP servers, which are hosted elsewhere and provide functionality without needing local system access.

Visual Studio Code

In Visual Studio Code, you typically add MCP servers via an mcp.json file, either in the workspace .vscode folder or in the user profile to configure MCP servers for all workspaces. A mcp.json file has two main sections:

"servers": {} - Contains the list of MCP servers and their configurations
"inputs": [] - Optional placeholders for sensitive information like API keys

You can use predefined variables in the servers section and the variables defined in the inputs section.

{
  "servers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"]
    },
    "fetch": {
      "url": "https://remote.mcpservers.org/fetch/mcp",
      "type": "http"
    },
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "type": "sse",
      "headers": {
        "X-MCP-Toolsets": "gists",
        "Authorization": "Bearer ${env:GITHUB_TOKEN}"
      }
    }
  },
  "inputs": []
}

From the example above, you can see that you need to specify the type field to define whether it is a local or a remote MCP server.

You can manage the MCP server either via

MCP SERVERS - INSTALLED section in the Extensions view
Inline actions in the mcp.json editor (codelenses)
MCP: List Servers command from the Command Palette

After the first start of an MCP server, the server’s capabilities and tools are discovered and cached. The next time a tool is used in a prompt while the server is not running yet, Visual Studio Code can auto-start the server because of this cached information.

Using the chat.mcp.autostart setting, you can configure whether MCP servers should be restarted automatically when configuration changes are detected. This autostart setting is available only globally, not per server.

Further information can be found in Use MCP servers in VS Code.

Eclipse Theia

In Eclipse Theia, you typically add MCP servers via the general settings.json file. There is currently no support for an mcp.json file.

The settings.json file contains many settings that can be applied in Theia, not just MCP-related configuration. There is no support for predefined variables or inputs like the inputs section in mcp.json.

Comparing Visual Studio Code mcp.json and Eclipse Theia settings.json MCP server configuration, there are a few differences:

In Theia, you do not need to specify the type field.
For local servers, this is straightforward because only one type is available (stdio). For remote servers, Theia first tries to connect via sse, and if that fails, it falls back to http.
In Eclipse Theia, there is an autostart field that lets you configure whether an MCP server should start automatically. The default is true if it is not set.
For remote servers, the main URL is set as url in Visual Studio Code, while in Eclipse Theia the field is called serverUrl.
In Eclipse Theia, you can specify the authentication token via serverAuthToken, which defaults to an Authorization header with Bearer. You can change that via serverAuthTokenHeader.

{
  "ai-features.mcp.mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/home/node/examples"
      ],
      "autostart": false
    },
    "fetch": {
      "serverUrl": "https://remote.mcpservers.org/fetch/mcp",
      "autostart": false
    },
    "github": {
      "serverUrl": "https://api.githubcopilot.com/mcp/",
      "serverAuthToken": "",
      "headers": {
        "X-MCP-Toolsets": "gists"
      }
    }
  }
}

You can manage the MCP server either via

AI Configuration view: Menu -> View -> AI Configuration -> MCP Servers tab
Command palette: F1
- MCP: Start MCP Server -> filesystem
- MCP: Stop MCP Server -> filesystem

If an MCP server is not started, its capabilities and tools cannot be used. There is no auto-start based on cached information as in Visual Studio Code. However, you can configure auto-start behavior per server via the autostart field, which is enabled by default.

Further information can be found in MCP Integration.

Chat Variables

In Visual Studio Code and Eclipse Theia, it is possible, and usually recommended, to add specific context to your request. To do this explicitly, you can use the # syntax with some predefined options.

In Theia, it is also possible to implement and provide additional Context Variables as Global Variables or Agent-Specific Variables.

Further information for Visual Studio Code can be found in Add context to your prompts.

Further information for Eclipse Theia can be found in Context Variables.

Prompt Files vs Prompt Fragments

Visual Studio Code and Eclipse Theia both allow users to define reusable prompts for recurring development tasks. Although the feature is similar, there are differences.

Visual Studio Code

In Visual Studio Code, you can create and use Prompt Files to define reusable prompts for recurring development tasks.

Prompt Files are Markdown files with a .prompt.md file extension. They are located either in the .github/prompts folder in the workspace or in the prompts folder in the user profile (for example on Windows, C:\Users\\AppData\Roaming\Code\User\prompts).

In the optional YAML frontmatter header, the prompt behavior can be configured, for example:

agent header to define the agent that should be used for running the prompt
tools header to define the list of tools or tool sets that are available for the prompt

You can use variables in the prompt file using the syntax ${variableName}. The following variables can be used:

Workspace variables - ${workspaceFolder}, ${workspaceFolderBasename}
Selection variables - ${selection}, ${selectedText}
File context variables - ${file}, ${fileBasename}, ${fileDirname}, ${fileBasenameNoExtension}
Input variables - ${input:variableName}, ${input:variableName:placeholder}

Arguments passed in chat via key=value syntax (e.g. _target=robin) are available in the prompt via ${input:variableName} or ${input:variableName:placeholder}.

Tools configured as available in the prompt via the tools frontmatter header can be referenced in the prompt via #tool:.

To use a Prompt File in the Chat view, type / followed by the prompt name. For example, if you created a harley.prompt.md file, you could execute it via the slash command /harley.

Further information can be found in Extending Copilot in Visual Studio Code - Further Customization - Prompt Files.

Eclipse Theia

In Eclipse Theia, you can create and use Prompt Fragments to define reusable prompts for recurring development tasks.

Prompt Fragments are Markdown files with a .prompttemplate file extension. They are located either in the .prompts folder in the workspace or in user-wide local directories configured in the settings (AI Features -> Prompt Templates).

In the optional YAML frontmatter header, prompts can be configured as a Slash Command:

isCommand header needs to be set to true
commandName header specifies the name of the command
commandAgents header can be used to limit the visibility of the command to the specified agents.

You can use any available Context Variable in the prompt.

Command arguments passed via chat can be used in the prompt via Argument placeholders $ARGUMENTS or $1, $2, $3 for arguments by position.

The tools that should be used inside the prompt do not need to be preconfigured in the YAML frontmatter and can be referenced in the prompt via ~.

To use a Prompt Fragment in the Chat view, you can use the special variable #prompt:promptFragmentID, for example @Universal #prompt:harley joke about batgirl. When configured as a Slash Command, type / followed by the prompt name, for example @Universal /harley batgirl.

Further information can be found in Getting Started with Theia AI - Further Customization - Prompt Fragments and Getting Started with Theia AI - Further Customization - Slash Commands.

Custom Agents

Custom Agents are a mechanism that allows users to create specialized assistants for specific tasks in the chat. For example, users can create different personas tailored to development roles and tasks such as planning, research, or specialized workflows.

Custom Agents are similar to Visual Studio Code Chat Participants or programmatically contributed Custom Agents in Eclipse Theia. However, instead of contributing them programmatically, users define and configure them through dedicated agent files.

Visual Studio Code

In Visual Studio Code, Custom Agents are configured in custom agent files. Custom Agent Files are Markdown files with a .agent.md extension. They are located either in the .github/agents folder in the workspace or in the user profile folder (interestingly, also in the prompts folder). There is one dedicated .agent.md file for each Custom Agent.

Similar to Prompt Files, Custom Agents can be configured via an optional YAML frontmatter header. You can, for example:

select the model that should be used when running the agent prompt via the model header
select the tools or tool sets that can be used by the custom agent via the tools header
select the agents that are available as subagents in the custom agent via the agents header
configure handoffs for orchestrating multi-step workflows via the handoffs header

To use a Custom Agent, select it from the agents dropdown in chat and enter a prompt, for example joke about alfred.

Further information can be found in Extending Copilot in Visual Studio Code - Further Customization - Custom Agents.

While the usage of agents in Visual Studio Code and Eclipse Theia is quite similar, Visual Studio Code has some features that are currently not available in Eclipse Theia:

You can select an Agent type to control where and how an agent runs: local, background, cloud, or third-party.
There is a distinction between calling a Subagent, which spawns a child agent within a session to handle a subtask in its own isolated context window, and performing a Hand off, which transfers a session from one agent type to another while carrying over the conversation history.

Further information can be found in Using agents in Visual Studio Code.

Eclipse Theia

In Eclipse Theia, multiple Custom Agents are configured in a single custom agent configuration file. The Custom Agent File is a YAML file named customAgents.yml. It is located either in the .prompts folder in the workspace or in user-wide local directories configured in the settings (AI Features -> Prompt Templates).

Because there is only one file for multiple Custom Agents, there is no frontmatter configuration header. Instead, each Custom Agent configuration has its own attributes. In addition to the obvious fields such as id, name, description, and prompt, you need to specify the model via the defaultLLM field.

You can use any available Context Variable in the prompt.

The tools that should be used inside the prompt do not need to be preconfigured in any way. They can be referenced in the prompt via ~.

You can delegate to another agent by using the delegateToAgent Tool Function.

To use a Custom Agent, you need to use the @ syntax in the chat view, just like for any other agent in Theia, e.g. @Joker joke about alfred.

If you use a specific agent most of the time and do not want to type the @ syntax every time, you can configure a default agent via the preference ai-features.chat.defaultChatAgent, for example to use the Universal agent whenever no agent is explicitly mentioned in the chat:

"ai-features.chat.defaultChatAgent": "Universal"

Further information can be found in Getting Started with Theia AI - Further Customization - Custom Agents and Getting Started with Theia AI - Further Customization - Agent-to-Agent Delegation (function).

Agent orchestration

When talking about AI agents, we now often refer to Agentic AI workflows, where multiple agents collaborate to achieve complex goals. When creating Custom Agents, you need to consider collaboration options, especially if you design your agents for dedicated tasks rather than having one agent do everything. This is important because you should keep the context of your agent or prompt as small as possible while still providing enough information to achieve the desired results. Creating agents for dedicated tasks with a limited scope or context is similar to the encapsulation principle in object-oriented programming, and likewise, you need to consider processing or orchestration patterns.

Apart from a Single Agent that does all the work alone, you currently have two options:

Delegate Pattern
Create guided sequential workflows that transition between agents. The agents are called one after the other.
Coordinator and Worker Pattern
The main/coordinator agent receives the task, delegates subtasks to subagents, and combines the subagent results into the final result.

You can also combine these patterns to have multiple “main” agents that use worker agents for specific tasks. Each “main” agent can delegate to the next “main” agent once it is done, creating a sequential workflow of main tasks.

While the patterns are generally the same, technically there are differences between Visual Studio Code and Eclipse Theia.

Visual Studio Code

The Delegate Pattern is supported via Handoffs when creating Custom Agents in Visual Studio Code. A handoff is configured in the YAML frontmatter header. The user needs to actively proceed with the handoff by clicking a button in the chat UI. The token usage with a handoff is similar to having a single agent that processes all the tasks itself, as the whole context is passed from one agent to the next.

The Coordinator and Worker Pattern is supported through Subagents. To call a subagent, the built-in agent/runSubagent tool needs to be enabled for the coordinator agent. Using a subagent means spawning a child agent within a session to handle a subtask in its own isolated context window. This reduces the token usage, as subagents are not called with the whole context compared to a Handoff.

Each subagent call is sequential (the coordinator waits for that call to return), but the coordinator can spawn multiple subagent calls in parallel.

Further information can be found in AI Agent Orchestration - Visual Studio Code.

Eclipse Theia

Theia does not provide a feature like Handoffs in Visual Studio Code. Instead, Theia provides the built-in Tool Function delegateToAgent to support Agent-to-Agent Delegation, which is comparable to Subagents. Whether you implement the Delegate Pattern or the Coordinator and Worker Pattern depends on how you use the delegateToAgent tool in the prompt.

Using a subagent means spawning a child agent within a session to handle a subtask in its own isolated context window. Because Theia has no Handoff concept that forwards processing to another agent, but only the concept of subagents, you do not see the same token-usage difference there.

Each subagent call via delegateToAgent is sequential (the coordinator waits for that call to return), but the coordinator can spawn multiple subagent calls in parallel.

Further information can be found in AI Agent Orchestration - Eclipse Theia.

Context Monitoring / Token Usage

In Visual Studio Code, it is possible to monitor context window usage. This helps indicate how much context a conversation uses. Theia does not yet support such context-window monitoring, but this feature has been requested via Context window inspection / analysis command.

In Theia, token usage can be inspected via AI Configuration by switching to the Token Usage tab, at least for LLMs that provide usage metadata for a request. Token usage is accumulated within a session, so you do not get the information per request. Token usage is not persisted and is reset when restarting the application. Visual Studio Code does not support tracking token usage at that level.

Agent Skills

Agent Skills is a simple, open format for giving agents new capabilities and expertise. Basically, a skill is a folder containing a SKILL.md file that includes metadata in the form of a YAML frontmatter header and instructions that tell an agent how to perform a specific task. It can also contain subfolders with scripts, templates, and referenced materials. Because it is an open format, it is supported in various AI tools.

Agent Skills are a fairly new format, and both Visual Studio Code and Eclipse Theia support it, although in Eclipse Theia the feature is still in alpha. There are some differences in where skills are stored and how they are used, which I list in the following sections. If you are interested in examples, have a look at awesome-agent-skills.

Visual Studio Code

The location of the skills folder for a project in your repository is .github/skills/, .claude/skills/ or .agents/skills/.
The location for personal skills in the user home is ~/.copilot/skills/, ~/.claude/skills/ or ~/.agents/skills/.
You can configure additional locations for skills via the chat.agentSkillsLocations setting to share skills across projects or keep them in a central location.
You can use skills directly in the chat via a slash command. For example, if you created a skill with the name webapp-testing, you can use it directly in the chat via /webapp-testing for the login page.
Copilot discovers the skills to use automatically by matching the user prompt with the skill description. Only the body of a matching skill will be loaded into the context. Additional resources will only be added if they are referenced in the instructions.
You can create a new skill manually by creating the required folder and a SKILL.md file in that folder
You can create a new skill with the help of AI by using the /create-skill slash command in the chat
You can use the Chat Customizations dialog by clicking the gear icon in the upper-right corner of the Copilot chat window, select the Skills menu item on the left side and select an option to generate a skill via the dropdown on the upper right corner to guide you through the initial creation.

You can learn more about the use of Agent Skills in Visual Studio Code in Use Agent Skills in VS Code and Extending Copilot in Visual Studio Code - Further Customization - Agent Skills.

Eclipse Theia

Support for Agent Skills in Eclipse Theia is still in alpha and currently has known limitations. For example, in Theia 1.70.0, automatic skill discovery is not working reliably. Automatic execution and tool calls can also fail. These issues are likely to improve in upcoming releases.

The location of the skills folder for a project in your repository is .prompts/skills/.
The location for personal skills in the user home is ~/.theia/skills/.
You can configure additional locations for skills via the ai-features.skills.skillDirectories setting to share skills across projects or keep them in a central location.
You can use skills directly in the chat as a slash command. For example, if you created a skill with the name webapp-testing, you can use it directly in the chat via /webapp-testing for the login page.
You can enable agents to load skills on demand by using the `` variable in an agent’s prompt to list all available skills, and use the ~getSkillFileContent function to load a selected skill on demand.
You can create a new skill manually by creating the required folder and a SKILL.md file in that folder
You can create a new skill with the help of AI by using the built-in @CreateSkill agent in the chat
There is a Skills and Slash Commands View available via the AI Configuration via the Skills tab, which provides a convenient overview of the discovered skills and a button to directly open the corresponding SKILL.md file in an editor.

You can learn more about the use of Agent Skills in Eclipse Theia via Agent Skills (Alpha) and Getting Started with Theia AI - Further Customization - Agent Skills.

Conclusion

As you can see, the AI capabilities of Visual Studio Code GitHub Copilot and Eclipse Theia AI are very similar. Both ecosystems evolve quickly, and while writing this post, I had to update findings and screenshots several times to keep it current.

At a high level, both platforms support the same core building blocks: tools, MCP integration, custom agents, reusable prompts, and skills. The main differences are in product strategy and developer control:

Visual Studio Code with GitHub Copilot gives you a polished product with strong built-in workflows and broad adoption.
Eclipse Theia gives you an open platform you can own and shape deeply for your own product and domain.

From a practical perspective, your choice usually depends less on feature checklists and more on your goals:

Choose Visual Studio Code GitHub Copilot if you want fast adoption, familiar UX, and minimal platform-level ownership.
Choose Eclipse Theia if you need full control, deeper integration into your own application, and an open customization model.

It is also worth noting that AI customization now offers multiple overlapping mechanisms for similar outcomes. Deciding whether to use a Custom Agent, a Prompt File/Fragment, or an Agent Skill is not always straightforward and often depends on scope, reuse, and ownership.

If you want to dive deeper into that topic, there is a valuable discussion in the Theia repository: Agent vs PromptTemplate vs Skill. The response by Jonas Helming provides useful guidance on how these mechanisms differ and when each is a good fit.

In short: both platforms are strong, modern foundations for AI-assisted development. If you optimize for ready-to-use productivity, Visual Studio Code is a strong choice. If you optimize for extensibility and product ownership, Eclipse Theia is compelling.

AI Agent Orchestration

2026-03-20T00:00:00+00:00

When talking about AI agents, we now often refer to Agentic AI workflows, where multiple agents collaborate to achieve complex goals. When creating Custom Agents, you need to consider collaboration options, especially if you design your agents for dedicated tasks rather than having one agent do everything. This is important because you should keep the context of your agent or prompt as minimal as possible while still providing enough information to achieve the desired results. Creating agents for dedicated tasks with a limited scope/context is similar to the encapsulation principle in object-oriented programming, and similarly, you need to consider processing or orchestration patterns.

Apart from a Single Agent that does all the work alone, you currently have two options:

Delegate Pattern
Create guided sequential workflows that transition between agents. The agents are called one after the other.
Coordinator and Worker Pattern
The main/coordinator agent receives the task, delegates subtasks to subagents, and combines the subagent results into the final result.

I will explain these patterns and show the differences between Visual Studio Code and Eclipse Theia using the following example: get a list of links for a specific topic. To get those links, first check a GitHub user’s gists for a publication collection. Then inspect the list of publications for links contained in the posts.

Visual Studio Code

In the following sections, I describe how to create Custom Agents in Visual Studio Code and compare the different orchestration patterns.

GitHub MCP Server

As explained earlier, I want to set up an example process where the first step is to retrieve a list of publications from a GitHub Gist. For this, we need to configure the GitHub MCP Server with the gists toolset enabled.

Open the file .vscode/mcp.json (create one if you do not already have that file in your workspace)
- Add the following full configuration (or merge the github server entry into your existing servers object):
```
{
  "servers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "type": "sse",
      "headers": {
        "X-MCP-Toolsets": "gists"
      }
    }
  },
  "inputs": []
}
```
If you already have other servers configured in .vscode/mcp.json, keep them and only add the github entry under servers.

This adds the Remote GitHub MCP Server with the gists toolset and OAuth authentication.

Note:
If you want to use a Personal Access Token (PAT) for the authorization instead of OAuth, have a look at Extending Copilot in Visual Studio Code - Remote MCP Server with authorization.
In the editor, you will see actions provided as CodeLens that let you interact with the server. Click Start to start the GitHub MCP server.

The first time, you will be prompted via dialog to authenticate with GitHub. After clicking Allow, a website opens where you can log in to the account you want to connect the MCP server to.

After the authentication succeeds, the server starts and the capabilities and tools provided by the server are discovered.

Single Agent

We start by creating a single Custom Agent that performs all steps itself. This agent will then be split to explain the orchestration patterns.

Create a new Custom Agent that executes the previously described process to provide the user with a collection of links for a specific topic.
- In the Copilot chat window, click the gear icon in the upper right corner (Configure Chat…) and select
  Custom Agents -> Create new custom agent… -> .github/agents -> name: research
  
  This creates the file .github/agents/research.agent.md
Add the tools web/fetch and github/list_gists
Add a prompt that defines the steps to process

The following snippet shows how such an agent could look like

---
description: "This agent provides a collection of links for a specific topic."
tools: [web/fetch, github/list_gists]
---

You are an agent that helps the developer by extracting and providing links mentioned in blog posts.

To provide the necessary links execute the following steps:

1. Fetch the publications of Dirk Fauth in the gists of the user fipro78. Use #tool:github/list_gists to find the correct gist.
2. Use #tool:web/fetch to fetch the content of the gist with a max-length parameter of 15000.
3. Filter the fetched content for links about the requested information.
4. For every found blog post, use #tool:web/fetch to fetch the content of the given blog post with a max-length parameter of 15000.
5. Collect all links that are mentioned in the blog post and relevant for the topic.
6. Filter out duplicate links and links that are not relevant for the topic. Relevance can be determined by the presence of keywords related to the topic in the context of the link.
7. Provide a collection of the extracted filtered links ordered by the blog post they are mentioned in. Use the anchor text as the name of the link if available. If the anchor text is not available, use the URL as the name of the link. Order them alphabetically by the name of the link.

Hint:
The built-in web/fetch tool asks for approval to execute fetch and to access the URLs it wants to retrieve, ensuring no malicious content is fetched. If you use the custom agent prompts that I prepared, it will fetch my gist with my publications and blog posts published at https://vogella.com/blog/. If you trust these sources (at least I do :smile:), you can configure trust in settings.json by adding the following configuration to reduce the number of prompts during processing:

  "chat.tools.urls.autoApprove": {
    "https://vogella.com/blog/": true,
  },

Use the Custom Agent research by selecting it in the agents dropdown in the chat view, then enter a prompt, for example show links about visual studio code.
- When asked to allow fetching the gist and the content of the gist, select Allow and Review Once for the first request, and Allow Once afterwards.
  Further information can be found in the official documentation: Use tools with agents - URL approval

After the agent finishes its task, you can monitor the context window usage. The following screenshots show the context window usage when I ran the Custom Agent with Gemini 2.5 Pro and GPT-5.3-Codex. The values might be different when executing it again.

This is the context window usage with Gemini 2.5 Pro:

This is the context window usage with GPT-5.3-Codex:

Delegate Pattern

The Delegate Pattern is supported via Handoffs when creating Custom Agents in Visual Studio Code. For this scenario, we split the previous research agent into two Custom Agents, one per task:

One agent to get the information from a gist to find the blog posts
One agent to extract the links from the found blog posts
Create a new Custom Agent that extracts links from the text of a given blog post.
- In the Copilot chat window, click the gear icon in the upper right corner (Configure Chat…) and select
  Custom Agents -> Create new custom agent… -> .github/agents -> name: link_extractor
  
  This creates the file .github/agents/link_extractor.agent.md
Add the built-in web/fetch tool to fetch the content
Add a prompt that defines the steps to process

The following snippet shows how such an agent could look like

---
description: "This agent provides a list of links extracted from blog posts."
tools: [web/fetch]
---

You are an agent that helps the developer by extracting links mentioned in a blog post and providing them in a structured format.

To provide the necessary links execute the following steps:

1. Use #tool:web/fetch to fetch the content of the given blog post with a max-length parameter of 15000.
2. Collect all links that are mentioned in the blog post and relevant for the topic.
3. Filter out duplicate links and links that are not relevant for the topic. Relevance can be determined by the presence of keywords related to the topic in the context of the link.
4. Provide a collection of the extracted filtered links ordered by the blog post they are mentioned in. Use the anchor text as the name of the link if available. If the anchor text is not available, use the URL as the name of the link. Order them alphabetically by the name of the link.

Create a new Custom Agent that is able to retrieve information from a gist.
- In the Copilot chat window, click the gear icon in the upper right corner (Configure Chat…) and select
  Custom Agents -> Create new custom agent… -> .github/agents -> name: gists
  
  This creates the file .github/agents/gists.agent.md
Add the GitHub MCP tool github/list_gists to list the gists
Add the built-in web/fetch tool to fetch the content
Configure a handoff to delegate processing to the link_extractor agent

The following snippet shows how such an agent could look like

---
description: "This agent provides a list of links to blog posts from a GitHub Gist."
tools: [github/list_gists, web/fetch]
handoffs:
  - label: Extract Links from posts
    agent: link_extractor
    prompt: Extract links from the given list of blog posts
    send: true
---

You are an agent that helps the developer by providing links to blog posts.

To provide the necessary links execute the following steps:

1. Fetch the publications of Dirk Fauth in the gists of the user fipro78. Use #tool:github/list_gists to find the correct gist.
2. Use #tool:web/fetch to fetch the content of the gist with a max-length parameter of 15000.
3. Filter the fetched content for links about the requested information.
4. Provide a list of links to the relevant blog posts.

Use the Custom Agent gists by selecting it in the agents dropdown in the chat view, then enter a prompt, for example show links about visual studio code.
- When asked to allow fetching the gist and the content of the gist, select Allow and Review Once for the first request, and Allow Once afterwards.
  Further information can be found in the official documentation: Use tools with agents - URL approval
- After the gists agent finishes its task, the user must actively proceed with the handoff by clicking the Proceed button in the chat.
- You can see that the agent switches to the link_extractor agent in the chat

This is the context window usage with Gemini 2.5 Pro:

This is the context window usage with GPT-5.3-Codex:

You can see that the context window looks quite similar to executing the process with a single agent. The reason is that we stay in the same conversation, so the relevant context is largely the same. This means the context contains information from the first agent that is also available to the second agent. The Delegate Pattern therefore helps create a better structure for a multi-agent system and reusable agents for various scenarios via “encapsulation”, but it has little to no effect on token usage compared to the single-agent solution.

Coordinator and Worker Pattern

In Visual Studio Code, you implement the Coordinator and Worker Pattern by using Subagents. Using a subagent means spawning a child agent within a session to handle a subtask in its own isolated context window. From a pattern perspective, this means there is a main coordinator agent that manages the overall task and delegates subtasks to specialized subagents. To call a subagent, the built-in agent/runSubagent tool needs to be enabled for the coordinator agent. Each subagent call is sequential (the coordinator waits for that call to return), but the coordinator can spawn multiple subagent calls in parallel.

In this section, the previously created agents are converted into coordinator and worker agents.

Open the file .github/agents/gists.agent.md
Remove the handoffs header
Ensure that the agent returns something at the end

The following snippet shows how such an agent could look like

---
description: "This agent provides a list of links to blog posts from a GitHub Gist."
tools: [github/list_gists, web/fetch]
---

You are an agent that helps the developer by providing links to blog posts.

To provide the necessary links execute the following steps:

1. Fetch the publications of Dirk Fauth in the gists of the user fipro78. Use #tool:github/list_gists to find the correct gist.
2. Use #tool:web/fetch to fetch the content of the gist with a max-length parameter of 15000.
3. Filter the fetched content for links about the requested information.
4. Provide a list of links to the relevant blog posts.

Open the file .github/agents/research.agent.md
Add the built-in agent tool to call subagents and remove the other tools
Configure the agents gists and link_extractor as agents that can be used as subagents

The following snippet shows how such an agent could look like

---
description: "This agent provides a collection of links for a specific topic."
tools: [agent]
agents: ["gists", "link_extractor"]
---

You are an agent that helps the developer by providing links to blog posts about a specific topic.
To provide the necessary links use subagents to execute the following steps:

1. Use the gists subagent to fetch a collection of blog posts about the specific topic.
2. For each of the found blog posts use the link_extractor subagent to fetch the content of the blog post and extract all links that are mentioned in the blog post.
3. Provide a collection of the extracted links ordered by the blog post they are mentioned in. Use the anchor text as the name of the link if available. If the anchor text is not available, use the URL as the name of the link. Order them alphabetically by the name of the link.

The link_extractor agent can stay as it is, since it does not specify a handoff and already returns the result in its prompt.
Use the Custom Agent research by selecting it in the agents dropdown in the chat view, then enter a prompt, for example show links about visual studio code.

When watching the execution, you should notice that:

The research agent stays active as the coordinator agent
While the subagents are called, the coordinator waits until they are done
The link_extractor agent is called multiple times, once per found blog post. These multiple agent calls are executed in parallel, while the coordinator agent waits until all spawned child agents are finished.

This is the context window usage with Gemini 2.5 Pro:

This is the context window usage with GPT-5.3-Codex:

You can see that the context window is smaller compared to the other patterns, which can be explained by the fact that each subagent is executed in its own isolated context window.

Eclipse Theia

If you are new to Eclipse Theia and want to try out the examples in the following sections, you have three options:

Try Theia IDE online
Get Theia IDE for desktop
Build your own Theia application
Have a look at Getting Started with Eclipse Theia and Getting Started with Theia AI if you are interested in that topic.

For the following sections, I assume that you have a Theia application with AI support. To enable AI features inside a Theia application, such as Theia IDE, you need access to an LLM and must configure it accordingly. I will give an example using the Google Gemini free tier. This only works if you have a Google account. If you want to use another LLM, have a look at the LLM Providers Overview to see which LLMs are currently supported by Theia. If you have a subscription for an LLM that is not listed here, check whether it is compatible with the OpenAI API and try to configure it as an OpenAI Compatible Model.

If you have a Google account, you can try out the Google AI Studio
- Create a new project via Google AI Studio - Projects
  - Click on Create a new project
  - Provide a name like theia-evaluation
  - Click on Create project
- Create a new API key via Google AI Studio - API Keys
  - Click on Create API Key
  - Give the key a name like theia
  - Select the previously created theia-evaluation project
  - Click on Create key
Switch to the Theia application (e.g. the Theia IDE)
- Open the settings page by pressing CTRL + ,
  - Select the AI Features
  - Check Enable AI
  - Configure the LLM you want to use
    - Google
      - Api Key: Copy and paste your Google AI API key (see above)
        For this tutorial we simply configure the API key via preferences as it is easier than setting up the environment. In a productive environment you should use the environment variable GOOGLE_API_KEY to set the key securely.
      - Models: Ensure to have models in the list that are currently available according to Gemini Models
  - Configure the Model Aliases
    - Open the AI Configuration via Menu -> View -> AI Configuration
    - Switch to the Model Aliases tab
    - For every model alias, select the model that you configured, e.g. google/gemini-3.1-flash-lite-preview

Since version 1.68.0 Theia also supports a GitHub Copilot language model integration. To try it out, you need to authenticate with GitHub

Click on Sign in to GitHub Copilot in the footer of the Theia application
This will open the following window
Copy the key
Click on Open GitHub
Follow the instructions on the GitHub website to grant the device permission
After the device activation is successful, switch back to the Theia browser window and click on I have authorized to finish the authentication process in Theia
After successful authentication, you can select a Copilot model as Model Alias, e.g. copilot/gpt-4o

Note:
At the time of writing this article, the only Copilot models that are working in Theia are gpt-4o and gpt-4o-mini. Using other models results in the following issue: AI Chat with GitHub Copilot fails with: 400 The requested model is not supported.

MCP Server Configuration

To set up the example process like in Visual Studio Code to retrieve a list of publications from a GitHub Gist and then fetch the data for further processing, we need to configure the necessary MCP server. This is again the GitHub MCP Server with the gists toolset enabled, and the fetch MCP Server as Theia does not provide a built-in fetch tool.

Open the AI Configuration via Menu -> View -> AI Configuration
- Switch to the MCP Servers tab
- Add the Fetch MCP Server as a remote MCP Server
  - Click on Add MCP Server
  - Set the following values in the dialog
    - Server Name: fetch
    - Server Type: Remote (URL)
    - Server URL: https://remote.mcpservers.org/fetch/mcp
    - Keep the Autostart flag checked
  - Click Add Server
- Add the Remote GitHub MCP Server with the gists toolset
  - Click on Add MCP Server
  - Set the following values in the dialog
    - Server Name: github
    - Server Type: Remote (URL)
    - Server URL: https://api.githubcopilot.com/mcp/x/gists
    - Auth Token: Your Personal Access Token (PAT) with repo scope. See Creating a personal access token (classic) if you do not already have a PAT.
    - Keep the Autostart flag checked
  - Click Add Server

Instead of configuring everything via user interface, you can also directly paste one of the following configurations directly in the settings JSON

Switch to the JSON view of the settings by clicking the curly braces on the upper right corner of the editor (Open Settings (JSON))
Alternatively use the Command Palette (F1) and search for Preferences: Open Settings (JSON)

Copy the following snippet and paste it in the editor

{
  "window.titleBarStyle": "custom",
  "ai-features.AiEnable.enableAI": true,
  "ai-features.google.apiKey": "",
  "ai-features.google.models": [
    "gemini-3.1-flash-lite-preview",
    "gemini-3-flash-preview",
    "gemini-2.5-flash",
    "gemini-2.5-flash-lite",
    "gemini-2.5-pro"
  ],
  "ai-features.languageModelAliases": {
    "default/code": {
      "selectedModel": "google/gemini-3.1-flash-lite-preview"
    },
    "default/universal": {
      "selectedModel": "google/gemini-3.1-flash-lite-preview"
    },
    "default/code-completion": {
      "selectedModel": "google/gemini-3.1-flash-lite-preview"
    },
    "default/summarize": {
      "selectedModel": "google/gemini-3.1-flash-lite-preview"
    }
  },
  "ai-features.chat.defaultChatAgent": "Universal",
  "ai-features.mcp.mcpServers": {
    "fetch": {
      "serverUrl": "https://remote.mcpservers.org/fetch/mcp",
      "autostart": true
    },
    "github": {
      "serverUrl": "https://api.githubcopilot.com/mcp/x/gists",
      "autostart": true,
      "serverAuthToken": ""
    }
  }
}

Replace with your Google AI Studio AI key and with your PAT.

After performing the above steps, you should see the two MCP servers in the overview and they should directly be Connected as the servers are configured to autostart.

Single Agent

We again first create a single Custom Agent that performs all steps itself. This agent will then be split to explain the orchestration patterns.

Create a new Custom Agent that executes the previously described process to provide the user with a collection of links for a specific topic.

Open the AI Configuration via Menu -> View -> AI Configuration
Switch to the Agents tab
Click on Add Custom Agent
Select the .prompts folder of the current workspace
Verify that a .prompts folder is generated in your workspace that contains a customAgents.yml file
Define a custom agent with the name Research by defining the following information
- id: A unique identifier for the agent.
- name: The display name of the agent.
- description: A brief explanation of what the agent does.
- prompt: The default prompt that the agent will use for processing requests.
- defaultLLM: The language model used by default.
- showInChat: Whether the agent should be shown in the chat UI. This one is optional and defaults to true.
Replace the content of the customAgents.yml with the following snippet

- id: Research
  name: Research
  description: This agent provides a collection of links for a specific topic.
  prompt: >-
    You are an agent that helps the developer by extracting and providing links mentioned in blog posts.

    To provide the necessary links execute the following steps:

    1. Fetch the publications of Dirk Fauth in the gists of the user fipro78. Use ~{mcp_github_list_gists} to find the correct gist.
    2. Use ~{mcp_fetch_fetch} to fetch the content of the gist with a max-length parameter of 15000.
    3. Filter the fetched content for links about the requested information.
    4. For every found blog post, use ~{mcp_fetch_fetch} to fetch the content of the given blog post with a max-length parameter of 15000.
    5. Collect all links that are mentioned in the blog post and relevant for the topic.
    6. Filter out duplicate links and links that are not relevant for the topic. Relevance can be determined by the presence of keywords related to the topic in the context of the link.
    7. Provide a collection of the extracted filtered links ordered by the blog post they are mentioned in. Use the anchor text as the name of the link if available. If the anchor text is not available, use the URL as the name of the link. Order them alphabetically by the name of the link.

  defaultLLM: default/universal
  showInChat: true

Compared to a custom agent in Visual Studio Code, we do not need to configure which tools we want to use in the prompt. They can simply be referenced in the prompt via ~.

Use the Custom Agent Research by selecting it in the chat prompt via @ syntax and add the prompt to execute, for example @Research show links about theia.

Theia does not yet support context window monitoring like Visual Studio Code, so we cannot inspect detailed context usage. This feature has been requested via Context window inspection / analysis command. For several LLMs, token usage can still be inspected via AI Configuration by switching to the Token Usage tab. I tested the example using GPT-5.3-Codex hosted on Azure, GPT-4o via Copilot, and Gemini 3.1 Flash Lite Preview via Google AI Studio in the Free Tier.

Note:
The token counts reported for Gemini models are incorrect in Theia 1.69.0. I created the ticket Token usage shows incorrect values for Gemini models and submitted a pull request that fixes this issue. The screenshot above shows token usage with the fix applied for a fair comparison.

Token usage is not persisted and is reset when restarting the application. To get a better comparison, I restart after each example.

Delegate Pattern

Theia does not provide a feature like the Handoffs in Visual Studio Code. Instead Theia provides the built-in Tool Function delegateToAgent to support Agent-to-Agent Delegation. To show this scenario, we split the previous Research agent into two Custom Agents, one per task:

One agent to get the information from a gist to find the blog posts
One agent to extract the links from the found blog posts

In Eclipse Theia, multiple Custom Agents are configured in a single custom agent configuration file. We therefore add the new agents to the previously created customAgents.yml.

Open the .prompts/customAgents.yml file

Add a new Link_Extractor agent

Use the MCP Tool mcp_fetch_fetch to fetch the content of the blog posts
Add a prompt that defines the steps to process
The following snippet shows how such an agent could look like

- id: Link_Extractor
  name: Link_Extractor
  description: This agent provides a list of links extracted from blog posts.
  prompt: >-
    You are an agent that helps the developer by extracting links mentioned in blog posts and providing them in a structured format.

    To provide the necessary links execute the following steps:

    1. Iterate over the list of provided blog posts
    2. For every blog post use ~{mcp_fetch_fetch} to fetch the content of the blog post with a max-length parameter of 15000.
    3. Collect all links that are mentioned in the blog post and relevant for the topic.
    4. Filter out duplicate links and links that are not relevant for the topic. Relevance can be determined by the presence of keywords related to the topic in the context of the link.
    5. Provide a collection of the extracted filtered links ordered by the blog post they are mentioned in. Use the anchor text as the name of the link if available. If the anchor text is not available, use the URL as the name of the link. Order them alphabetically by the name of the link.

  defaultLLM: default/universal
  showInChat: true

Add a new Gists agent

Use the MCP Tool mcp_github_list_gists to list the gists
Use the MCP Tool mcp_fetch_fetch to fetch the content
Use the Theia built-in Tool Function delegateToAgent to delegate processing to the Link_Extractor agent
The following snippet shows how such an agent could look like

- id: Gists
  name: Gists
  description: This agent provides a list of links to blog posts from a GitHub Gist.
  prompt: >-
    You are an agent that helps the developer by providing links to blog posts.

    To provide the necessary links execute the following steps:

    1. Fetch the publications of Dirk Fauth in the gists of the user fipro78. Use ~{mcp_github_list_gists} to find the correct gist.
    2. Use ~{mcp_fetch_fetch} to fetch the content of the gist with a max-length parameter of 15000.
    3. Filter the fetched content for links about the requested information.
    4. Provide a list of links to the relevant blog posts.
    5. Pass the provided list of links to the Link_Extractor agent via ~{delegateToAgent} to extract links from the given list of blog posts

  defaultLLM: default/universal
  showInChat: true

Use the Custom Agent Gists by selecting it in the chat prompt via @ syntax and add the prompt to execute, for example @Gists show links about theia.

You can see in the chat response that the Gists agent stays the active agent, and Link_Extractor is called as part of it. So it is not actually a Handoff like in Visual Studio Code, where the active agent really switches.

Interestingly, token usage for the Delegate Pattern in Theia is slightly higher compared to the single-agent solution. It is also interesting that the Delegate Pattern is not exactly the same as in Visual Studio Code via Handoffs. It seems that Agent-to-Agent Delegation is similar to Subagents in Visual Studio Code, at least based on the chat output.

At the time of writing this blog post, Theia does not support an automatic Handoff similar to Visual Studio Code. But you can try to simulate this manually.

Update the Gists agent

Remove the last step that passes the processing to the Link_Extractor agent
The following snippet shows how such an agent could look like

- id: Gists
  name: Gists
  description: This agent provides a list of links to blog posts from a GitHub Gist.
  prompt: >-
    You are an agent that helps the developer by providing links to blog posts.

    To provide the necessary links execute the following steps:

    1. Fetch the publications of Dirk Fauth in the gists of the user fipro78. Use ~{mcp_github_list_gists} to find the correct gist.
    2. Use ~{mcp_fetch_fetch} to fetch the content of the gist with a max-length parameter of 15000.
    3. Filter the fetched content for links about the requested information.
    4. Provide a list of links to the relevant blog posts.

  defaultLLM: default/universal
  showInChat: true

Use the Custom Agent Gists by selecting it in the chat prompt via @ syntax and add the prompt to execute, for example @Gists show links about theia.
Once the Gists agent is done, use the Link_Extractor agent by selecting it in the chat prompt via @ syntax and add the prompt to execute, for example @Link_Extractor fetch the previously found blog posts and extract further links.

As a result of manually changing the active agent, Link_Extractor is now the active agent.

The token usage increased as the whole conversation is passed to the next agent as context, and the token usage is accumulated over the whole session. Therefore the Input Tokens and the Output Tokens are higher than compared to using the Agent-to-Agent Delegation with an isolated context or the Single Agent, where only a single request is processed.

Coordinator and Worker Pattern

In Eclipse Theia, you implement the Coordinator and Worker Pattern by using Subagents via the built-in Tool Function delegateToAgent. Using a subagent means spawning a child agent within a session to handle a subtask in its own isolated context window. This can be seen in the delegateToAgent implementation. From a pattern perspective, this means there is a main coordinator agent that manages the overall task and delegates subtasks to specialized subagents. Each subagent call is sequential (the coordinator waits for that call to return), but the coordinator can spawn multiple subagent calls in parallel.

In this section, the previously created agents are converted into coordinator and worker agents.

Open the .prompts/customAgents.yml file

Change the prompt of the Research agent

Use ~{delegateToAgent} to delegate tasks to the Gists and the Link_Extractor agent

The following snippet shows how such an agent could look like

- id: Research
  name: Research
  description: This agent provides a collection of links for a specific topic.
  prompt: >-
    You are an agent that helps the developer by providing links to blog posts about a specific topic.
    To provide the necessary links use subagents to execute the following steps:

    1. Use the Gists subagent via ~{delegateToAgent} to fetch a collection of blog posts about the specific topic.
    2. For each of the found blog post link use the Link_Extractor subagent via ~{delegateToAgent} to fetch the content of the blog post and extract all links that are mentioned in the blog post.
    3. Provide a collection of the extracted links ordered by the blog post they are mentioned in. Use the anchor text as the name of the link if available. If the anchor text is not available, use the URL as the name of the link. Order them alphabetically by the name of the link.

  defaultLLM: default/universal
  showInChat: true

Change the prompt of the Gists agent

Remove the last step that delegates to the Link_Extractor agent
Ensure that the agent returns something at the end

The following snippet shows how such an agent could look like

- id: Gists
  name: Gists
  description: This agent provides a list of links to blog posts from a GitHub Gist.
  prompt: >-
    You are an agent that helps the developer by providing links to blog posts.

    To provide the necessary links execute the following steps:

    1. Fetch the publications of Dirk Fauth in the gists of the user fipro78. Use ~{mcp_github_list_gists} to find the correct gist.
    2. Use ~{mcp_fetch_fetch} to fetch the content of the gist with a max-length parameter of 15000.
    3. Filter the fetched content for links about the requested information.
    4. Provide a list of links to the relevant blog posts.

  defaultLLM: default/universal
  showInChat: true

Change the prompt of the Link_Extractor agent

Remove the iteration, as now the agent is called once per blog post
Ensure that the agent returns something at the end

The following snippet shows how such an agent could look like

- id: Link_Extractor
  name: Link_Extractor
  description: This agent provides a list of links extracted from blog posts.
  prompt: >-
    You are an agent that helps the developer by extracting links mentioned in a blog post and providing them in a structured format.

    To provide the necessary links execute the following steps:

    1. Use ~{mcp_fetch_fetch} to fetch the content of the blog post with a max-length parameter of 15000.
    2. Collect all links that are mentioned in the blog post and relevant for the topic.
    3. Filter out duplicate links and links that are not relevant for the topic. Relevance can be determined by the presence of keywords related to the topic in the context of the link.
    4. Provide a collection of the extracted filtered links ordered by the blog post they are mentioned in. Use the anchor text as the name of the link if available. If the anchor text is not available, use the URL as the name of the link. Order them alphabetically by the name of the link.

  defaultLLM: default/universal
  showInChat: true

Use the Custom Agent Research by selecting it in the chat prompt via @ syntax and add the prompt to execute, for example @Research show links about theia.

I noticed that it depends on the model used whether subagent calls are executed sequentially or in parallel. For example, with gemini-3.1-flash-lite-preview in the free tier, the delegateToAgent tool calls were executed sequentially. When executing the same workflow with gpt-5.4, the calls were executed in parallel, as you can see in the following screenshot:

Interestingly, token usage for the Coordinator and Worker Pattern in Theia uses fewer tokens than the Delegate Pattern but still slightly more than the single-agent solution.

Conclusion

There is no single “best” orchestration pattern for every scenario. The right choice depends on whether your priority is simplicity, reuse, user guidance, or token efficiency.

For quick implementations and straightforward tasks, a single agent is often the easiest and most reliable option. If you want to split responsibilities into reusable building blocks and keep a guided user flow, delegation is a good fit. If you need better context isolation and potentially lower token usage for larger workflows, a coordinator with specialized worker subagents is usually the strongest approach.

The key takeaway is to treat orchestration as an architectural decision, not just a prompt-writing detail. In Visual Studio Code, the selected orchestration pattern can have a clear impact on token usage, while in Eclipse Theia the impact is almost negligible in this scenario. Start with the simplest setup that works, measure behavior and token usage with your target model, and then evolve toward delegation or coordinator-worker designs when your workflow grows in complexity.

As agent tooling in Visual Studio Code and Eclipse Theia continues to evolve, these patterns will likely become even more powerful. Revisit your agent design regularly to benefit from new capabilities and improved model behavior.

Eclipse UI Best Practices and Icon Testing

2026-03-18T00:00:00+00:00

The Eclipse UI Best Practices project works on icon packs with modernized icons for the Eclipse IDE.

Testing New Icons in Your IDE

To try them out in your existing Eclipse installation, you can use the provided replace_icons.sh script.

Prerequisites

jq (for JSON parsing)
A JDK with the jar command

Steps

Clone the repository:

git clone https://github.com/eclipse-platform/ui-best-practices.git
cd ui-best-practices

Run the replacement script, pointing it to your Eclipse plugins directory and the desired icon mapping file:

./scripts/replace_icons.sh /path/to/eclipse/plugins iconpacks/eclipse-dual-tone/icon-mapping.json

The script reads the JSON mapping file, locates each icon in the icon pack, and replaces the corresponding icons inside the Eclipse plugins — whether they are folder-based or packaged as JARs.

Restart Eclipse with the -clean -clearPersistedState flags to clear the icon cache:

./eclipse -clean -clearPersistedState

You should now see the updated icons in your IDE.

Note: To see the new icons in EGit, you need a nightly build of EGit, as it only recently moved to SVG images.

Kudos to the Contributors

This project would not exist without the dedicated work of its contributors. Special thanks to Jasmin Hundt, Matthias Becker, Daniela Stegaru, and Michael Bangas. Their efforts are making the Eclipse IDE more visually modern and consistent.

Eclipse RCP Book - Fourth Edition

2026-02-18T00:00:00+00:00

I’m happy to announce the release of the fourth edition of the Eclipse RCP book, updated for Eclipse 2025-12.

Eclipse Rich Client Platform (RCP) powers some of the world’s most sophisticated desktop applications. This comprehensive guide takes you from first principles to professional application development, combining crystal-clear explanations with hands-on exercises that build a complete working application.

You’ll learn:

Building modern UIs with SWT, JFace, and CSS styling
OSGi modularity, dependency injection, and platform services
Command-line builds with Maven and Tycho
Migrating legacy Eclipse 3.x applications

Whether you’re building your first Eclipse application or modernizing existing systems, this book provides the complete roadmap. Each chapter pairs thorough explanations with detailed exercises.

This fourth edition is fully updated for Eclipse 2025-12 and reflects real-world best practices from hundreds of training sessions and production projects.

Get the book on Amazon:

Getting Started with Theia AI

2026-01-28T00:00:00+00:00

Eclipse Theia comes with quite extensive AI capabilities. This includes the usage of AI from a users perspective as well as from a developers perspective to implement AI features in Theia. This tutorial focuses on implementing AI features in Theia. But as you can not describe how to implement something without knowing how to use it in the end, there are also some Theia AI usage guides in here. For a more detailed description on how to use Theia AI as an end-user, have a look at Using the AI Features in the Theia IDE as an End User.

To get a better understanding of the Theia AI capabilities compared to Visual Studio Code GitHub Copilot, I will try to keep the same structure as in my Extending Copilot in Visual Studio Code tutorial. For Theia the structure will be a slightly different, as Theia AI is doing things differently and even provides some more features that help in providing AI features for end users.

Prerequisites

Additionally to using Visual Studio Code with Dev Containers for the development, you need access to a LLM (Large Language Model). If you have an AI subscription, e.g. from OpenAI, you can use that one. Have a look at the LLM Providers Overview to see which LLMs are currently supported by Theia. If you have a subscription for a LLM that is not listed here, check if it is compatible with the OpenAI API and try to configure it as a OpenAI Compatible Model.

If you do not have a subscription yet, but want to follow this tutorial, you can try a free alternative. So far I only found these two variants:

Google AI (in case you have a Google account)
Local LLM via Ollama

OpenAI offers a free tier, but this is only for the usage of ChatGPT. There is no free tier for the usage of the OpenAI API. You actually need to configure the billing setup in order to use it.

If you have a Google account, you can try out the Google AI Studio
- Create a new project via Google AI Studio - Projects
  - Click on Create a new project
  - Provide a name like theia-evaluation
  - Click on Create project
- Create a new API key via Google AI Studio - API Keys
  - Click on Create API Key
  - Give the key a name like theia
  - Select the previously created theia-evaluation project
  - Click on Create key
If you have a capable notebook or workstation, you can also try out a local LLM via Ollama
- Download and install Ollama for your operating system
- Pull a model that supports tool calls, e.g. llama3.2
```
ollama pull llama3.2
```

Since version 1.68.0 Theia also supports a GitHub Copilot language model integration.

Dependent on which LLM you want to use, I will show how it can be configured later.

Project Setup

As this tutorial is part of my Visual Studio Code Extension - Theia - Cookbook, I will use the Dev Container created with the Getting Started with Visual Studio Code Extension Development tutorial and extended in the Getting Started with Eclipse Theia tutorial.

Clone the Visual Studio Code Extension - Theia - Cookbook GitHub Repository from the vscode_copilot branch. You can also use the theia_getting_started branch if you don’t want the Visual Studio Code Copilot Extension in your setup.
```
git clone -b vscode_copilot https://github.com/fipro78/vscode_theia_cookbook.git
```
Switch to the new folder and open Visual Studio Code
```
cd vscode_theia_cookbook
code .
```
When asked, select Reopen in Container to build and open the project in the Dev Container

Update Dependencies

Developing applications that are based on web frameworks typically means that you have to handle dependency updates quite often. The reason is the high frequency in which libraries are updated. Sometimes it feels like the tutorials and blog posts that rely on a specific version of a library is outdated at the time it is published. The Eclipse Theia project also publishes new releases quite often, so it is a common task to update your dependencies. As several things happened since the Getting Started with Eclipse Theia tutorial, I will update the setup in the following section. It should be at least up-to-date at the time the tutorial is published, and describe in general the steps to follow for updating in the future.

Note:
You need at least to use Theia 1.70.0 to make all features work that are described and used in this tutorial.

Theia and Visual Studio Code can use Node 22 in the meanwhile. The Theia Prerequisites talk about the requirement Node.js >= 22 and <= 24 and the VS Code Dev Container is based on typescript-node:22-bookworm. Therefore we first update the project setup to use Node 22.

Open the file theia/package.json

Update the enginges section

"engines": {
  "node": ">=22 <=24",
  "npm": ">=10"
},

Open the file .devcontainer/devcontainer.json
- Update the image to typescript-node:22-bookworm
```
"image": "mcr.microsoft.com/devcontainers/typescript-node:1-22-bookworm",
```
Open the Dockerfile in the project root (used to containerize the application)
- Update the NODE_VERSION
```
ARG NODE_VERSION=22
```
Open the file .devcontainer/postCreateCommand.sh
- Install npm-check-updates to make dependency updates more comfortable.
```
npm install -g npm yo generator-code @vscode/vsce @angular/cli generator-theia-extension npm-check-updates
```
  Note:
  This step is of course opinionated. There are also other ways to update dependencies, but I personally found this one quite comfortable.
Rebuild the Dev Container (e.g. F1 -> Dev Containers: Rebuild Container)

After the Dev Container is rebuilt, lets update the dependencies of the Theia project(s) by using npm-check-updates. You can also use different ways to update the dependencies, e.g. by manually search and replace the Theia package versions with the most current one, or by executing npm outdated to get a list of outdated dependencies and the available newer versions, and then updating the versions dependency by dependency.

Open a Terminal
Switch to the theia folder
Execute the following command to show the outdated dependencies.
```
ncu
```
This will show that lerna is quite outdated. Although that is not really an issue, let’s also update that dependency.
Execute the following command to update the outdated dependencies in the package.json
```
ncu -u
```

Open the file theia/lerna.json

Change the content to the following

{
  "lerna": "9.0.0",
  "version": "0.0.0",
  "npmClient": "npm",
  "command": {
    "run": {
      "stream": true
    }
  }
}

Switch back to the Terminal
- Switch to the folder theia/browser-app
- Execute the following command to update the dependencies
```
ncu -u
```
- Switch to the folder theia/theia-customization
- Execute the following command to update the dependencies
```
ncu -u -i
```
  - Uncheck the typescript package to avoid that it gets updated automatically to version 6.x.
  - Answer the question Run npm install to install new versions? with n as we need to execute npm install from the theia parent folder.
- Switch to the folder theia/electron-app
- Execute the following command to update the dependencies in interactive mode
```
ncu -u -i
```
  - Uncheck the electron package to avoid that it gets updated automatically.
    This is necessary because the package @theia/electron@1.70.0 has a peer dependency to electron@39.7.0 and a newer dependency would break the build.
  - Answer the question Run npm install to install new versions? with n as we need to execute npm install from the theia parent folder.
- Open the file theia/electron-app/package.json
  - Update the electron version
    "devDependencies": { "electron": "^39.7.0" },
- Switch back to Terminal to the theia folder
- Run npm install to update the dependencies

Note:
Newer versions of @theia/electron might have a dependency to a newer electron version. You can find out which version is needed by looking into the @theia/electron - package.json and check for the peerDependencies.

Note:
If you get some strange errors after the dependency updates, try to cleanup the workspace first.

Delete the folder theia/node_modules
Delete the file theia/package-lock.json
Run npm install again

Create the new Theia AI Extension project

In the following section we will create a new Theia extension to add custom AI features to our Theia application.

Open a Terminal
Switch to the theia folder

Create a new Theia extension by using the theia-extension generator

yo theia-extension
? The extension's type Empty
? The extension's name ai-extension

Select do not overwrite (n) for every file that comes up with a conflict. It would otherwise remove all changes we applied before.
Add the necessary modifications manually
- Update the theia/package.json
  - Add a script to build the ai-extension and add the execution of that script to build:browser and build:electron
  - Change build:browser and build:electron to use lerna
    "scripts": { "build:ai-extension": "npm --prefix ai-extension run build", "build:customization": "npm --prefix theia-customization run build", "build:browser": "lerna run build --ignore electron-app", "build:electron": "lerna run build --ignore browser-app", },
    Note:
    This configuration is helpful for this tutorial as we only have two extensions, and if you now execute npm run build:browser it will first build the ai-extension and the theia-customization and then the browser-app but not the electron-app. In bigger setups it might be more efficient to build the changed extension and then the application. Or to have dedicated build jobs for different scenarios.
  - Add the new ai-extension module to the workspaces section
    "workspaces": [ "ai-extension", "theia-customization", "browser-app", "electron-app" ]
- Add the ai-extension module as a dependency to the browser-app and the electron-app
  - Open the package.json
  - Add the dependency to the dependencies section
    "dependencies": { ..., "ai-extension": "0.0.0" },
- Delete the newly created theia/.vscode folder
  We already copied the content to the .vscode folder in the previous tutorial.
- Switch back to Terminal to the theia folder
- Run npm install to update the project after the manual modifications

Add AI features

The code generator is generating basic project stubs. They do not contain the AI features already, so first we need to extend the browser-app and the electron-app to support AI.

Add Theia AI to the Theia application.

Note:
We add the dependencies to support AI Chat capabilities and MCP support in this tutorial. To also add AI support in the Editor and the Terminal, install the corresponding packages @theia/ai-editor and @theia/ai-terminal.

Note:
We add the dependencies to support LLMs that use the Google API, the OpenAI API and Ollama in this tutorial. If you need additional LLM API support, have a look at LLM Providers Overview to see what is available. If you for example have a GitHub Copilot license and want to use that, add the @theia/ai-copilot module which was added with Theia 1.68.0.
- Update the package.json of the browser-app and the electron-app
  - Open a Terminal
  - Switch to the Theia Application directory (browser-app and electron-app)
  - Add @theia/ai-core-ui to add UI Core
  - Add @theia/ai-history to add the AI history view
  - Add @theia/ai-ide to add the Chat and the default agents
  - Add @theia/ai-mcp-ui to add MCP support
  - Add @theia/ai-google to add Google API support
  - Add @theia/ai-ollama to add Ollama support
  - Add @theia/ai-openai to add OpenAI API support
    npm install @theia/ai-core-ui @theia/ai-history @theia/ai-ide @theia/ai-mcp-ui @theia/ai-google @theia/ai-ollama @theia/ai-openai
  The additional required packages will be added transitively. If you want to use any other LLM than Google AI, Ollama or OpenAI, add the corresponding module for your LLM.
- Build and run the Theia browser application
  If you created the tasks as explained in Optional: Define Tasks you can either
  - Press F1
    - Select Tasks: Run Task
    - Select Build Theia Browser to build the Theia browser application
    - Select Start Theia Browser to start the Theia browser application
  - Use the Task Explorer Visual Studio Code Extension
    - Expand npm in the Task Explorer view
    - Run the Build Theia Browser task from the tree to build the Theia browser application
    - Run the Start Theia Browser task from the tree to start the Theia browser application
  If you want to work with the Terminal and execute the npm scripts manually
  - Open a Terminal
  - Switch to the theia folder
  - Run npm run build:browser to build the Theia browser application
  - Run npm run start:browser to start the Theia browser application
  Note:
  You can also use the Launch Configuration from the .vscode/launch.json via Run and Debug. This will start the application and enable debugging. But you first need to build the application via commandline or Task.

Configure AI

Open a browser on http://localhost:3000 and see the started Theia application.
- Open the settings page by pressing CTRL + ,
  - Select the AI Features
  - Check Enable AI
  - Configure the LLM you want to use
    - Google
      - Api Key: Copy and paste your Google AI API key (see above)
        For this tutorial we simply configure the API key via preferences as it is easier than setting up the environment. In a productive environment you should use the environment variable GOOGLE_API_KEY to set the key securely.
      - Models: Ensure to have models in the list that are currently available according to Gemini Models
    - Ollama
      - Ollama Host: http://localhost:11434
      - Ollama Models: llama3.2
  - Configure the Model Aliases
    - Open the AI Configuration via Menu -> View -> AI Configuration
    - Switch to the Model Aliases tab
    - For every model alias select the model that you configured
- Instead of configuring everything via user interface, you can also directly paste one of the following configurations directly in the settings JSON
  - Switch to the JSON view of the settings by clicking the curly braces on the upper right corner of the editor (Open Settings (JSON))
  - Alternatively use the Command Palette (F1) and search for Preferences: Open Settings (JSON)
  - Copy one of the following snippets and paste it in the editor
    - Google
      { "ai-features.AiEnable.enableAI": true, "ai-features.google.apiKey": "", "ai-features.google.models": [ "gemini-2.5-pro", "gemini-2.5-flash", "gemini-2.5-flash-preview-09-2025", "gemini-2.0-flash", "gemini-2.0-flash-lite" ], "ai-features.languageModelAliases": { "default/code": { "selectedModel": "google/gemini-2.5-flash" }, "default/universal": { "selectedModel": "google/gemini-2.5-flash" }, "default/code-completion": { "selectedModel": "google/gemini-2.5-flash" }, "default/summarize": { "selectedModel": "google/gemini-2.5-flash" } } }
    - Ollama
      { "ai-features.AiEnable.enableAI": true, "ai-features.ollama.ollamaHost": "http://localhost:11434", "ai-features.ollama.ollamaModels": ["llama3.2"], "ai-features.languageModelAliases": { "default/code": { "selectedModel": "ollama/llama3.2" }, "default/universal": { "selectedModel": "ollama/llama3.2" }, "default/code-completion": { "selectedModel": "ollama/llama3.2" }, "default/summarize": { "selectedModel": "ollama/llama3.2" } } }
- Open the AI Chat view if it is not open already via CTRL + ALT + I or Menu Bar -> View -> AI Chat
- Enter something in the chat like @Universal Tell me a bar joke and check if the AI configuration works

Note:
If you want to use the GitHub Copilot language model integration, you need to click on the Copilot indicator in the status bar and follow the instructions in the dialog to authorize the application via the GitHub device authorization page. After the authorization succeeded, you can select one of the available Copilot language models in the AI Configuration.

Tool Functions

The first component you can contribute in Visual Studio Code to Copilot is a Language Model Tool. In Theia they are called Tool Functions. Such tools are used to extend the chat with domain-specific capabilities that can use the VSCode API to perform actions in Visual Studio Code.

In Visual Studio Code you configure the Language Model Tool in the contributes section of the package.json, implement the vscode.LanguageModelTool and register it via vscode.lm.registerTool() on activation of the extension. See Extending Copilot in Visual Studio Code - Language Model Tool for further details.

In Theia you implement a ToolProvider and bind it to the injection context. In this section we will create a Tool Function that creates a file in the current workspace that contains a joke as content.

Note:
Theia already contains a tool function with the name writeFileContent that can be used to create a file in the workspace. The implementation is WriteFileContent in case you are interested in the default implementation. So the following implementation is not necessary to achieve the result. It is intended as an example how the implementation of a Tool Function could look like.

Open a Terminal
- Switch to the theia/ai-extension directory
- Add @theia/ai-core as a dependency
```
npm install @theia/ai-core
```

Open the file theia/ai-extension/src/browser/ai-extension-contribution.ts

Implement a ToolProvider where the important things to notice are
- The definition of an ID which is used to call the Tool Function
- The implementation of the ToolRequest that is returned by getTool() where the handler is defined that represents the function

Replace the content with the following and adjust it if you want. This makes it easier to follow the tutorial instead of implementing everything by your own.

import {
  ToolProvider,
  ToolRequest,
  ToolInvocationContext,
} from "@theia/ai-core";
import { CommandRegistry } from "@theia/core";
import { BinaryBuffer } from "@theia/core/lib/common/buffer";
import { inject, injectable } from "@theia/core/shared/inversify";
import { FileService } from "@theia/filesystem/lib/browser/file-service";
import { WorkspaceService } from "@theia/workspace/lib/browser";
import { FileNavigatorCommands } from "@theia/navigator/lib/browser/navigator-contribution";

export const CREATE_JOKE_FILE_FUNCTION_ID = "jokeFileCreator";

@injectable()
export class JokeFileCreationFunction implements ToolProvider {
  static ID = CREATE_JOKE_FILE_FUNCTION_ID;

  @inject(WorkspaceService)
  protected workspaceService: WorkspaceService;

  @inject(FileService)
  protected readonly fileService: FileService;

  @inject(CommandRegistry)
  protected commandRegistry: CommandRegistry;

  getTool(): ToolRequest {
    return {
      id: JokeFileCreationFunction.ID,
      name: JokeFileCreationFunction.ID,
      description: `Create a file at the given path that contains a joke.`,
      parameters: {
        type: "object",
        properties: {
          path: {
            type: "string",
            description:
              "The name of the folder in the workspace where the joke file should be created.",
          },
          filename: {
            type: "string",
            description: "The name of the jokefile that should be created.",
          },
          joke: {
            type: "string",
            description: "The joke content to be written in the joke file.",
          },
        },
        required: ["path", "filename", "joke"],
      },
      handler: async (
        args: string,
        ctx: ToolInvocationContext,
      ): Promise<string> => {
        if (ctx?.cancellationToken?.isCancellationRequested) {
          return JSON.stringify({ error: "Operation cancelled by user" });
        }

        const { path, filename, joke } = JSON.parse(args);

        const wsRoots = await this.workspaceService.roots;
        if (wsRoots.length === 0) {
          throw new Error("No workspace has been opened yet");
        }
        const workspaceRoot = wsRoots[0].resource;
        const uri = workspaceRoot.resolve(path);

        try {
          await this.fileService.createFolder(uri);
        } catch (error) {
          return JSON.stringify({ error: error.message });
        }

        const fileUri = uri.resolve(filename);

        // ensure that we do not overwrite existing files
        if (await this.fileService.exists(fileUri)) {
          return JSON.stringify({
            error: `File ${fileUri} already exists`,
          });
        }

        try {
          await this.fileService.createFile(
            fileUri,
            BinaryBuffer.fromString(joke),
          );

          this.commandRegistry.executeCommand(
            FileNavigatorCommands.REFRESH_NAVIGATOR.id,
          );

          return `Successfully wrote a joke in the file ${fileUri}`;
        } catch (error) {
          return JSON.stringify({ error: error.message });
        }
      },
    };
  }
}

Open the file theia/ai-extension/src/browser/ai-extension-frontend-module.ts

Replace the content with the following

import { JokeFileCreationFunction } from "./ai-extension-contribution";
import { bindToolProvider } from "@theia/ai-core/lib/common";
import { ContainerModule } from "@theia/core/shared/inversify";

export default new ContainerModule((bind) => {
  bindToolProvider(JokeFileCreationFunction, bind);
});

You need an open workspace to make the Tool Function work. To be able to open a workspace in the Theia application create a folder example in the home directory of the node user in the Dev Container
```
mkdir ~/example
```
Build the Theia browser application
Run the Theia browser application
Open the Theia browser application on http://localhost:3000
Open the AI Configuration via Menu -> View -> AI Configuration
- Switch to the Tools tab
- Verify that there is an entry for jokeFileCreator that is set to Always Allow
  If you like to get a confirmation dialog before executing the tool, change the value to Confirm
Click on Open Folder in the Explorer tab to open a workspace
- Select the created node/example folder
In the AI Chat enter a prompt that uses the created tool function. This can be done by typing ~ followed by the tool id, in our case ~jokeFileCreator.
```
@Universal create a file that contains a joke in the folder test. use a file name that relates to the joke. ~jokeFileCreator
```
Check in the response if the jokeFileCreator function was executed and if a file with a joke was created.

Note:
If you compare the prompt we use in Theia with the prompt used in the Visual Studio Copilot tutorial, you notice some differences:

You specify a Theia Agent via @Universal
In previous versions of Theia the @Orchestrator agent was called when no other agent was explicitly mentioned. This caused additional requests in the background to find a matching agent. Since 1.67.0 you can also select a default agent in the settings under AI Features -> Chat: Default Agent. This agent will be used when no other agent is mentioned explicitly using the @ symbol. Note that specifying the default agent is done via agent ID without the leading @.
The Tool Function is specified via ~jokeFileCreator while the Language Model Tool in Visual Studio Code is targeted via #jokeFileCreator
The prompt is more descriptive, otherwise it might fail, where in Copilot the values are somehow set correctly. But that might be related to the model that is used.

MCP Server

The Model Context Protocol (MCP), is an open protocol to standardize how AI applications connect with external tools and data sources. MCP servers can offer resources, prompts and tools that can be used by a client.

In this section we will cover how to add MCP servers to a Theia application and how to use the provided MCP tools.

There are basically two types of MCP servers:

Local MCP servers (stdio transport)
A local MCP server runs on the same machine as the MCP client and is used to access local resources like files or run local scripts. Local servers are essential for tasks that require accessing local files or data that is not available remotely.
Remote MCP servers (streamable HTTP or server-sent events)

There are several ways to add MCP servers to Theia:

Configure them via settings.json
Programmatically via a Theia Extension

Note:
The usage of a mcp.json server configuration file, like in Visual Studio Code, is currently not supported, but proposed via this ticket. If you are interested in the mcp.json format in Visual Studio Code, have a look at Extending Copilot in Visual Studio Code - MCP Server for further details.

In this section I will describe how to manually configure MCP servers via settings.json and programmatically via Theia extension.

We will install

the Filesystem MCP Server as a local MCP Server
the Fetch MCP Server as a remote MCP Server
the GitHub MCP Server as a remote MCP Server that requires an authorization

Add MCP server via settings.json

In the following section we will add MCP servers via settings.json file. For this you need of course a running Theia application. At this point you don’t need to build anything, so simply start the Theia browser application or use the running instance if you did not stop the server from the previous steps.

Local MCP Server

Run the Theia browser application
Open the Theia browser application on http://localhost:3000
Open the settings page by pressing CTRL + ,
Switch to the JSON view of the settings by clicking the curly braces on the upper right corner of the editor (Open Settings (JSON))
- Alternatively use the Command Palette (F1) and search for Preferences: Open Settings (JSON)

Add the following content to configure the filesystem server as local MCP server.

"ai-features.mcp.mcpServers": {
  "filesystem": {
    "command": "npx",
    "args": [
      "-y",
      "@modelcontextprotocol/server-filesystem",
      "/home/node/example"
    ]
  }
},

Note:
The Filesystem MCP Server supports Roots. Visual Studio Code as a MCP client supports roots and sets the workspace as such. Since version 1.69.0 Theia also supports roots which was added via this pull request. In Theia it is possible to configure whether the workspace should be used as Root or not via the preference ai-features.mcp.useWorkspaceAsRoot.

The above configuration sets the autostart flag by default to true if the current open workspace is trusted and the workspace trust setting is enabled. If autostart is disabled or the server does not start automatically, you can start the server manually.

To start the filesystem MCP server you can either
- Use the command palette: F1 -> MCP: Start MCP Server -> filesystem
- Use the AI Configuration view: Menu -> View -> AI Configuration
  - Open the MCP Servers tab
  - Click on the Play button for the filesystem MCP server

Starting the server will discover the capabilities and tools provided by the server. These tools can then be used for example in the Chat.

Test if the configuration works by entering the following to the AI Chat

@Universal list files in /home/node/example ~mcp_filesystem_list_directory

You should now see that the mcp_filesystem_list_directory tool from the filesystem (MCP Server) is executed to solve your request.

Note:
The name of the tool to use can be found either by typing ~ and go through the list, or from the AI Configuration - MCP Servers view, if you expand the Tools section and click on the Copy tool icon of the corresponding tool.

To compare the results with the Visual Studio Code Copilot Extension example, you can also try to execute one of the following prompts:

@Universal list allowed directories ~mcp_filesystem_list_allowed_directories

or a more extended one

@Universal list files in the allowed directories and all subdirectories ~mcp_filesystem_list_allowed_directories ~mcp_filesystem_list_directory

Remote MCP Server

Add the following content to the settings.json in the ai-features.mcp.mcpServers section to configure the fetch server as remote MCP server.
```
"fetch": {
  "serverUrl": "https://remote.mcpservers.org/fetch/mcp"
}
```
Click on the Connect button to connect to the fetch remote MCP server

Test if the configuration works by entering the following to the AI Chat

@Universal fetch the content from https://eclipse.dev/nattable ~mcp_fetch_fetch

You should now see that the mcp_fetch_fetch tool from the fetch (MCP Server) is executed to solve your request.

Remote MCP Server with authorization

Most of the remote MCP servers require an authorization in order to work. Currently it is only possible to write the token in plain text into the settings.json file. As long as the settings.json is locally on your system, this is not an issue. But it can become an issue if you want to share your settings with team colleagues or store them on a central server. There is an open ticket that addresses this issue.

In the following section we will configure MCP servers with an authorization token in plain text in the settings.json.

To demonstrate this we use the GitHub MCP Server with a PAT (Personal Access Token). This is also described in Using the GitHub MCP Server.

Create a Personal Access Token as described in Creating a personal access token (classic)
Use repo as scope

You can use the GitHub MCP server locally via Docker. To make this work in a Dev Container you need the docker-in-docker feature added to the devcontainer.json

"features": {
  "ghcr.io/devcontainers/features/docker-in-docker:2": {},
}

The local GitHub MCP server can then be configured in the settings.json file like this:

"github": {
  "command": "docker",
  "args": [
      "run",
      "-i",
      "--rm",
      "-e",
      "GITHUB_PERSONAL_ACCESS_TOKEN",
      "ghcr.io/github/github-mcp-server"
  ],
  "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": ""
  }
}

The token is configured in the env section of the local MCP server configuration. Replace with the PAT created before.

Instead of using the GitHub MCP server locally, you can directly use the GitHub hosted server as explained in A practical guide on how to use the GitHub MCP server. The token can be configured via the serverAuthToken property, which resolves to a Bearer authorization token. If Bearer is not correct for the specific server, you can change this via the serverAuthTokenHeader property.

"github": {
  "serverUrl": "https://api.githubcopilot.com/mcp/",
  "serverAuthToken": ""
}

Alternatively you can configure the header also in the headers section directly, e.g. if you need to use a custom header for the authorization.

"github": {
  "serverUrl": "https://api.githubcopilot.com/mcp/",
  "headers": {
    "Authorization": "Bearer "
  }
}

Note:
GitHub recommends to authenticate against the MCP remote servers via OAuth. At the time writing this tutorial there is no OAuth support for MCP servers available in Theia, so you need to stick with the Authorization token until the OAuth support is added in Theia.

As the GitHub MCP Server provides a huge set of tools, the tools are categorized and not all tools are enabled by default. If you for example want to use the GitHub Gist related tools, you need to enable that. This can either be done by using the explicit MCP URL

"github": {
  "serverUrl": "https://api.githubcopilot.com/mcp/x/gists",
  "serverAuthToken": ""
}

or by setting the optional header X-MCP-Toolsets

"github": {
  "serverUrl": "https://api.githubcopilot.com/mcp/",
  "headers": {
    "Authorization": "Bearer ",
    "X-MCP-Toolsets": "gists"
  }
}

Further details about this are available in Remote GitHub MCP Server.

Test if the GitHub MCP Server configuration works

Start the server

Enter the following in the chat

@Universal fetch the publications written by Dirk Fauth in the gists of fipro78. Provide the links to blog posts about VS Code and Eclipse Theia in the chat that are extracted from a related gists file. Use ~mcp_github_list_gists  to list the available gists. Then use ~mcp_fetch_fetch  to fetch the content of the found gists with a max-length parameter of 15000.

Add MCP server programmatically via Theia Extension

You can also register MCP server programmatically via a Theia extension. This way you can for example bundle AI extensions like agents or the direct usage of the AI API with the registration of MCP servers that are needed for the provided functionality. You can also share default MCP servers with an authorization token that is configured in an environment variable.

To register a MCP server programmatically you can either use the MCPFrontendService or the MCPServerManager directly, which is used by the MCPFrontendService internally. To retrieve environment variables you can use the EnvVariablesServer.

In the following section we will register the MCP servers from the section above programmatically.

Note:
Remember to remove the MCP server configuration from the settings.json or use different names for the MCP servers to avoid naming collisions.

Open the file ai-extension/src/browser/ai-extension-contribution.ts

Add the necessary import statements

import { CommandRegistry, MessageService } from "@theia/core";
import { FrontendApplicationContribution } from "@theia/core/lib/browser";
import { EnvVariablesServer } from "@theia/core/lib/common/env-variables";
import {
  LocalMCPServerDescription,
  MCPFrontendService,
  RemoteMCPServerDescription,
} from "@theia/ai-mcp/lib/common";

Add a new class McpFrontendContribution that implements FrontendApplicationContribution
Get the MCPFrontendService and the EnvVariablesServer injected

Implement the onStart() method

Register the filesystem MCP server as local MCP server via LocalMCPServerDescription
Register the fetch MCP server as remote MCP server via RemoteMCPServerDescription
Register the github MCP server as remote MCP server via RemoteMCPServerDescription and add a resolve function to provide the GITHUB_TOKEN environment variable

@injectable()
export class McpFrontendContribution implements FrontendApplicationContribution {
  @inject(EnvVariablesServer)
  private readonly envVariablesServer: EnvVariablesServer;

  @inject(MCPFrontendService)
  protected readonly mcpFrontendService: MCPFrontendService;

  @inject(MessageService)
  private readonly messageService: MessageService;

  async onStart(): Promise<void> {
    try {
      // add a local MCP server
      const fileSystemServer: LocalMCPServerDescription = {
        name: "filesystem",
        command: "npx",
        args: [
          "-y",
          "@modelcontextprotocol/server-filesystem",
          "/home/node/example",
        ],
      };
      this.mcpFrontendService.addOrUpdateServer(fileSystemServer);

      // add a remote MCP server
      const fetchServer: RemoteMCPServerDescription = {
        name: "fetch",
        serverUrl: "https://remote.mcpservers.org/fetch/mcp",
      };
      this.mcpFrontendService.addOrUpdateServer(fetchServer);

      // get the GITHUB_TOKEN environment variable
      const githubTokenVar =
        await this.envVariablesServer.getValue("GITHUB_TOKEN");
      // add a remote MCP server with resolve method
      const githubServer: RemoteMCPServerDescription = {
        name: "github",
        serverUrl: "https://api.githubcopilot.com/mcp/",
        serverAuthToken: githubTokenVar?.value,
        headers: {
          "X-MCP-Toolsets": "gists",
        },
      };
      this.mcpFrontendService.addOrUpdateServer(githubServer);
    } catch (error) {
      console.error("Error configuring MCP server:", error);
      this.messageService.error(
        "Failed to configure MCP server. Please check the console for details.",
      );
    }
  }
}

Alternatively it is possible to get the token interactively by implementing resolve() of the RemoteMCPServerDescription:

Get the QuickInputService injected

@inject(QuickInputService)
protected readonly quickInputService: QuickInputService;

Change the githubServer definition
- Remove the serverAuthToken
- Add a resolve function that asks for the authentication token by using the QuickInputService

const githubServer: RemoteMCPServerDescription = {
  name: "github",
  serverUrl: "https://api.githubcopilot.com/mcp/",
  headers: {
    "X-MCP-Toolsets": "gists",
  },
  resolve: async (serverDescription) => {
    console.log("Resolving GitHub MCP server description");

    // Prompt user for authentication token
    const authToken = await this.quickInputService.input({
      prompt: "Enter authentication token for GitHubMCP server",
      password: true,
      value:
        "serverAuthToken" in serverDescription
          ? serverDescription.serverAuthToken || ""
          : "",
    });

    if (authToken) {
      // Return updated server description with new token
      return {
        ...serverDescription,
        serverAuthToken: authToken,
      } as RemoteMCPServerDescription;
    }

    // If no token provided, return original description
    return serverDescription;
  },
};
this.mcpFrontendService.addOrUpdateServer(githubServer);

Note:
If you want to automatically start the programmatically registered MCP servers, you need to call the corresponding API at the end:

this.mcpFrontendService.startServer(fileSystemServer.name);
this.mcpFrontendService.startServer(fetchServer.name);
this.mcpFrontendService.startServer(githubServer.name);

Open the file ai-extension/src/browser/ai-extension-frontend-module.ts

import {
  McpFrontendContribution,
  JokeFileCreationFunction,
} from "./ai-extension-contribution";
import { bindToolProvider } from "@theia/ai-core/lib/common";
import { FrontendApplicationContribution } from "@theia/core/lib/browser";
import { ContainerModule } from "@theia/core/shared/inversify";

export default new ContainerModule((bind) => {
  bindToolProvider(JokeFileCreationFunction, bind);

  bind(McpFrontendContribution).toSelf().inSingletonScope();
  bind(FrontendApplicationContribution).toService(McpFrontendContribution);
});

Build the Theia browser application
Run the Theia browser application
Open the Theia browser application on http://localhost:3000
Open the AI Configuration via Menu -> View -> AI Configuration
Switch to the MCP Servers tab
Start the MCP servers if they are not configured to autostart
In the AI Chat view use prompts like in the section before to verify that the MCP servers are registered and working correctly.

Further information about MCP in Theia:

Agents

Custom agents in Theia allow the creation of custom workflows and extending the Theia IDE with new capabilities. An agent in Theia AI is comparable to the Chat Participant in Visual Studio Code Copilot. So it is a specialized assistant to extend the IDE with domain specific experts knowledge. In comparison to Visual Studio Code, this is not limited to the chat, it can also be integrated into other parts of the IDE like the editor, the terminal or a custom widget. Similar to the Chat Participant in Visual Studio Code, an agent can use the available and exposed Theia AI to access and integrate in the Theia application. This applies of course to agents that are implemented and contributed programmatically.

Note:
Defining a custom agent via configuration file similar to custom agents in Visual Studio Code will be described in Further customizations.

Implement a Custom Agent

In this section we will implement a Custom Agent. In the section after this one, we will extend the agent to have more influence on the processing, access the Theia API or add agent specific variables and tools.

Create a new file ai-extension/src/browser/ai-extension-joker-agent.ts

Create a new class JokerChatAgent that extends AbstractStreamParsingChatAgent

Define a BasePromptFragment that basically consists of an id and a template
Set the required fields according to your needs
- Define the LanguageModelRequirement for the purpose chat and by default uses default/universal model alias
- Set the prompts and define a simple PromptVariantSet based on the single `BasePromptFragment
- Add the Tool Function jokeFileCreator that we created before to the functions
Copy and paste the following code to the new file to make it easy to proceed

import { AbstractStreamParsingChatAgent } from "@theia/ai-chat";
import {
  BasePromptFragment,
  LanguageModelRequirement,
} from "@theia/ai-core";
import { CREATE_JOKE_FILE_FUNCTION_ID } from "./ai-extension-contribution";
import { injectable } from "@theia/core/shared/inversify";

export const jokerTemplate: BasePromptFragment = {
  id: "joker-system-default",
  template: `
  # Instructions
    
  You are the Joker, the arch enemy of Batman.
  To attack Batman, you tell a joke that is so funny, it distracts him from his mission.
  To keep the distraction going on, write the joke to a file. Use **~{${CREATE_JOKE_FILE_FUNCTION_ID}}** to write the joke to a file.
  If the user does not provide a path, create a new folder "bat-jokes" in the current workspace folder and store the file in that folder.
  Choose a filename that is related to the joke itself.
  `,
};

@injectable()
export class JokerChatAgent extends AbstractStreamParsingChatAgent {
  id: string = "Joker";
  name: string = "Joker";
  languageModelRequirements: LanguageModelRequirement[] = [
    {
      purpose: "chat",
      identifier: "default/universal",
    },
  ];
  protected defaultLanguageModelPurpose: string = "chat";
  override description =
    "This agent creates a file with a joke about batman.";

  override iconClass: string = "codicon codicon-feedback";
  protected override systemPromptId: string = "joker-system";
  override prompts = [
    { id: "joker-system", defaultVariant: jokerTemplate, variants: [] },
  ];
  override functions = [CREATE_JOKE_FILE_FUNCTION_ID];
}

Open the file ai-extension/src/browser/ai-extension-frontend-module.ts

Import the necessary dependencies
Register the JokerChatAgent via dependency injection
Register it as an Agent

import {
  McpFrontendContribution,
  JokeFileCreationFunction,
} from "./ai-extension-contribution";
import { Agent, bindToolProvider } from "@theia/ai-core/lib/common";
import { ChatAgent } from "@theia/ai-chat/lib/common";
import { FrontendApplicationContribution } from "@theia/core/lib/browser";
import { ContainerModule } from "@theia/core/shared/inversify";
import { JokerChatAgent } from "./ai-extension-joker-agent";

export default new ContainerModule((bind) => {
  bindToolProvider(JokeFileCreationFunction, bind);

  bind(McpFrontendContribution).toSelf().inSingletonScope();
  bind(FrontendApplicationContribution).toService(McpFrontendContribution);

  bind(JokerChatAgent).toSelf().inSingletonScope();
  bind(Agent).toService(JokerChatAgent);
  bind(ChatAgent).toService(JokerChatAgent);
});

Build the Theia browser application
Run the Theia browser application
Open the Theia browser application on http://localhost:3000
Open the AI Configuration via Menu -> View -> AI Configuration
- Switch to the Agents tab
- Verify that the Joker agent is listed
In the AI Chat enter a prompt that uses the @Joker agent.
```
@Joker tell me a joke about batman
```
Check in the response if the jokeFileCreator function was executed and if a file with a joke was created.

Further information about Custom Agents in Theia AI can be found here:

Advanced Theia AI Agent features

The above agent implementation is pretty simple, and actually you can achieve the same by creating a Custom Agent via configuration file, as the agent basically only consists of a specialized prompt. The advantage of a programmatically registered Custom Agent is:

it can be integrated and delivered with the Theia application, without the need to have a user to define a customAgents.yml file
you can use the Theia API to, for example customize the response rendering, access the platform to perform additional tasks, start a related MCP server in case it is not already started but needed for the processing.

We will have a look at those features in the following sections.

Prompt Variants

Theia supports a feature called Prompt Variants which enables tool builders to define multiple prompts per agents that a user can switch between. To demonstrate that we will add a new Prompt Variant to the JokerChatAgent that does not use the Tool Function to write the joke into a file.

Open the file ai-extension/src/browser/ai-extension-joker-agent.ts

Define a new BasePromptFragment with a simplified prompt

export const jokerTemplateSimple: BasePromptFragment = {
  id: "joker-system-simple",
  template: `
  # Instructions
    
  You are the Joker, the arch enemy of Batman.
  To attack Batman, you tell a joke that is so funny, it distracts him from his mission.
  `,
};

Extend the prompts field to specify the prompt variants

override prompts = [
  {
    id: "joker-system",
    defaultVariant: jokerTemplate,
    variants: [jokerTemplate, jokerTemplateSimple],
  },
];

Build the Theia browser application
Run the Theia browser application
Open the Theia browser application on http://localhost:3000
Open the AI Configuration via Menu -> View -> AI Configuration
- Switch to the Agents tab
- Select the Joker agent
- Select the joker-system-simple entry in the Prompt Templates combobox
In the AI Chat enter a prompt that uses the @Joker agent.
```
@Joker tell me a joke about batman
```
Check that now there is only a joke in the response, but no file is generated.

By using Prompt Variants you are able to provide users different ways how an agent works. In Theia Prompt Variants are for example used to switch the @Coder chat agent to the Agent mode. This is explained in Theia Coder Agent Mode: From AI Assistant to Autonomous Developer that also has a video linked to show it in more detail.

Note:
A user is even able to adjust prompt templates via the AI Configuration. By clicking the Edit button next to the selected Prompt Template, the Prompt Template can be modified, which will create a .prompttemplate file in the .theia/prompt-templates folder in the user home.

Agent Modes

It is possible to define multiple operational modes for a Chat Agent that allow users to control how the agent responds. This way agents can adjust their behavior based on user preferences. The Coder agent and the Architect agent in Theia support Agent Modes. They extend the AbstractModeAwareChatAgent, which is defined in the @theia/ai-ide package. This implementation maps Prompt Variants to Agent Modes, so a user can directly change the behavior of the agent by selecting a mode and does not need to switch to the settings every time. The mode can also control other behavior, for example how a response is rendered or whether the agent should explain or fix something.

As mentioned, there is an AbstractModeAwareChatAgent implementation that can be extended to achieve mode-to-prompt-fragment mapping. But first, we will implement similar behavior in a simpler way in the Joker agent to better understand Agent Mode support details.

Open the file ai-extension/src/browser/ai-extension-joker-agent.ts

Define a new BasePromptFragment with a simplified prompt that swears and uses emojis and does not save the joke to a file.

export const jokerTemplateSwear: BasePromptFragment = {
  id: "joker-system-swear",
  template: `
  # Instructions
    
  You are the Joker, the arch enemy of Batman.
  To attack Batman, you tell a joke that is so funny, it distracts him from his mission.
  You swear a lot and use a lot of emojis in your jokes to make them even more distracting for Batman.
  `,
};

Extend the prompts field to specify the prompt variants

override prompts = [
  {
    id: "joker-system",
    defaultVariant: jokerTemplate,
    variants: [jokerTemplate, jokerTemplateSimple, jokerTemplateSwear],
  },
];

Define the modes the agent supports.
Use the IDs of the templates and a corresponding user-facing name.

modes = [
  { id: jokerTemplate.id, name: "Default Mode" },
  { id: jokerTemplateSimple.id, name: "Simple Mode" },
  { id: jokerTemplateSwear.id, name: "Swear Mode" },
];

Override the method getSystemMessageDescription() to get the prompt fragment to use from the selected mode in the request context.

protected override async getSystemMessageDescription(
  context: AIVariableContext,
): Promise<SystemMessageDescription | undefined> {
  if (this.systemPromptId === undefined) {
    return undefined;
  }

  // Check for mode-based override from request
  let modeId = ChatSessionContext.is(context)
    ? context.request?.request.modeId
    : undefined;
  if (!modeId) {
    modeId = jokerTemplate.id; // fallback to default mode if no mode is specified in the request
  }

  const isCustomized =
    this.promptService.getPromptVariantInfo(modeId)?.isCustomized ?? false;
  const resolvedPrompt = await this.promptService.getResolvedPromptFragment(
    modeId,
    undefined,
    context,
  );
  return resolvedPrompt
    ? SystemMessageDescription.fromResolvedPromptFragment(
        resolvedPrompt,
        modeId,
        isCustomized,
      )
    : undefined;
}

Build the Theia browser application
Run the Theia browser application
Open the Theia browser application on http://localhost:3000
In the AI Chat enter a prompt that uses the @Joker agent. Do not send the chat request yet.
```
@Joker tell me a joke about batman
```
After selecting the Joker agent, a combobox appears to allow the user to select an Agent Mode
Select the Swear Mode
Send the chat request
Check that there is now only a joke in the response and no file is generated. The response should also contain multiple emojis. :smile:

At this point, we use the Agent Mode to let a user easily switch between available Prompt Variants. The implementation shown above is a simplified version of the existing AbstractModeAwareChatAgent, and it helps explain Agent Mode support in general. For this use case, we now change the implementation to extend AbstractModeAwareChatAgent.

Open a Terminal
- Switch to the theia/ai-extension directory
- Add @theia/ai-ide as a dependency
```
npm install @theia/ai-ide
```

Open the file ai-extension/src/browser/ai-extension-joker-agent.ts

Update the imports and add the AbstractModeAwareChatAgent from the @theia/ai-ide package and the ChatMode from the @theia/ai-chat package

import { ChatAgentService, ChatMode } from "@theia/ai-chat";
import {
  BasePromptFragment,
  LanguageModelRequirement,
} from "@theia/ai-core";
import { AbstractModeAwareChatAgent } from "@theia/ai-ide/lib/browser/mode-aware-chat-agent";
import { CREATE_JOKE_FILE_FUNCTION_ID } from "./ai-extension-contribution";
import { inject, injectable } from "@theia/core/shared/inversify";

Change the JokerChatAgent to extend AbstractModeAwareChatAgent instead of AbstractStreamParsingChatAgent
```
@injectable()
export class JokerChatAgent extends AbstractModeAwareChatAgent {
```

Change the modes field to modeDefinitions in the following format

protected readonly modeDefinitions: Omit<ChatMode, "isDefault">[] = [
  { id: jokerTemplate.id, name: "Default Mode" },
  { id: jokerTemplateSimple.id, name: "Simple Mode" },
  { id: jokerTemplateSwear.id, name: "Swear Mode" },
];

Remove the method getSystemMessageDescription() as it is implemented in AbstractModeAwareChatAgent

Build the Theia browser application
Run the Theia browser application
Open the Theia browser application on http://localhost:3000
In the AI Chat enter a prompt that uses the @Joker agent. Do not send the chat request yet.
```
@Joker tell me a joke about batman
```
After selecting the Joker agent, a combobox appears to allow the user to select an Agent Mode
Select the Swear Mode
Send the chat request
Check that there is now only a joke in the response and no file is generated. The response should also contain multiple emojis. :smile:

Further information about Agent Modes can be found here:

Agent-specific Variables

Additionally to Tool Functions that can be used in prompts, you can define Variables that can be resolved at runtime. There are Global Variables and Agent-specific Variables. Global Variables are available to all agents. Theia provides some Global Variables like for example #selectedText for the currently selected text or #currentFileContent for the whole content of the currently opened file.

You can see which Global Variables are available in the AI Configuration on the Variables tab. To use a Global Variable you can type a # in the AI Chat and then select it from the list of available variables, e.g. open a joke file that was created before and write something like the following to the chat:

explain #currentFileContent

I will not go into detail on how to implement Global Variables here. The Global Variables section in the Theia documentation and the implementation of the #today variable.

For creating custom agents programmatically, it can be interesting to define Agent-specific Variables. Such variables can be filled by any Theia API and enables extended use cases, like adding data to a prompt dynamically and even adding data before the work is delegated to another agent.

In this section we will implement another chat agent that uses Agent-specific Variables and is able to write content into a file in the workspace. The following implementation is used to get a better understanding of a programmatically defined agent and the usage of Agent-specific Variables.

Create a new file ai-extension/src/browser/ai-extension-writer-agent.ts

Create a new class WriterChatAgent that extends AbstractStreamParsingChatAgent
Specify a prompt that
- uses the variable placeholders {{folder}} and {{content}}
- uses the jokeFileCreator Tool Function
Define the agentSpecificVariables field to declare the variables folder and content which enables to keep track of used variables and even shows that information on the agent configuration page.
Implement getSystemMessageDescription() where the variables are resolved
- Extract the values from the request
- If they are not present in the request, define a default value

import {
  AbstractStreamParsingChatAgent,
  SystemMessageDescription,
} from "@theia/ai-chat";
import {
  AIVariableContext,
  BasePromptFragment,
  LanguageModelRequirement,
} from "@theia/ai-core";
import { injectable } from "@theia/core/shared/inversify";
import { CREATE_JOKE_FILE_FUNCTION_ID } from "./ai-extension-contribution";

export const writerTemplate: BasePromptFragment = {
  id: "writer-system-default",
  template: `
      # Instructions
      
      You are an agent that operates in the current workspace of the Theia IDE. 
      You are able to persist the provided content into a file by using ~{${CREATE_JOKE_FILE_FUNCTION_ID}}.
      Derive the filename out of the provided content if no filename is provided.
      The file should be created in the folder {{folder}} in the current workspace.
  
      The content to persist is as follows:
      {{content}}
      `,
};

@injectable()
export class WriterChatAgent extends AbstractStreamParsingChatAgent {
  id: string = "Writer";
  name: string = "Writer";
  languageModelRequirements: LanguageModelRequirement[] = [
    {
      purpose: "chat",
      identifier: "default/universal",
    },
  ];
  protected defaultLanguageModelPurpose: string = "chat";
  override description =
    "This is an agent that is able to persist content into a file in the workspace.";

  override iconClass: string = "codicon codicon-new-file";
  protected override systemPromptId: string = "writer-system";
  override prompts = [
    { id: "writer-system", defaultVariant: writerTemplate, variants: [] },
  ];
  override functions = [CREATE_JOKE_FILE_FUNCTION_ID];
  override agentSpecificVariables = [
    {
      name: "folder",
      description: "The folder in which the file should be created.",
      usedInPrompt: true,
    },
    {
      name: "content",
      description: "The content to persist into the file.",
      usedInPrompt: true,
    },
  ];

  protected override async getSystemMessageDescription(
    context: AIVariableContext,
  ): Promise<SystemMessageDescription | undefined> {
    // extract data from the context
    let request = (context as any).request;
    let folder = request.getDataByKey(`folder`) as string;
    let content = request.getDataByKey(`content`) as string;

    // provide default values if not set
    if (!folder) {
      folder = "temp";
    }

    if (!content) {
      content = "Lorem ipsum dolor sit amet.";
    }

    const variableValues = {
      folder: folder,
      content: content,
    };

    // get the resolved prompt
    const resolvedPrompt = await this.promptService.getResolvedPromptFragment(
      this.systemPromptId,
      variableValues,
      context,
    );

    // return the system message description
    return resolvedPrompt
      ? SystemMessageDescription.fromResolvedPromptFragment(resolvedPrompt)
      : undefined;
  }
}

Open the file ai-extension/src/browser/ai-extension-frontend-module.ts

bind(WriterChatAgent).toSelf().inSingletonScope();
bind(Agent).toService(WriterChatAgent);
bind(ChatAgent).toService(WriterChatAgent);

Build the Theia browser application
Run the Theia browser application
Open the Theia browser application on http://localhost:3000
In the AI Chat enter a prompt that uses the @Writer agent.
```
@Writer write a file
```

You should see that a new file is generated in a new folder temp that contains the text Lorem ipsum dolor sit amet.

Further information about variables in Theia AI can be found here:

Agent-to-Agent Delegation (programmatically)

You can delegate the processing from one agent to another by using the delegateToAgent Tool Function. This is described in Agent-to-Agent Delegation in the Theia documentation, and I describe this also later in Agent-to-Agent Delegation (function). As in some cases it might be interesting to delegate to another agent programmatically, I will describe this approach in the following section. Delegating to another agent can be done by using the ChatAgentService Theia API.

In the following section we will extend the JokerChatAgent to programmatically forward to the WriterChatAgent if the joker-system-simple prompt template was selected. There are different ways to find out which Prompt Template was selected, dependent on whether Agent Modes are used that map to Prompt Templates or if the selection can only be done in the settings.

To retrieve the selected Prompt Template from the settings, use PromptService#getSelectedVariantId(promptVariantSetId) or PromptService#getEffectiveVariantId(promptVariantSetId)
To retrieve the selected Agent Mode inspect the chat request object via request.request.modeId.

Open the file ai-extension/src/browser/ai-extension-joker-agent.ts

Get the ChatAgentService injected

@inject(ChatAgentService)
protected chatAgentService: ChatAgentService;

Override addContentsToResponse()

Check if the selected variant was the joker-system-simple template by using the PromptService
Add the content and the folder data to the request
Get the WriterChatAgent by using the ChatAgentService
Delegate the request to the WriterChatAgent

protected override async addContentsToResponse(
  response: LanguageModelResponse,
  request: MutableChatRequestModel
): Promise<void> {
  await super.addContentsToResponse(response, request);

  const selectedVariantId = request.request.modeId
    ? request.request.modeId
    : this.promptService.getEffectiveVariantId(this.systemPromptId);

  if (selectedVariantId === jokerTemplateSimple.id) {
    // extract information from the result and add it to the request
    const responseText = await getTextOfResponse(response);
    request.addData("content", responseText);
    request.addData("folder", "bat-jokes");

    const agent = this.chatAgentService.getAgent("Writer");
    if (!agent) {
      throw new Error(`Chat agent "Writer" not found.`);
    }

    return await agent.invoke(request);
  }
}

Update the import statements to fix the compile errors

import {
  AbstractStreamParsingChatAgent,
  ChatAgentService,
  MutableChatRequestModel,
} from "@theia/ai-chat";
import {
  BasePromptFragment,
  getTextOfResponse,
  LanguageModelRequirement,
  LanguageModelResponse,
} from "@theia/ai-core";
import { CREATE_JOKE_FILE_FUNCTION_ID } from "./ai-extension-contribution";
import { inject, injectable } from "@theia/core/shared/inversify";

Build the Theia browser application
Run the Theia browser application
Open the Theia browser application on http://localhost:3000
Open the AI Configuration via Menu -> View -> AI Configuration
- Switch to the Agents tab
- Select the Joker agent
- Ensure that the joker-system-simple entry is selected in the Prompt Templates combobox
  (note that this will preselect the Simple Mode agent mode)
In the AI Chat enter a prompt that uses the @Joker agent.
```
@Joker a joke about scarecrow
```
Verify that the Simple Mode is selected in the Agent Mode combobox
Check that now there is a joke in the response and a file is generated.

The above implementation is of course a pretty simple one with the intention to show how it basically works. A more advanced example on how to programmatically forward from one agent to another can be seen in the @Orchestrator chat agent implementation provided by Theia itself.

And if you are interested in the implementation of the delegateToAgent Tool Function, have a look here.

Custom Response Part Rendering

Another interesting feature when implementing a Custom Agent in Theia, is the ability to fully customize the chat response rendering. This can be done by overriding AbstractChatAgent#addContentsToResponse() and adding additional content of type ChatResponseContent to the response.

There are already several default implementations of ChatResponseContent available that can be used to customize the response:

CodeChatResponseContent
CommandChatResponseContent
ErrorChatResponseContent
HorizontalLayoutChatResponseContent
InformationalChatResponseContent
MarkdownChatResponseContent
ProgressChatResponseContent
QuestionResponseContent
TextChatResponseContent
ThinkingChatResponseContent
ToolCallChatResponseContent

Those default interfaces and implementations are located in chat-model.ts.

To add a simple static text to the response, you can use the TextChatResponseContent, or if it should be formatted in some way the MarkdownChatResponseContent.

Open the file ai-extension/src/browser/ai-extension-joker-agent.ts

In the method addContentsToResponse() add a TextChatResponseContentImpl or a MarkdownChatResponseContentImpl

request.response.response.addContent(
  new TextChatResponseContentImpl(
    `Hilarious, Batman will never recover from this as he will always try to remember my distracting jokes!`,
  ),
);

request.response.response.addContent(
  new MarkdownChatResponseContentImpl(
    `Hilarious, **Batman** :bat: will never recover from this :dizzy_face: as he will always try to remember my _distracting jokes_!`,
  ),
);

You can also implement your own ChatResponseContent with a corresponding renderer, to have even more control on how the response should be rendered. This is described in more detail in Custom Response Part Rendering of the Theia documentation.

You can also register a custom renderer for the existing ChatResponseContent implementations. We will create a customized renderer for the QuestionResponseContent and extend the JokerChatAgent to ask the user if the joke should be saved in a file.

Note:
We are doing this because the default QuestionPartRenderer implementation is intended to ask the user as part of the prompt and shows the buttons disabled if the process is not waiting for input. In our case the first step is done and we do not put the process in a waiting state. If you are interested in the question-response-handling with the waiting state, have a look at the Theia AskAndContinueChatAgent example.

Open the file ai-extension/src/browser/ai-extension-joker-agent.ts

In the method addContentsToResponse() add a QuestionResponseContentImpl

Ask the user if the joke should be saved to a file.
If the answer is Yes delegate to the Writer agent.
If the answer is No show the markup message from the previous section.

protected override async addContentsToResponse(
  response: LanguageModelResponse,
  request: MutableChatRequestModel,
): Promise<void> {
  await super.addContentsToResponse(response, request);

  const selectedVariantId = request.request.modeId
    ? request.request.modeId
    : this.promptService.getEffectiveVariantId(this.systemPromptId);

  if (selectedVariantId === jokerTemplateSimple.id) {
    // if the simple variant is selected, ask if the user wants to delegate to the Writer agent
    request.response.response.addContent(
      new QuestionResponseContentImpl(
        `I have created a funny joke for you. Would you like me to save it to a file using the Writer agent?`,
        [
          { text: "Yes", value: "yes" },
          { text: "No", value: "no" },
        ],
        request,
        async (selectedOption) => {
          if (selectedOption.value === "yes") {
            // get the response text and add it to the request for the Writer agent
            const responseText = await getTextOfResponse(response);
            request.addData("content", responseText);
            request.addData("folder", "bat-jokes");

            // delegate to the Writer agent to save the joke to a file
            const agent = this.chatAgentService.getAgent("Writer");
            if (!agent) {
              throw new Error(`Chat agent "Writer" not found.`);
            }

            await agent.invoke(request);
          } else {
            // don't save to file, just add a funny closing remark
            request.response.response.addContent(
              new MarkdownChatResponseContentImpl(
                `Hilarious, **Batman** :bat: will never recover from this :dizzy_face: as he will always try to remember my _distracting jokes_!`,
              ),
            );
          }
        },
      ),
    );
  }
}

Create a new file ai-extension/src/browser/no-wait-question-part-renderer.tsx

Copy the code from QuestionPartRenderer
Change the name to NoWaitQuestionPartRenderer
In the canHandle() method return a value > 10 to ensure that our renderer is picked in the rendering process

Change the definition of isDisabled to only check the question.selectedOption to ensure the buttons are shown disabled once the user selected an option. The other statements would show the buttons always disabled in our case, as we do not put the processing in a waiting state.

import {
  ChatResponseContent,
  QuestionResponseContent,
  QuestionResponseHandler,
} from "@theia/ai-chat";
import { injectable } from "@theia/core/shared/inversify";
import * as React from "@theia/core/shared/react";
import { ReactNode } from "@theia/core/shared/react";
import { ChatResponsePartRenderer } from "@theia/ai-chat-ui/lib/browser/chat-response-part-renderer";
import { ResponseNode } from "@theia/ai-chat-ui/lib/browser/chat-tree-view";

@injectable()
export class NoWaitQuestionPartRenderer implements ChatResponsePartRenderer<QuestionResponseContent> {
  canHandle(response: ChatResponseContent): number {
    if (QuestionResponseContent.is(response)) {
      return 100;
    }
    return -1;
  }

  render(question: QuestionResponseContent, node: ResponseNode): ReactNode {
    const isDisabled = question.selectedOption !== undefined;

    return (
      <div className="theia-QuestionPartRenderer-root">
        <div className="theia-QuestionPartRenderer-question">
          {question.question}
        </div>
        <div className="theia-QuestionPartRenderer-options">
          {question.options.map((option, index) => (
            <button
              className={`theia-button theia-QuestionPartRenderer-option ${
                question.selectedOption?.text === option.text ? "selected" : ""
              }`}
              onClick={() => {
                if (!question.isReadOnly && question.handler) {
                  question.selectedOption = option;
                  (question.handler as QuestionResponseHandler)(option);
                }
              }}
              disabled={isDisabled}
              key={index}
            >
              {option.text}
            </button>
          ))}
        </div>
      </div>
    );
  }
}

Open the file ai-extension/src/browser/ai-extension-frontend-module.ts

Import the ChatResponsePartRenderer interface

import { ChatResponsePartRenderer } from "@theia/ai-chat-ui/lib/browser/chat-response-part-renderer";

bind(ChatResponsePartRenderer)
  .to(NoWaitQuestionPartRenderer)
  .inSingletonScope();

Build the Theia browser application
Run the Theia browser application
Open the Theia browser application on http://localhost:3000
Open the AI Configuration via Menu -> View -> AI Configuration
- Switch to the Agents tab
- Select the Joker agent
- Ensure that the joker-system-simple entry is selected in the Prompt Templates combobox
In the AI Chat enter a prompt that uses the @Joker agent.
```
@Joker a joke about scarecrow
```
Check that additionally to the joke you are asked whether to save the joke to a file and two buttons to select how to proceed
If you select Yes the file should be saved
If you select No you should only get the markdown formatted response

Further Customizations

Users can further customize the Theia AI experience by configuring Task Contexts, Prompt Fragments, Slash Commands, Custom Agents and Agent Skills.

Task Context
Task Context is a concept to externalize your intent into dedicated files that serve as persistent, editable records of what you want the AI to accomplish. Task Context files are stored in .prompts/task-context/ with the default settings. Additional information is available in Structured AI Coding with Task Context: A Better Way to Work with AI Agents.
Prompt Fragments
Prompt Fragments are used to define reusable prompts to execute reusable development tasks. Prompt Fragment files are stored in the .prompts folder with the default settings.
They are similar to Visual Studio Code Copilot Prompt Files.
Slash Commands
Slash Commands are basically a way to execute a Prompt Fragment in a more intuitive way. Configuring a Prompt Fragment as a Slash Command makes them feel even more like using Prompt Files in Visual Studio Code Copilot.
Custom Agents
Custom Agents are used to create a specialist assistant for specific tasks that can be used in the chat for planning or research or to define specialized workflows. Custom Agents are stored in a .prompts/customAgents.yml file with the default settings.
They are similar to Visual Studio Code Copilot Custom Agents.
Agent Skills
Agent Skills are used to create reusable capabilities that work across different AI tools. They can include scripts, examples, or other resources alongside instructions. You can define specialized workflows like testing, debugging, or deployment processes by using Agent Skills. Project skills can be stored in the folder .prompts/skills/. Personal skills can be stored in the user home in the folder ~/.theia/skills/.

By having the task contexts, prompt fragments, custom agents and agent skills in the workspace, it is possible to have a dedicated set of AI enhancements per project that are checked in the repository.

Further information can be found in Using the AI Features in the Theia IDE as an End User.

I will not go into details of every possible customization. But as an example and comparison to the previous programmatically registered Custom Agent, we will create a prompt, a custom agent and an agent skill, each able to achieve the same result.

Prompt Fragments

Prompt Fragments are used to define reusable prompts to execute reusable development tasks. Prompt Fragment files are stored in the .prompts folder with the default settings. They are similar to Visual Studio Code Copilot Prompt Files.

Prompt Fragments can be used by using the special variable #prompt:promptFragmentID. It does not support any additional arguments.

Start the Theia browser application
Open the Theia browser application on http://localhost:3000
Ensure that you have a workspace open otherwise open a folder somewhere (e.g. /home/node/example)
Create a new folder .prompts in your workspace
Create a new file harley.prompttemplate in that folder

Add the following content

---
name: Harley Quinn
description: Tell a joke as the girlfriend of the Joker
---

You are Harley Quinn, the girlfriend of the Joker, who is the arch enemy of Batman.
To attack Batman, you tell a joke that is so funny, it distracts him from his mission.

To keep the distraction going on, write the joke to a file. Use ~jokeFileCreator to write the joke to a file.
If the user does not provide a path, create a new folder "bat-jokes" in the current workspace folder and store the file in that folder.
Choose a filename that is related to the joke itself.

Test the Prompt Fragment with the following chat message in the AI Chat
```
@Universal #prompt:harley joke about batgirl
```

Slash Commands

Slash Commands are basically a way to execute a Prompt Fragment in a more intuitive way. Configuring a Prompt Fragment as a Slash Command makes them feel even more like using Prompt Files in Visual Studio Code Copilot.

By configuring a Prompt Fragment as a Slash Command you can call the prompt via /commandname and don’t need to use the #prompt:promptFragmentID variable. Additionally you can pass arguments to a Slash Command that can be used in the prompt via placeholders ($ARGUMENTS for all arguments in a single string, $1,$2,$3 for the individual argument by position). Note that the commandAgents header is used to limit the usage of the Slash Command to specific agents, while in Visual Studio Code Prompt Files the agent header is used to specify the agent that is used to execute the prompt.

Open the file .prompts/harley.prompttemplate in your workspace
Change the content by adding the necessary metadata to the Frontmatter block

Modify the prompt to tell a joke about the person passed as first argument

---
name: Harley Quinn
description: Tell a joke as the girlfriend of the Joker
isCommand: true
commandName: harley
commandDescription: Tell a joke and write it to a file
commandArgumentHint: The person to tell a joke about
commandAgents:
  - Universal
---

You are Harley Quinn, the girlfriend of the Joker, who is the arch enemy of Batman.
To attack Batman, you tell a joke about $1 that is so funny, it distracts him from his mission.

To keep the distraction going on, write the joke to a file. Use ~jokeFileCreator to write the joke to a file.
If the user does not provide a path, create a new folder "bat-jokes" in the current workspace folder and store the file in that folder.
Choose a filename that is related to the joke itself.

Test the Prompt Fragment by using the Slash Command in the AI Chat like this
```
@Universal /harley batgirl
```

As mentioned before, the creation of a Prompt Fragment and configure it as a Slash Command is similar to the creation and usage of a prompt file in Visual Studio Code as explained in Extending Copilot in Visual Studio Code - Further Customizations.

Custom Agents

As a user you can create a Custom Agent in Theia via a configuration file. Dependent on the available tools, the integration into the user interface is limited compared to Implementing a Custom Agent, as you have no access to the Theia API of course.

Custom Agents are used to create a specialist assistant for specific tasks that can be used in the chat for planning or research or to define specialized workflows. Custom Agents are stored in a .prompts/customAgents.yml file with the default settings. They are similar to Visual Studio Code Copilot Custom Agents.

Start the Theia browser application
Open the Theia browser application on http://localhost:3000
Ensure that you have a workspace open otherwise open a folder somewhere (e.g. /home/node/example)
Open the AI Configuration via Menu -> View -> AI Configuration
Switch to the Agents tab
Click on Add Custom Agent
Select the .prompts folder of the current workspace
Verify that a .prompts folder is generated in your workspace that contains a customAgents.yml file
Define a custom agent by defining the following information
- id: A unique identifier for the agent.
- name: The display name of the agent.
- description: A brief explanation of what the agent does.
- prompt: The default prompt that the agent will use for processing requests.
- defaultLLM: The language model used by default.
- showInChat: Whether the agent should be shown in the chat UI. This one is optional and defaults to true.

Replace the content of the customAgents.yml with the following snippet

- id: Blog
  name: Blog
  description: This agent provides a list of blog posts related to VS Code and Theia written by Dirk Fauth.
  prompt: >-

    You are an agent that helps the developer by providing links to blog posts about VS Code and Theia written by Dirk Fauth.

    To provide the necessary links execute the following steps:
    1. Fetch the publications of Dirk Fauth in the gists of fipro78. Use ~{mcp_github_list_gists} to find the correct gist.
    2. Use ~{mcp_fetch_fetch} to fetch the content of the gists with a max-length parameter of 15000.
    3. Filter the found links for information about VS Code or Theia
    4. Provide a list of links to the blog posts about VS Code or Theia

  defaultLLM: default/universal
  showInChat: true

Test the new Custom Agent
- Open the AI Configuration via Menu -> View -> AI Configuration
- Switch to the MCP Servers tab
- Ensure that the fetch MCP server and the github MCP server configured for the gists tools are available and started
- Open the AI Chat and enter the following prompt
```
@Blog show me the list
```
- Verify the result in the chat response

The creation of a Custom Agent in Theia via configuration file is similar to creating a Custom Agent in Visual Studio Code.

Agent-to-Agent Delegation (function)

The tasks that can be performed by AI agents are getting more and more complicated when they are used to solve complex tasks. Such complex tasks typically contain repetitive tasks that can be useful for multiple scenarios. And like in all programming languages, you usually want to modularize and reuse such tasks instead of define them over and over again. In terms of agents this means to create agents for specialized tasks and then tell the more complex agents to call those specialized agents to solve a specific task. In Theia AI this can be done by using the Agent-to-Agent Delegation, either in the prompt via a dedicated delegate function, or programmatically using the ChatAgentService. The programmatical approach was already shown in Agent-to-Agent Delegation (programmatically). The following section describes the Agent-to-Agent Delegation function that can be used in prompts.

Run the Theia browser application
Open the Theia browser application on http://localhost:3000
Ensure that you have a workspace open otherwise open a folder somewhere (e.g. /home/node/example)
Open the AI Configuration via Menu -> View -> AI Configuration
Switch to the Agents tab
Click on Add Custom Agent
Alternatively simply open the .prompts/customAgents.yaml file created before

Add a new FileWriter agent that uses the Theia built-in Tool Function writeFileContent to persist content to a file

- id: FileWriter
  name: FileWriter
  description: This is an agent that is able to persist content into a file in the workspace.
  prompt: >-

    You are an agent that operates in the current workspace of the Theia IDE.
    You are able to persist the provided content into a file by using ~{writeFileContent}.

  defaultLLM: default/universal
  showInChat: true

Add a new step to the Blog agent that delegates to the new FileWriter agent to persist the result by using the delegateToAgent Tool Function

- id: Blog
  name: Blog
  description: This agent provides a list of blog posts related to VS Code and Theia written by Dirk Fauth.
  prompt: >-

    You are an agent that helps the developer by providing links to blog posts about VS Code and Theia written by Dirk Fauth.

    To provide the necessary links execute the following steps:
    1. Fetch the publications of Dirk Fauth in the gists of fipro78. Use ~{mcp_github_list_gists} to find the correct gist.
    2. Use ~{mcp_fetch_fetch} to fetch the content of the gists with a max-length parameter of 15000.
    3. Filter the found links for information about VS Code or Theia
    4. Provide a list of links to the blog posts about VS Code or Theia
    5. Persist the result by delegating to `FileWriter` via ~{delegateToAgent} and write to the links folder in a file named fauth.html

  defaultLLM: default/universal
  showInChat: true

Open the AI Chat and enter the following prompt
```
@Blog show me the list
```
Verify that at the end the new FileWriter agent is called to persist the result and created the file links/fauth.html

The delegateToAgent function is a very nice and powerful way to delegate tasks from one agent to another by using a prompt to create multi-agent-workflows.

Agent Skills

Agent Skills are used to create reusable capabilities that work across different AI tools. They can include scripts, examples, or other resources alongside instructions. You can define specialized workflows like testing, debugging, or deployment processes by using Agent Skills. Project skills can be stored in the folder .prompts/skills/. Personal skills can be stored in the user home in the folder ~/.theia/skills/.

Agent Skills can be used directly as a Slash Command in the chat, where the name of the skill is used as command.

Note:
The support for Agent Skills was introduced with Theia 1.68.0. It is still in alpha, which means it is target to changes and does not yet work reliably as you can see for example via this ticket.

Start the Theia browser application
Open the Theia browser application on http://localhost:3000
Ensure that you have a workspace open otherwise open a folder somewhere (e.g. /home/node/example)
Create a new folder skills in the folder .prompts in your workspace
Create a new folder blog-link-extraction in the previously created .prompts/skills folder

Create the SKILL.md file in that folder

Add the following content to the SKILL.md file

---
name: blog-link-extraction
description: This skill provides a collection of links about VSCode or Theia from blog posts written by Dirk Fauth. Use this when asked for resources about VSCode or Theia, or when asked to find blog posts by Dirk Fauth.
---

# Blog Link Extraction Skill

This skill is designed to extract links from blog posts written by Dirk Fauth about VSCode or Theia. It first collects relevant blog posts from Dirk Fauth's gists and then extracts and filters the links contained within those blog posts to provide a structured list of resources related to VSCode or Theia.

## Process Overview

1. **Define the Extraction Goal**: Identify the specific information to be extracted (e.g., links to blog posts about VSCode or Theia).
2. **Blog Collection**: Fetch a list of relevant blog posts from a specified data source (e.g., GitHub gists).
3. **Link Extraction**: For each blog post, extract outbound links and filter them based on relevance to the topic. Perform this step without user interaction to provide a complete result set.
4. **Output**: Provide a structured list grouped by source blog post, with deterministic ordering.

## Execution Rules

1. Run this workflow end-to-end without asking the user for intermediate confirmations.
2. Preferred tools are ~{mcp_github_list_gists} and ~{mcp_fetch_fetch}. If those exact names are unavailable, use equivalent tools that provide the same capability.
3. On fetch failures, retry once. If the second attempt fails, continue with remaining items and report the skipped URL in the final output.
4. If fetched content appears truncated, fetch additional chunks (for example via start index or pagination) until no additional content is returned.

## Blog Collection

1. List gists for user `fipro78`.
2. Select gist files whose filename contains `publications` (case-insensitive).
3. If multiple matches exist, choose files from the most recently updated gist first.
4. Fetch the selected gist content with max length `25000`; if needed, fetch additional chunks until complete.
5. Extract candidate blog post URLs.
6. Keep only blog posts relevant to the requested topic (default topic: VSCode or Theia).
7. De-duplicate URLs and produce the final blog post list.

## Link Extraction

1. Fetch each blog post with max length `25000`; if needed, continue fetching additional chunks until complete.
2. Extract outbound links from the blog post.
3. Exclude non-http(s) links and non-content protocols (`mailto:`, `javascript:`, `tel:`).
4. Filter links for relevance using topic keywords from surrounding context. For VSCode/Theia, use keywords such as: `vscode`, `visual studio code`, `theia`, `eclipse theia`, `extension`, `webview`, `copilot`.
5. De-duplicate links per blog post.
6. Determine display name for each link:

- Use anchor text when available.
- Otherwise use the URL.

7. Sort links alphabetically by display name within each blog post.

## Example Workflow

1. A user asks for resources about VSCode or Theia.
2. The blog collection process fetches the relevant blog posts from Dirk Fauth's gists.
3. For each relevant blog post, the link extraction process reads the post, extracts outbound links, filters for relevance, and removes duplicates without user interaction.
4. The final output is grouped by blog post, with links presented using anchor text when available, and sorted alphabetically by link name within each blog post.

## Result

The final output is an aggregated collection grouped by blog post. Blog posts are ordered alphabetically by title (or URL if no title is available). Links inside each blog post are ordered alphabetically by link display name.

### Example Result

- [Blog Post 1](http://example.com/blog1):
  - [Link 1](http://example.com/link1) - Anchor Text 1
  - [Link 2](http://example.com/link2) - Anchor Text 2
- [Blog Post 2](http://example.com/blog2):
  - [Link 3](http://example.com/link3) - Anchor Text 3
  - [Link 4](http://example.com/link4) - Anchor Text 4

## Guidelines

- Ensure that the links are relevant to the topic of VSCode or Theia.
- Avoid including duplicate links or links that are not relevant to the topic.
- Provide clear and concise output that is easy to understand and navigate.
- Use the anchor text as the name of the link when available, and use the URL as the name of the link when anchor text is not available.
- Order links alphabetically by name within each blog post section.
- Ensure that the output is structured in a way that clearly indicates which links are associated with which blog posts.
- Include a short `Skipped URLs` section when any blog post could not be fetched after retry.

Use the Agent Skill by using it as a slash command to call it directly
- Enter a prompt similar to the following to the chat: @Universal /blog-link-extraction links about theia
  You will notice that it loads the skill, but it does not execute it directly.
- Enter something like process or execute to the chat to start the skill processing
  You will get a message that the required tools are not available. This is because there is currently an issue in the loading and processing of Agent Skills.
- Open the Generic Capabilities panel
  - Select the necessary MCP tools (fetch/fetch and github/list_gists)
  - Click on Save
  Note:
  This will configure the Generic Capabilities for the @Universal agent. This affects the usage of the agent in general. So you probably want to reset this later, to have the agent work as expected again. For this open the settings.json and remove the configuration for ai-features.agentSettings/Universal.
- Enter something like process or execute again to the chat to start the skill processing. After that the processing starts as described in the skill.

Note:
In Theia 1.70.0 the automatic discovery of skills is not working. Also the automatic execution and the tool calls are not working. As the Agent Skill support is currently in alpha state, this will hopefully fixed soon.

Further information about Agent Skills:

Use Visual Studio Code Copilot Extension in Theia

If you read my previous articles, you might wonder if you could implement a Visual Studio Code Copilot Extension and use it in Theia, as Theia is in general compatible with Visual Studio Code Extensions. If you did not read my previous articles and you are interested in that topic, have a look at Getting Started with Eclipse Theia - Theia - Visual Studio Code Extension.

As described above, there is some kind of a mapping between the AI contributions you can provide in a Visual Studio Code Copilot Extension and a Theia AI Extension. At the time writing this article, the @theia/plugin-ext extension only supports the mapping of programmatically registered MCP servers via McpServerDefinitionProvider to Theia MCPServerDescriptions. The Language Model Tools and the Chat Participants are not supported and therefore will simply not be available in a Theia application.

Further Information

There are several blog posts, tutorials and videos available related to Theia AI. The following list contains some links, but is of course not complete and probably also not up-to-date at the time you are reading this blog post.

Conclusion

In this comprehensive tutorial, we explored the extensive AI capabilities available in Eclipse Theia, focusing on how developers can implement and extend AI features in their Theia applications. We covered three main approaches to enhance Theia’s AI functionality:

Tool Functions provide deep integration with Theia’s APIs, allowing you to create domain-specific capabilities that can interact directly with the workspace, file system, and other IDE features. While Theia already includes several built-in tools, custom Tool Functions enable specialized functionality tailored to your specific development needs.

MCP (Model Context Protocol) Servers offer a standardized way to connect AI applications with external tools and data sources. We demonstrated both manual configuration via settings.json and programmatic registration through Theia extensions, covering local servers (stdio transport), remote servers, and authentication scenarios using various methods including PATs and OAuth.

Custom Agents create specialized AI assistants with domain-specific expertise that can be integrated throughout the Theia IDE. We explored how to implement agents programmatically with advanced features like prompt variants, agent-specific variables, and agent-to-agent delegation. Custom Agents excel when you need specialized workflows, deep Theia integration, or the ability to distribute AI capabilities as part of your Theia-based application.

We also explored configuration-based approaches like defining custom agents via YAML files, which enable users and teams to create specialized workflows without coding, and the powerful concept of agent-to-agent delegation for building sophisticated multi-agent workflows.

The key takeaway is that Theia AI provides a comprehensive and flexible framework for AI integration that goes beyond simple chat interfaces. Whether you’re building an AI-native IDE, adding intelligent assistants for specialized domains, or creating complex multi-agent workflows, Theia AI offers the building blocks needed to create sophisticated AI experiences.

Compared to Visual Studio Code’s Copilot extension model, Theia AI provides more flexibility in how AI features can be integrated throughout the IDE, native support for MCP servers, and extensive customization options through both programmatic APIs and configuration files. While VS Code Copilot extensions can be partially used in Theia (currently limited to MCP server definitions), native Theia AI extensions offer deeper integration and more capabilities.

The complete source code and examples from this tutorial are available in my GitHub repository, providing a practical foundation for building your own AI-powered Theia applications.

Whether you’re looking to enhance developer productivity with domain-specific AI tools, create specialized development workflows, or build an entirely AI-native development environment, this tutorial provides the essential building blocks to get started with Theia AI.

Extending Copilot in Visual Studio Code

2025-10-22T00:00:00+00:00

In this tutorial I will explain how to extend Visual Studio Code with a customized AI experience. By creating a Visual Studio Code Copilot Extension, we will contribute tools, MCP servers and chat participants, to provide AI features with domain expert know-how.

Obviously we will use and extend Copilot to achieve this. There are also other Visual Studio Code extensions to integrate AI in Visual Studio Code, but Copilot is the most prominent integration and there are several tutorials available I will refer to. This way it is easier to get started with those kind of extensions.

The article AI extensibility in VS Code gives an overview of the AI extensibility options in Visual Studio Code. In this tutorial we will

create a custom Language Model Tool
configure and contribute MCP Server
create a custom Chat Participant

In first place this tutorial is about extending GitHub Copilot in Visual Studio code and not a tutorial about using it. If you are interested in that, have a look at Get started with GitHub Copilot in VS Code.

Prerequisites

To follow this tutorial you need the following tools and services:

Visual Studio Code >= 1.113.0
Copilot Extension
Copilot Account (e.g. GitHub Copilot Free)

Project Setup

As this tutorial is part of my Visual Studio Code Extension - Theia - Cookbook, I will use the Dev Container created with the Getting Started with Visual Studio Code Extension Development.

Note:
If you are familiar with setting up a new Visual Studio Code Extension project or you don’t want to use the Cookbook sources and the Dev Container setup defined there as a starting point, you can create the project setup yourself, skip the following section and directly move on to Language Model Tool.

Clone the Visual Studio Code Extension - Theia - Cookbook GitHub Repository from the theia_getting_started branch. You can also use the getting_started branch if you are not interested in the Eclipse Theia related sources in the repository.
```
git clone -b theia_getting_started https://github.com/fipro78/vscode_theia_cookbook.git
```
Switch to the new folder and open Visual Studio Code
```
cd vscode_theia_cookbook
code .
```
When asked, select Reopen in Container to build and open the project in the Dev Container

Create the Visual Studio Code Extension project

Create a new Visual Studio Code Extension project:

Open a Terminal and execute the following command
```
yo code
```

Answer the questions of the wizard for example like shown below:

# ? What type of extension do you want to create? New Extension (TypeScript)
# ? What's the name of your extension? copilot-extension
# ? What's the identifier of your extension? copilot-extension
# ? What's the description of your extension? LEAVE BLANK
# ? Initialize a git repository? No
# ? Which bundler to use? unbundled
# ? Which package manager to use? npm

# ? Do you want to open the new folder with Visual Studio Code? Skip

A new subfolder copilot-extension will be created that contains the sources of the Visual Studio Code Extension.

The cookbook repository is setup as a mono-repo, therefore the Visual Studio Code Extension is kept in a subfolder. The following modifications are needed to include the newly created extension project to the setup:

Edit the .vscode/tasks.json

Add a task for watching the new copilot extension

{
  "label": "Copilot Extension Watch",
  "type": "shell",
  "command": "npm run watch",
  "problemMatcher": "$tsc-watch",
  "isBackground": true,
  "presentation": {
    "reveal": "never"
  },
  "group": {
    "kind": "build"
  },
  "options": {
    "cwd": "${workspaceFolder}/copilot-extension"
  }
},

Update the default build task Watch Extensions and add the new Copilot Extension Watch to the dependsOn configuration

{
  "label": "Watch Extensions",
  "group": {
    "kind": "build",
    "isDefault": true
  },
  "dependsOn": [
    "VS Code Extension Watch",
    "Angular Extension Watch",
    "React Extension Watch",
    "Copilot Extension Watch"
  ]
},

Edit the .vscode/launch.json and add the new project folder to the extensionDevelopmentPath and the outFiles

{
  "name": "Run Extension",
  "type": "extensionHost",
  "request": "launch",
  "args": [
    "--extensionDevelopmentPath=${workspaceFolder}/vscode-extension",
    "--extensionDevelopmentPath=${workspaceFolder}/angular-extension",
    "--extensionDevelopmentPath=${workspaceFolder}/react-extension",
    "--extensionDevelopmentPath=${workspaceFolder}/copilot-extension"
  ],
  "outFiles": [
    "${workspaceFolder}/vscode-extension/out/**/*.js",
    "${workspaceFolder}/angular-extension/dist/**/*.js",
    "${workspaceFolder}/react-extension/dist/**/*.js",
    "${workspaceFolder}/copilot-extension/dist/**/*.js"
  ],
  "preLaunchTask": "${defaultBuildTask}",
  "postDebugTask": "Terminate Tasks"
},

You can also add a new run configuration that only starts the new extension if you want to focus on the new extension:

{
  "name": "Run Copilot Extension",
  "type": "extensionHost",
  "request": "launch",
  "args": [
    "--extensionDevelopmentPath=${workspaceFolder}/copilot-extension"
  ],
  "outFiles": ["${workspaceFolder}/copilot-extension/out/**/*.js"],
  "preLaunchTask": "Copilot Extension Watch",
  "postDebugTask": "Terminate Tasks"
},

Note:
If you are not starting from a plain project setup and not using the Cookbook GitHub Repository, the postDebugTask will fail as it does not exist. In that case add it to the tasks.json as explained in Automatic Termination of Watch Tasks.

Delete the copilot-extension/.vscode folder
```
rm -rf copilot-extension/.vscode
```

To verify that the setup works, open the file copilot-extension/src/extension.ts and press F5 to start a new Visual Studio Code instance with the extension, open the Command Palette (CTRL + SHIFT + P) and search for Hello to run the command.

If you only want to start the new copilot-extension in the Extension Host, switch first to the Run and Debug view (CTRL + SHIFT + D) and select Run Copilot Extension in the dropdown.

Language Model Tool

Adding a Language Model Tool enables you to extend the functionality of a large language model (LLM) in the chat with domain-specific capabilities. This is also possible via specialized MCP Server which will be described later. The main difference between a Language Model Tool and a MCP Server is that a Language Model Tool can deeply integrate with Visual Studio Code by using the VS Code APIs, while MCP Server provide access to external tools that don’t need to access to the VS Code API.

Further details can be found in Language Model Tool API.

In this section we will create a Language Model Tool that creates a file in the current workspace that contains a joke as content.

Note:
Actually Visual Studio Code already contains built-in language model tools that are able to interact with the workspace. So the following implementation is not necessary to achieve the result. It is intended as an example how the implementation of a Language Model Tool could look like.

Open the file copilot-extension/package.json

Replace the contributes section with the following snippet:

"contributes": {
  "languageModelTools": [
    {
      "name": "chat-tools-joke",
      "displayName": "Joke File Creator",
      "toolReferenceName": "jokeFileCreator",
      "canBeReferencedInPrompt": true,
      "icon": "$(files)",
      "userDescription": "Create a file that contains a joke.",
      "modelDescription": "Create a file at the given path that contains a joke.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "The name of the folder in the workspace where the joke file should be created."
          },
          "filename": {
            "type": "string",
            "description": "The name of the jokefile that should be created."
          },
          "joke": {
            "type": "string",
            "description": "The joke content to be written in the joke file."
          }
        }
      }
    }
  ]
},

Create a new file copilot-extension/src/joke-file-creator.ts

Import the VS Code API
```
import * as vscode from "vscode";
```

Define an interface for the tool parameters that matches the inputSchema in the package.json

interface IJokeFileParameters {
  path: string;
  filename: string;
  joke: string;
}

Create a class that implements vscode.LanguageModelTool

export class JokeFileCreatorTool
  implements vscode.LanguageModelTool<IJokeFileParameters> {}

Add the following prepareInvocation() method to provide tool configuration messages.

prepareInvocation?(
    options: vscode.LanguageModelToolInvocationPrepareOptions<IJokeFileParameters>,
    token: vscode.CancellationToken
): vscode.ProviderResult<vscode.PreparedToolInvocation> {
    const confirmationMessages = {
    title: "Create a joke file",
    message: new vscode.MarkdownString(
        (options.input.path !== undefined && options.input.path !== "")
        ? `Create a joke file in ${options.input.path}?`
        : "Create a joke file in the workspace root?"
    ),
    };

    return {
    invocationMessage: "Create a joke file",
    confirmationMessages,
    };
}

Note:
If you return undefined, the generic confirmation message will be shown.

Add the following invoke() method which is called when the language model tool is invoked while processing a chat prompt.

async invoke(
    options: vscode.LanguageModelToolInvocationOptions<IJokeFileParameters>,
    token: vscode.CancellationToken
): Promise<vscode.LanguageModelToolResult | null | undefined> {
    const params = options.input;
    const result = await this.createJokeFile(
        params.path,
        params.filename,
        params.joke
    );
    if (result.length > 0) {
        return new vscode.LanguageModelToolResult([
            new vscode.LanguageModelTextPart(result),
    ]);
    } else {
        return new vscode.LanguageModelToolResult([
            new vscode.LanguageModelTextPart(`Joke file creation failed`),
    ]);
    }
}

public async createJokeFile(
    path: string,
    filename: string,
    jokeContent: string
): Promise<string> {
    const workspaceFolders = vscode.workspace.workspaceFolders;
    if (!workspaceFolders) {
        vscode.window.showErrorMessage("No workspace folder open.");
        return "";
    }

    let folder = workspaceFolders[0];
    let pathUri = vscode.Uri.joinPath(folder.uri, path);

    try {
        await vscode.workspace.fs.stat(pathUri);
    } catch {
        vscode.workspace.fs.createDirectory(pathUri);
    }

    const fileUri = vscode.Uri.joinPath(pathUri, filename);

    try {
        await vscode.workspace.fs.writeFile(
            fileUri,
            Buffer.from(jokeContent, "utf8")
        );
        return `Joke file "${fileUri}" created!`;
    } catch (error) {
        return `Failed to create joke file: ${error}`;
    }
}

Change copilot-extension/src/extension.ts

Replace the existing example code with the following snippet

// The module 'vscode' contains the VS Code extensibility API
// Import the module and reference it with the alias vscode in your code below
import * as vscode from "vscode";
import { JokeFileCreatorTool } from "./joke-file-creator";

// This method is called when your extension is activated
// Your extension is activated the very first time the command is executed
export function activate(context: vscode.ExtensionContext) {
  // This line of code will only be executed once when your extension is activated
  console.log(
    'Congratulations, your extension "copilot-extension" is now active!'
  );

  // Register our custom joke creator language model tool
  // Use the name property of the tool configured in the package.json
  context.subscriptions.push(
    vscode.lm.registerTool("chat-tools-joke", new JokeFileCreatorTool())
  );
}

// This method is called when your extension is deactivated
export function deactivate() {}

If everything is correctly in place, you can verify the Language Model Tool like this:

You need an open workspace to make the Language Model Tool work. To be able to open a workspace in the Extension Host create a folder example in the home directory of the node user in the Dev Container
```
mkdir ~/example
```
Press F5 to start a new Visual Studio Code instance with the extension
Open a folder via File -> Open Folder… and select the created example folder
Open the Copilot Chat Editor if it is not open yet
Enter the following input to the Copilot Chat to execute the contributed Language Model Tool
```
#jokeFileCreator create a file that contains a joke in the folder test
```
In the chat you will see that a prompt comes up that asks you whether to Allow the execution of the tool or if you want to Skip it. Click on Allow or even select for example Allow in this Workspace from the dropdown so you don’t need to allow the execution of the tool in the future.
Check the Input and Output of the tool in the chat and ensure that the file was created in the correct place with the desired content.

MCP Server

MCP, or Model Context Protocol, is an open protocol to standardize how AI applications connect with external tools and data sources. MCP servers can offer resources, prompts and tools that can be used by a client.

In this section we will cover how to add MCP servers to Visual Studio Code and the usage of tools.

There are basically two types of MCP servers:

Local MCP servers (stdio transport)
A local MCP server runs on the same machine as the MCP client and is used to access local resources like files or run local scripts. Local servers are essential for tasks that require accessing local files or data that is not available remotely.
Remote MCP servers (streamable HTTP or server-sent events)

There are several ways to add MCP servers to Visual Studio Code:

Directly install them e.g. via a website like MCP Servers for agent mode
This will create a mcp.json file in C:\Users\\AppData\Roaming\Code\User with the configuration of the MCP server
Via mcp.json server configuration file, e.g. in the workspace in .vscode/mcp.json
Programmatically via a Visual Studio Code Extension

It is also possible to configure MCP servers in a Dev Container via devcontainer.json. This is described in Dev Container support.

In the following section I will describe how to manually configure MCP servers via mcp.json and programmatically via Visual Studio Code extension.

We will install

the Filesystem MCP Server as a local MCP Server
the Fetch MCP Server as a remote MCP Server
the GitHub MCP Server as a remote MCP Server that requires an authorization

Add MCP server via mcp.json

In the following section we will add MCP servers via mcp.json file. This can be done in the Visual Studio Code instance that you use to follow this tutorial (not the Extension Host for running the created extension).

Local MCP Server

Create a new file .vscode/mcp.json

Add the following content to configure the filesystem server as local MCP server.

{
  "servers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"]
    }
  },
  "inputs": []
}

Note:
The Filesystem MCP Server supports Roots and Visual Studio Code sets the roots to the workspace directory. You can set additional allowed directories via args, but they will be replaced by the roots provided by Visual Studio Code. You can therefore skip setting allowed directories as they will be replaced automatically with the workspace folder.

In the editor you will see actions provided as CodeLens that let you interact with the server. Click on Start to start the filesystem MCP server.

This will start the server and discover the capabilities and tools provided by the server. These tools can then be used in the Copilot Chat in agent mode.
Test if the configuration works
- Ensure to have the Agent mode enabled.
- Enter the following to the Copilot Chat
```
list allowed directories
```
- When asked if the tool list_allowed_directories should be executed, select Allow
- You should now see that the list_allowed_directories tool from the filesystem (MCP Server) is executed to solve your request.

Remote MCP Server

Add the following content to the mcp.json to configure the fetch server as remote MCP server.
```
"fetch": {
  "url": "https://remote.mcpservers.org/fetch/mcp",
  "type": "http"
}
```
Note:
Visual Studio Code already provides fetch as a built-in tool. So this is actually not needed for usage, but an example to show a simple remote MCP server configuration. For testing that the added remote fetch MCP server works
- Click on Configure Tools…
- Disable the built-in fetch tool
- Enable the added MCP server fetch in the configuration
- Click on OK to apply the changes
Start the fetch MCP server via Codelens
Test if the configuration works by entering the following to the Copilot Chat
```
fetch the content from https://eclipse.dev/nattable
```
When asked if the tool fetch - fetch (MCP Server) should be executed, select Allow
You should now see that the fetch tool from the fetch (MCP Server) is executed to solve your request.

Remote MCP Server with authorization

Most of the remote MCP servers require an authorization in order to work. Although of course possible, you typically don’t want to write the token in plain text into the mcp.json file, as you don’t want to share your personal token with other project members. Instead you can deal with the authorization token the following ways:

use input variables
use environment variables

To demonstrate this we use the GitHub MCP Server with a PAT (Personal Access Token). This is also described in Using the GitHub MCP Server.

Create a Personal Access Token as described in Creating a personal access token (classic)
Use repo as scope

You can use the GitHub MCP server locally via Docker. To make this work in a Dev Container you need the docker-in-docker feature added to the devcontainer.json.

"features": {
  "ghcr.io/devcontainers/features/docker-in-docker:2": {},
}

The local GitHub MCP server can then be configured in the mcp.json file like this:

"github": {
  "command": "docker",
  "args": [
    "run",
    "-i",
    "--rm",
    "-e",
    "GITHUB_PERSONAL_ACCESS_TOKEN",
    "ghcr.io/github/github-mcp-server"
  ],
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}"
  }
}

Note the ${input:github_token} in the env section. The input parameter needs to be configured in the following way in the inputs section of the mcp.json file.

"inputs": [
  {
    "type": "promptString",
    "id": "github_token",
    "description": "GitHub Personal Access Token",
    "password": true
  }
]

Inputs will be prompted on first server start and then stored securely by Visual Studio Code.

Further information about input variables can be found here:

Instead of using the GitHub MCP server locally, you can directly use the GitHub hosted server as explained in A practical guide on how to use the GitHub MCP server

"github": {
  "url": "https://api.githubcopilot.com/mcp/",
  "type": "http",
  "headers": {
    "Authorization": "Bearer ${input:github_token}"
  }
}

Instead of using an input, you can also use an environment variable as explained in Environment variables

"github": {
  "url": "https://api.githubcopilot.com/mcp/",
  "type": "http",
  "headers": {
    "Authorization": "Bearer ${env:GITHUB_TOKEN}"
  }
}

By using ${env:GITHUB_TOKEN} instead of the input variable the environment variable with the name GITHUB_TOKEN will be used for setting the authorization token.

Once the environment variable is set in your system and available, update the .devcontainer/devcontainer.json file and add the following configuration as described in Visual Studio Code - Environment variables

"remoteEnv": {
  "GITHUB_TOKEN": "${localEnv:GITHUB_TOKEN}"
},

Instead of using the Bearer token for authorization, GitHub recommends the usage of OAuth for the GitHub MCP server. In that case simply drop the headers section and you will be asked for the authentication on starting the server.

"github": {
  "url": "https://api.githubcopilot.com/mcp/",
  "type": "http"
}

"github_gists": {
  "url": "https://api.githubcopilot.com/mcp/x/gists",
  "type": "http"
}

or by setting the optional header X-MCP-Toolsets

"github": {
  "url": "https://api.githubcopilot.com/mcp/",
  "type": "http",
  "headers": {
    "X-MCP-Toolsets": "gists"
  }
}

Further details about this are available in Remote GitHub MCP Server.

Test if the GitHub MCP Server configuration works

Start the server
Ensure to have the Agent mode activated in the chat

Enter the following in the chat

fetch the publications written by Dirk Fauth. Inspect the gists of fipro78 and provide the links to blog posts about VS Code and Eclipse Theia in the chat that are extracted from a related gists file

Note:
The default .gitignore or at least the .gitignore in the cookbook repository by default ignores the whole .vscode folder and excludes the default settings JSON files. With this configuration the mcp.json file will be ignored. This makes sense to avoid that by accident configurations with hard coded authorization tokens are added to the repository. If you are sure that no private data is contained in the mcp.json file, e.g. because you use the OAuth mechanism for the GitHub MCP server, you can exclude the mcp.json file from the ignore list by adding the following line to the .gitignore in the project root:

!.vscode/mcp.json

Add MCP server programmatically via VS Code Extension

You can also register MCP server programmatically via a Visual Studio Code extension. This way you can for example bundle AI extensions like chat participants or the direct usage of the Language Model API with the registration of MCP servers that are needed for the provided functionality.

Open the file copilot-extension/package.json
- Extend the contributes section with the following mcpServerDefinitionProviders
```
"contributes": {
  "mcpServerDefinitionProviders": [
    {
      "id": "custom-mcp",
      "label": "Custom MCP Server Provider"
    }
  ]
},
```
- To ensure that the MCP servers are registered automatically, you need to configure the activationEvents accordingly, e.g. onStartupFinished. Otherwise the extension is not activated and the MCP servers are not registered. Alternatively you can of course use another activation event based on some other constraint.
```
"activationEvents": [
  "onStartupFinished"
],
```
Open the file copilot-extension/src/extension.ts
- Register the McpServerDefinitionProvider in the activate() method.
```
const didChangeEmitter = new vscode.EventEmitter<void>();

context.subscriptions.push(
  vscode.lm.registerMcpServerDefinitionProvider("custom-mcp", {
    onDidChangeMcpServerDefinitions: didChangeEmitter.event,
    provideMcpServerDefinitions: async () => {
      let servers: vscode.McpServerDefinition[] = [];

      // add the servers

      return servers;
    },
  })
);
```
- Add a local MCP server by using vscode.McpStdioServerDefinition (right after the // add the servers comment)
```
servers.push(
  new vscode.McpStdioServerDefinition("filesystem", "npx", [
    "-y",
    "@modelcontextprotocol/server-filesystem",
    "/home/node/example",
  ])
);
```
- Add a remote MCP server by using vscode.McpHttpServerDefinition
```
servers.push(
  new vscode.McpHttpServerDefinition(
    "fetch",
    vscode.Uri.parse("https://remote.mcpservers.org/fetch/mcp")
  )
);
```
There are some flaws related to programmatically registered MCP servers:
- There is no programmatical way to autostart a MCP server.
- They do not show up in the MCP Servers section of the Extensions view.
- They don’t get roots set.
The resources and tools provided by a MCP server are loaded and cached on the first start. But because of the above reasons, a programmatically registered MCP servers will not be started automatically and needs a user interaction for the first start. The only way to manage programmatically registered MCP servers manually is to use the command MCP: List Servers command from the Command Palette (F1) to view the list of configured MCP servers.
- Command Palette (F1) -> MCP: List Servers -> select the server to start -> Start Server
There is also a configuration Chat > MCP: Autostart available that lets a user define an autostart behavior for MCP servers.
- Command Palette (F1) -> Preferences: Open User Settings -> search for autostart -> Chat > MCP: Autostart - set the value to newAndOutdated ("chat.mcp.autostart": "newAndOutdated" in the settings JSON).
With this setting even programmatically registered MCP servers can be autostarted. But as for example the roots are not set by Visual Studio Code to programmatically registered MCP servers, the filesystem MCP server can be configured to access an directory outside the workspace via the allowed directories parameter, in the above configuration /home/node/example.
Run the extension by pressing F5
- Check that the MCP servers are started, either manually via command palette or have the chat.mcp.autostart setting enabled.
- Test if the programmatically registered MCP server works, e.g. by entering the following into the chat
```
show me the directory tree of the allowed directories
```

If you need to pass an authorization token via header like the PAT for the GitHub MCP server, you can for example read an environment variable or hard-code it and pass the Authorization header

let token = process.env.GITHUB_TOKEN;
servers.push(
  new vscode.McpHttpServerDefinition(
    "github",
    vscode.Uri.parse("https://api.githubcopilot.com/mcp/"),
    {
      Authorization: `Bearer ${token}`,
    }
  )
);

Alternatively it is possible to get the token interactively by implementing resolveMcpServerDefinition() of the McpServerDefinitionProvider

export function activate(context: vscode.ExtensionContext) {
  const didChangeEmitter = new vscode.EventEmitter<void>();

  context.subscriptions.push(
    vscode.lm.registerMcpServerDefinitionProvider("etas-mcp", {
      onDidChangeMcpServerDefinitions: didChangeEmitter.event,
      provideMcpServerDefinitions: async () => {
        let servers: vscode.McpServerDefinition[] = [];

        // add the servers
        servers.push(
          new vscode.McpStdioServerDefinition("filesystem", "npx", [
            "-y",
            "@modelcontextprotocol/server-filesystem",
            "/home/node/example",
          ])
        );

        servers.push(
          new vscode.McpHttpServerDefinition(
            "fetch",
            vscode.Uri.parse("https://remote.mcpservers.org/fetch/mcp")
          )
        );

        servers.push(
          new vscode.McpHttpServerDefinition(
            "github",
            vscode.Uri.parse("https://api.githubcopilot.com/mcp/")
          )
        );

        return servers;
      },
      resolveMcpServerDefinition: async (
        server: vscode.McpServerDefinition
      ) => {
        if (server.label === "github") {
          // First check if token is available in environment variable
          let token = process.env.GITHUB_TOKEN;

          // If no environment variable, ask for token from user
          if (!token) {
            token = await vscode.window.showInputBox({
              prompt: `Enter the authorization token for ${server.label}`,
              password: true,
              placeHolder: `Enter your authorization token for ${server.label} ...`,
            });

            if (token) {
              // If user provided a token, save it to environment variable for future use
              process.env.GITHUB_TOKEN = token;
              console.log(`GITHUB_TOKEN saved to environment for future use`);
            }
          } else {
            console.log(
              `Using GITHUB_TOKEN from environment for ${server.label}`
            );
          }

          if (!token) {
            vscode.window.showErrorMessage(
              `Authorization token is required for ${server.label}`
            );
            return undefined; // Don't start the server without a token
          }

          // Update the server headers with the new token
          const updatedHeaders = {
            ...(server as any).headers,
            Authorization: `Bearer ${token}`,
          };

          (server as any).headers = updatedHeaders;
        }

        // Return undefined to indicate that the server should not be started or throw an error
        // If there is a pending tool call, the editor will cancel it and return an error message
        // to the language model.
        return server;
      },
    })
  );
}

Additional information about registering a MCP server programmatically is also provided here:

Note:
If you plan to use a Visual Studio Code extension that contributes mcpServerDefinitionProviders in a Theia application, you can not use a type check for vscode types, e.g. the statement if (server instanceof vscode.McpHttpServerDefinition) will not work in Theia, because Theia does not use the vscode types. In such a case you need a different check like if ((server as any).uri) which checks for the property instead of the type, or the name check as shown in the above example.

Further information about MCP in Visual Studio Code:

Chat Participant

With the implementation of a Chat Participant you can create an assistant to extend the chat with domain specific experts knowledge.

Chat Participants

are specialized AI assistants
work within VS Code’s chat system and can interact with VS Code APIs
can be distributed and deployed with an extension via marketplace, no need for additional installation mechanisms
can control the end-to-end user chat prompt and response

In the following section we will create a chat participant that is able to use one of the tools we created before.

We use the chat-extension-utils to implement tool calling in the chat participant. You can also implement the tool calling yourself to have more control over the tool calling process. Check the tool calling by using prompt-tsx example for an example on how to implement the tool calling yourself.

Install @vscode/chat-extension-utils to use tools in the chat participant
- Open a Terminal
- Switch to the folder copilot-extension
- Execute the following command
```
npm install @vscode/chat-extension-utils
```

Open the file copilot-extension/package.json

Extend the contributes section with the following chatParticipants

"contributes": {
  "chatParticipants": [
    {
      "id": "joker-sample.joker-participant",
      "name": "joker",
      "fullName": "The Joker",
      "description": "Let me tell you a joke!",
      "isSticky": true
    }
  ]
},

Open the file copilot-extension/src/extension.ts

Define the prompt to use

const JOKER_PROMPT = `You are the Joker, the arch enemy of Batman.
To attack Batman, you tell a joke that is so funny, it distracts him from his mission.
To keep the distraction going on, write the joke to a file.
If the user does not provide a path, create a new folder "bat-jokes" in the current workspace folder and store the file in that folder.`;

Import chat-extension-utils

import * as chatUtils from "@vscode/chat-extension-utils";

Extend the activate() method

Define the vscode.ChatRequestHandler request handler

const handler: vscode.ChatRequestHandler = async (
  request: vscode.ChatRequest,
  context: vscode.ChatContext,
  stream: vscode.ChatResponseStream,
  token: vscode.CancellationToken
) => {
  // Chat request handler implementation goes here
  try {
    const tools = vscode.lm.tools.filter(
      (tool) => tool.name === "chat-tools-joke"
    );

    const libResult = chatUtils.sendChatParticipantRequest(
      request,
      context,
      {
        prompt: JOKER_PROMPT,
        responseStreamOptions: {
          stream,
          references: true,
          responseText: true,
        },
        tools,
      },
      token
    );

    return await libResult.result;
  } catch (err) {
    console.log(`Error in chat request handler: ${err}`);
  }
};

const chatLibParticipant = vscode.chat.createChatParticipant(
  "joker-sample.joker-participant",
  handler
);
context.subscriptions.push(chatLibParticipant);

Test the implementation by starting the extension host via F5.
- Open the Copilot Chat and ask the joker chat participant for a joke by selecting him via @joker
```
@joker tell me a joke about batman
```
- Verify the chat response and check the generated file

Further information about chat participants can be found here

Further Customizations

Users can further customize the Copilot experience by configuring Instructions, Prompt Templates, Custom Agents and Agent Skills.

Instructions
Custom Instructions are used to define common guidelines for specific tasks and can be installed in the user profile or in the workspace .github/instructions
Prompts
Prompt Files are used to define reusable prompts to execute reusable development tasks and can be installed in the user profile or in the .github/prompts folder
Custom Agents
Custom Agents are used to create a specialist assistant for specific tasks that can be used in the chat for planning or research or to define specialized workflows. They can be installed in the user profile or in the workspace in the .github/agents folder
Agent Skills
Agent Skills are used to create reusable capabilities that work across different AI tools. They can include scripts, examples, or other resources alongside instructions. You can define specialized workflows like testing, debugging, or deployment processes by using Agent Skills. Project skills can be stored in the folders .github/skills/, .claude/skills/ or .agents/skills/. Personal skills can be stored in the user home in the folders ~/.copilot/skills/, ~/.claude/skills/ or ~/.agents/skills/.
Tool Sets
Tool Sets can be defined in a .jsonc file that is located in the user profile e.g. C:\Users\\AppData\Roaming\Code\User\prompts

By having the instructions, prompts, custom agents and agent skills in the workspace, it is possible to have dedicated instructions, prompts, custom agents and agent skills per project that are checked in the repository.

Further information can be found in Customize AI in Visual Studio Code.

I will not go into details of every possible customization. But as an example and comparison to the previous programmatically registered Chat Participant, we will create a prompt and a custom agent, each able to achieve the same result.

Prompt Files

Prompt Files are used to define reusable prompts to execute reusable development tasks and can be installed in the user profile or in the .github/prompts folder.

Prompt Files can be used by typing / followed by the prompt name in the chat input field. You can provide additional information as input variables via =.

Start the Extension Host by pressing F5
This is necessary because the jokeFileCreator language model tool is contributed by the developed Visual Studio Code Extension. If that tool is not needed or used, you can even try this in the Visual Studio Code instance in which you are developing.
Create a new Prompt File
- In the Copilot chat window, click the gear icon in the upper right corner (Open Customizations)
- Select Prompts in the Chat Customizations dialog side menu
- Open the dropdown for generating a new prompt and select New Prompt (Workspace)
- Enter the name harley
This creates the file .github/prompts/harley.prompt.md, which is directly opened in the Chat Customizations dialog.
- Add the following content to the file
```
---
agent: agent
tools: [undefined_publisher.copilot-extension/jokeFileCreator]
---

You are Harley Quinn, the girlfriend of the Joker, who is the arch enemy of Batman.
To attack Batman, you tell a joke that is so funny, it distracts him from his mission.

To keep the distraction going on, write the joke to a file.
If the user does not provide a path, create a new folder "bat-jokes" in the current workspace folder and store the file in that folder.
```
- Execute the prompt by pressing the play button in the editor title area.
- Execute the prompt by using it in the chat via slash command and pass additional information, e.g. /harley joke about robin

The prompt can be more specific by using input variables and mentioning the tools to be used at the correct position via the #tool: syntax.

Update the file .github/prompts/harley.prompt.md

Use the variable target to tell a joke about

Use the jokeFileCreator tool explicitly to create the file

---
agent: agent
tools: [undefined_publisher.copilot-extension/jokeFileCreator]
---

You are Harley Quinn, the girlfriend of the Joker, who is the arch enemy of Batman.
To attack Batman, you tell a joke about ${input:target} that is so funny, it distracts him from his mission.

To keep the distraction going on, write the joke to a file by using #tool:undefined_publisher.copilot-extension/jokeFileCreator
If the user does not provide a path, create a new folder "bat-jokes" in the current workspace folder and store the file in that folder.

Execute the prompt by using it in the chat via slash command and set the target input variable, e.g. /harley target=batgirl

Custom Agents

Create a new Custom Agent
- In the Copilot chat window, click the gear icon in the upper right corner (Open Customizations)
- Select Agents in the Chat Customizations dialog side menu
- Open the dropdown for generating a new agent and select New Agent (Workspace)
- Select .github as location for the new agent
- Enter the name joker
This creates the file .github/agents/joker.agent.md, which is directly opened in the Chat Customizations dialog.
- Add the following content to the file
```
---
description: "Creates a file with a joke to distract Batman."
tools: [undefined_publisher.copilot-extension/jokeFileCreator]
---

You are the Joker, the arch enemy of Batman.
To attack Batman, you tell a joke that is so funny, it distracts him from his mission.
To keep the distraction going on, write the joke to a file.
If the user does not provide a path, create a new folder "bat-jokes" in the current workspace folder and store the file in that folder.
```
- Use the custom agent by selecting it in the agents dropdown in the chat view and enter a prompt, e.g. joke about alfred

As you might notice, the results from the implemented Chat Participant are quite similar to those from the Prompt File or the Custom Agent. For this simple example that uses a Language Model Tool for file creation, there is no significant advantage to creating a Chat Participant, except for the ability to distribute it via a Visual Studio Code Extension. The real benefits of a Chat Participant become apparent when you need to deeply integrate with Visual Studio Code using the extension APIs.

The following table shows a basic comparison of Prompt Files, Custom Agents and Chat Participants:

	Prompt Files	Custom Agents	Chat Participants
Format	.promp.md file	.agent.md file	Implementation of `vscode.ChatRequestHandler`
Usage	slash command, e.g. /joker	select in agents dropdown	select via `@` in chat, e.g. @joker
Usage scenarios	Reusable development tasks	Specialized workflows with option to delegate task to other agents	Domain-specific tasks and workflows distributed via extension

Agent-to-Agent Delegation / Handoffs

Custom Agents can be used to create specialized workflows with multiple agents involved. In this section we will create two new Custom Agents where the first agent is retrieving some information and the second one will write it to a file. This excercise can be done in the development host and does not need to be executed in the debugging instance.

Ensure to have the GitHub MCP server configured in your workspace with gists tools enabled:
- Open the file .vscode/mcp.json
- Check that the following entry is available
```
"github": {
  "url": "https://api.githubcopilot.com/mcp/",
  "type": "http",
  "headers": {
    "X-MCP-Toolsets": "gists"
  }
}
```
Create a new Custom Agent that is able to write content to a file in the workspace by using the edit/createFile built-in tool of Visual Studio Code.
- In the Copilot chat window, click the gear icon in the upper right corner (Open Customizations)
- Select Agents in the Chat Customizations dialog side menu
- Open the dropdown for generating a new agent and select New Agent (Workspace)
- Select .github as location for the new agent
- Enter the name filewriter
This creates the file .github/agents/filewriter.agent.md, which is directly opened in the Chat Customizations dialog.
- Add the following content to the file
```
---
description: "This is an agent that is able to persist content into a file in the workspace."
tools: [edit/createFile]
---

You are an agent that operates in the current workspace of Visual Studio Code. You are able to persist the provided content into a file.
```
Create a new Custom Agent that is able to retrieve information from a gist.
- Switch back to the Agents overview page in the Chat Customizations dialog (e.g. by using the back arrow if the previous agent editor is still open or selecting the Agents entry in the side menu again)
- Open the dropdown for generating a new agent and select New Agent (Workspace)
- Select .github as location for the new agent
- Enter the name blog
This creates the file .github/agents/blog.agent.md, which is directly opened in the Chat Customizations dialog.
- Use the GitHub MCP tool github/list_gists to list the gists (remember to enable the gists toolset)
- Use the built-in web/fetch tool to fetch the content
- Use handoffs field in the frontmatter header to configure that the processing should be hand off to the filewriter agent we created before
- Add the following content to the file
```
---
description: "This agent provides a list of blog posts related to VS Code and Theia written by Dirk Fauth."
tools: [web/fetch, github/list_gists]
handoffs:
  - label: Persist Blog Links
    agent: filewriter
    prompt: Persist the given list of links by writing to the links folder in a file named fauth.html
    send: false
---

You are an agent that helps the developer by providing links to blog posts about VS Code and Theia written by Dirk Fauth.

To provide the necessary links execute the following steps:

1. Fetch the publications of Dirk Fauth in the gists of fipro78. Use #tool:github/list_gists to find the correct gist.
2. Use #tool:web/fetch to fetch the content of the gists with a max-length parameter of 15000.
3. Filter the found links for information about VS Code or Theia
4. Provide a list of links to the blog posts about VS Code or Theia
```
  Note:
  The tools are mentioned explicitly via the #tool: syntax to ensure that the correct tools are used without the need to determine which tool to use.
Use the Custom Agent blog by selecting it in the agents dropdown in the chat view and enter the prompt, e.g. show me the list
- You will be prompted to allow the execution of the fetch tool to ensure that there is no malicious code fetched
- Once the blog agent is done, you will be asked if you want to proceed with the next step
- If the next step is approved, the chat will contain the prompt defined in the handoffs section, and the filewriter agent will be selected in the agent dropdown
- After sending the pre-filled chat entry, the filewriter will execute its task and create the folder links with a file fauth.html in it
- You will then be asked whether to Keep or to Undo the file changes. Select Keep and check what the content of the file.

By setting the send field in the handoffs section to true you can avoid that you need to send the hand-off prompt manually and instead auto-submit the prompt. But you still will need to approve the next step.

Agent Skills

Create a new Agent Skill

In the Copilot chat window, click the gear icon in the upper right corner (Open Customizations)
Select Skills in the Chat Customizations dialog side menu
Open the dropdown for generating a new skill and select New Skill (Workspace)
Select .github as location for the new skill
Enter the name blog-link-extraction

This creates the folder .github/skills/blog-link-extraction that contains a SKILL.md file, which is directly opened in the Chat Customizations dialog.

Add the following content to the SKILL.md file

---
name: blog-link-extraction
description: This skill provides a collection of links about VSCode or Theia from blog posts written by Dirk Fauth. Use this when asked for resources about VSCode or Theia, or when asked to find blog posts by Dirk Fauth.
---

# Blog Link Extraction Skill

This skill is designed to extract links from blog posts written by Dirk Fauth about VSCode or Theia. It first collects relevant blog posts from Dirk Fauth's gists and then extracts and filters the links contained within those blog posts to provide a structured list of resources related to VSCode or Theia.

## Process Overview

1. **Define the Extraction Goal**: Identify the specific information to be extracted (e.g., links to blog posts about VSCode or Theia).
2. **Blog Collection**: Fetch a list of relevant blog posts from a specified data source (e.g., GitHub gists).
3. **Link Extraction**: For each blog post, extract outbound links and filter them based on relevance to the topic. Perform this step without user interaction to provide a complete result set.
4. **Output**: Provide a structured list grouped by source blog post, with deterministic ordering.

## Execution Rules

1. Run this workflow end-to-end without asking the user for intermediate confirmations.
2. Preferred tools are `github/list_gists` and `web/fetch`. If those exact names are unavailable, use equivalent tools that provide the same capability.
3. On fetch failures, retry once. If the second attempt fails, continue with remaining items and report the skipped URL in the final output.
4. If fetched content appears truncated, fetch additional chunks (for example via start index or pagination) until no additional content is returned.

## Blog Collection

1. List gists for user `fipro78`.
2. Select gist files whose filename contains `publications` (case-insensitive).
3. If multiple matches exist, choose files from the most recently updated gist first.
4. Fetch the selected gist content with max length `25000`; if needed, fetch additional chunks until complete.
5. Extract candidate blog post URLs.
6. Keep only blog posts relevant to the requested topic (default topic: VSCode or Theia).
7. De-duplicate URLs and produce the final blog post list.

## Link Extraction

1. Fetch each blog post with max length `25000`; if needed, continue fetching additional chunks until complete.
2. Extract outbound links from the blog post.
3. Exclude non-http(s) links and non-content protocols (`mailto:`, `javascript:`, `tel:`).
4. Filter links for relevance using topic keywords from surrounding context. For VSCode/Theia, use keywords such as: `vscode`, `visual studio code`, `theia`, `eclipse theia`, `extension`, `webview`, `copilot`.
5. De-duplicate links per blog post.
6. Determine display name for each link:

- Use anchor text when available.
- Otherwise use the URL.

7. Sort links alphabetically by display name within each blog post.

## Example Workflow

1. A user asks for resources about VSCode or Theia.
2. The blog collection process fetches the relevant blog posts from Dirk Fauth's gists.
3. For each relevant blog post, the link extraction process reads the post, extracts outbound links, filters for relevance, and removes duplicates without user interaction.
4. The final output is grouped by blog post, with links presented using anchor text when available, and sorted alphabetically by link name within each blog post.

## Result

The final output is an aggregated collection grouped by blog post. Blog posts are ordered alphabetically by title (or URL if no title is available). Links inside each blog post are ordered alphabetically by link display name.

### Example Result

- [Blog Post 1](http://example.com/blog1):
  - [Link 1](http://example.com/link1) - Anchor Text 1
  - [Link 2](http://example.com/link2) - Anchor Text 2
- [Blog Post 2](http://example.com/blog2):
  - [Link 3](http://example.com/link3) - Anchor Text 3
  - [Link 4](http://example.com/link4) - Anchor Text 4

## Guidelines

- Ensure that the links are relevant to the topic of VSCode or Theia.
- Avoid including duplicate links or links that are not relevant to the topic.
- Provide clear and concise output that is easy to understand and navigate.
- Use the anchor text as the name of the link when available, and use the URL as the name of the link when anchor text is not available.
- Order links alphabetically by name within each blog post section.
- Ensure that the output is structured in a way that clearly indicates which links are associated with which blog posts.
- Include a short `Skipped URLs` section when any blog post could not be fetched after retry.

Use the Agent Skill by selecting the Agent mode in the agents dropdown in the chat view and either
- enter a prompt, e.g. find links about vscode, which let Copilot discover and load the instructions by matching the user prompt with the name and the description of the skill
- use the slash command to call it directly, e.g. /blog-link-extraction links about vscode
Following the execution you will notice that the first step in processing is to read the blog-link-extraction skill file. After that it starts processing as described in the skill.

Further information about Agent Skills:

Conclusion

In this comprehensive tutorial, we explored the powerful extensibility options available for integrating AI capabilities into Visual Studio Code through Copilot extensions. We covered three main approaches to extend Copilot’s functionality:

Language Model Tools provide deep integration with VS Code APIs, allowing you to create domain-specific tools that can interact directly with the workspace and file system. While VS Code already includes many built-in tools, custom Language Model Tools enable specialized functionality tailored to your specific development needs.

MCP (Model Context Protocol) Servers offer a standardized way to connect AI applications with external tools and data sources. We demonstrated both manual configuration via mcp.json files and programmatic registration through VS Code extensions, covering local servers, remote servers, and authentication scenarios.

Chat Participants create specialized AI assistants that can leverage both Language Model Tools and MCP servers while providing a customized conversational interface. They excel when deep VS Code integration is required and can be easily distributed through the VS Code marketplace.

We also explored alternative customization approaches like Instructions, Prompt Files and Custom Agents, which can help to improve the Copilot experience according to your needs.

The key takeaway is that the choice between these approaches depends on your specific requirements: use Language Model Tools for VS Code-specific integrations, MCP servers for external tool access, and Chat Participants when you need a complete custom AI assistant experience that can be distributed as an extension.

The complete source code and examples from this tutorial are available in my GitHub repository, providing a practical foundation for building your own AI-powered VS Code extensions.

Whether you’re looking to enhance developer productivity with domain-specific AI tools or create entirely new AI-powered development workflows, this tutorial provides the essential building blocks to get started with extending Copilot in Visual Studio Code.

Getting Started with Eclipse Theia

2025-07-08T00:00:00+00:00

In my blog post Getting Started with Visual Studio Code Extension Development I explained how to implement a Visual Studio Code Extension that contributes a custom editor using the Webviews API and different Javascript frameworks. Implementing a Visual Studio Code Extension means to buy-in to the Microsoft Visual Studio Code product world. At least at first sight. By creating an application based on the Eclipse Theia Platform it is possible to build up tools that are similar to Visual Studio Code, but with some differences regarding features, extensibility and customization, privacy and deployment. It reuses components from the VS Code Open Source project and provides additional modules that add features that are otherwise only available in Visual Studio Code because of license restrictions. It is also possible to integrate Visual Studio Code Extensions to a Theia Application, and therefore it is an alternative for the deployment of the developed Visual Studio Code Extension.

If you are interested in a more detailed comparison between Visual Studio Code and Eclipse Theia, have a look at the following articles:

In this tutorial I will show how to:

Create an Eclipse Theia Application
Integrate a Visual Studio Code Extensions to a Theia Application
Extend/Customize the Theia Application via a Theia Extension
Containerize a Theia Application

Dev Container

To be able to build a Theia application, several tools and libraries need to be available. As I created a Dev Container for the development of Visual Studio Code Extensions in my previous blog post, let’s follow this path further and extend the existing Dev Container.

Open the file .devcontainer/postCreateCommand.sh

Add the Theia code generator generator-theia-extension to the initial global npm install instruction
Install the necessary Theia dependencies

#!/bin/bash

# Install a new version of npm, the Visual Studio Code Extension code generator, the extension manager,
# the Angular CLI and the Theia code generator
npm install -g npm yo generator-code @vscode/vsce @angular/cli generator-theia-extension

# Install Theia dependencies
sudo apt-get update && export DEBIAN_FRONTEND=noninteractive \
    && sudo apt-get -y install --no-install-recommends \
    make \
    gcc \
    pkg-config \
    build-essential \
    python3.11 \
    software-properties-common \
    libx11-dev \
    libxkbfile-dev \
    libsecret-1-dev \
    libssl-dev

Note:
If you have chosen to use a Dockerfile instead of a postCreateCommand.sh script file, the installation of the dependencies and the Theia code generator need to be added to the Dockerfile by using RUN commands of course.

# Install Theia dependencies
RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
    && apt-get -y install --no-install-recommends \
    make \
    gcc \
    dos2unix \
    pkg-config \
    build-essential \
    python3.11 \
    software-properties-common \
    libx11-dev \
    libxkbfile-dev \
    libsecret-1-dev \
    libssl-dev

# Install a new version of npm, the Visual Studio Code Extension code generator, the extension manager,
# the Angular CLI and the Theia code generator
RUN npm install -g npm yo generator-code @vscode/vsce @angular/cli generator-theia-extension

Rebuild the Dev Container to get the additional dependencies installed

Further details for building a Theia application are described in How to build Theia and the example applications.

Alternative: Local installation on Windows

If you prefer to develop on Windows instead of using the Dev Container, you need to prepare your local environment. This is also necessary if you want to build the Theia Electron Desktop app, as you typically build for the OS you are running the build on. That means, you need to build on Windows if you want to create a Windows Desktop application.

Install scoop.
Install nvm with scoop: scoop install nvm.
Install Node.js with nvm: nvm install lts, then use it: nvm use lts. You can list all available Node.js versions with nvm list available if you want to pick another version.
Install Python with pip
Set the environment variable PYTHON to the python.exe
Add the Python installation folder and the Scripts folder to the PATH
Install distutils module: pip install setuptools
Needed to install python packages for node gyp, but was removed in Python v3.12
Install the Visual Studio build tools with Desktop development with C++

This is also described in (Theia - Developing - Building on Windows)[https://github.com/eclipse-theia/theia/blob/master/doc/Developing.md#building-on-windows]

Additionally you need to configure the project environment, similar to what is done in the Dev Container.

Install code generator for Visual Studio Code and Theia Extensions and install the dependencies
```
npm install -g npm yo generator-code @vscode/vsce @angular/cli generator-theia-extension
```

Create the Theia application structure

A Theia Application project consists of multiple packages. There are two projects for the application (browser and desktop) and typically at least one extension project. Of course this is dependent on the use case. You could also build up the Theia Application with only Theia dependencies and Visual Studio Code Extensions.

As this tutorial is part of my Visual Studio Code Extension - Theia - Cookbook, I will setup a Multi Module Repository (monorepo) that contains the Visual Studio Code Extensions sources and the Theia related sources in one place. For other projects it might be more useful to keep the extension sources and the Theia app sources in separate repositories. Especially if the extension should be consumeable by different applications.

To avoid dependency collisions between the Visual Studio Code Extension projects and the Theia projects (e.g. different versions of webpack, different copy-webpack-plugin versions, mocha vs jasmine), the projects should be separated and not combined with a common workspace setting.

Open a Terminal
Create a new subfolder theia in the project root
Switch to that folder
Create the Theia App Modules by using the theia-extension generator
```
yo theia-extension
```
Select the type No Extension (just a Theia application)

Note:
If you generated the Theia application structure with a generator-theia-extension Version < 0.1.45 and yarn is not installed in your system, the code generation will fail with an error when trying to spawn yarn. In that case you first need to follow the steps described in Yarn vs NPM.
If you use generator-theia-extension Version >= 0.1.45 there should be no yarn dependencies anymore in the generated sources.

The generator-theia-extension creates two new modules browser-app and electron-app inside the theia folder. Additionally there are some project files

theia/lerna.json
Lerna is a fast, modern build system for managing and publishing multiple JavaScript/TypeScript packages from the same repository. There is no need to change anything here.
theia/.gitignore
The .gitignore file for the theia folder. Dependent on your strategy to handle .gitignore you can simply keep the file or move the content to the .gitignore file in the root folder. For the later you need of course to adapt the entries with the theia folder prefix.
theia/package.json
The package.json for the Theia projects. It makes use of the workspaces feature of the package manager (npm workspaces / yarn workspaces)
theia/README.md
The generated README file that contains some basic information about building and running the Theia application.
theia/.vscode/launch.json that contains some launch scripts. They need to be moved to the main .vscode/launch.json and modified to work correctly.
- Copy the two configurations to .vscode/launch.json
- Replace ${workspaceRoot} with ${workspaceRoot}/theia to have the correct file links in the configurations
- Delete the folder theia/.vscode

Yarn vs NPM

Since Theia 1.58.0 npm is used to build Theia instead of yarn, which was used before see (Use npm instead of yarn to build Theia). The Eclipse Theia Generator recently was updated to use npm instead of yarn. You need at least version 0.1.45 to get the Theia sources generated that use npm. If you are unsure which version of the Eclipse Theia Generator you have globally installed, you can check it via

npm ls --depth=0 -global

If you have an older version (e.g. because you are using a Dev Container that was created some time ago) you can update the Eclipse Theia Generator via

npm install -g generator-theia-extension@latest

Update an existing project

In case you have an existing Theia project that still uses yarn and you want to use only one package manager in our setup, perform the following updates to use npm instead of yarn:

Update theia/lerna.json
Change npmClient to npm

theia/package.json

Update the engines

"engines": {
  "npm": ">=10.0.0",
  "node": ">=18"
},

Update the scripts

Replace yarn --cwd with npm --prefix

Add run between the folder and the script

"scripts": {
"build:browser": "npm --prefix browser-app run bundle",
"build:electron": "npm --prefix electron-app run bundle",
"prepare": "lerna run prepare",
"postinstall": "theia check:theia-version",
"start:browser": "npm --prefix browser-app run start",
"start:electron": "npm --prefix electron-app run start",
"watch:browser": "lerna run --parallel watch --ignore electron-app",
"watch:electron": "lerna run --parallel watch --ignore browser-app"
},

theia/browser-app/package.json

Replace yarn rebuild with npm run rebuild

Add prepare scripts

"prepare": "npm run clean && npm run build",
"clean": "theia clean",
"build": "theia build --mode development"

theia/electron-app/package.json

Replace yarn rebuild with npm run rebuild

Add prepare scripts

"prepare": "npm run clean && npm run build",
"clean": "theia clean",
"build": "theia build --mode development"

Delete the file theia/yarn.lock

Optional: Define Tasks

Open the file .vscode/tasks.json

Add the following task definitions

{
    "label": "Build Theia Browser",
    "type": "npm",
    "script": "build:browser",
    "isBackground": true,
    "group": "build",
    "options": {
        "cwd": "${workspaceFolder}/theia"
    }
},
{
    "label": "Start Theia Browser",
    "type": "npm",
    "script": "start:browser",
    "isBackground": true,
    "options": {
        "cwd": "${workspaceFolder}/theia"
    }
},
{
    "label": "Watch Theia Browser",
    "type": "npm",
    "script": "watch:browser",
    "isBackground": true,
    "problemMatcher": {
        "owner": "typescript",
        "pattern": "$tsc",
        "background": {
            "activeOnStart": true,
            "beginsPattern": {
                "regexp": "(.*?)"
            },
            "endsPattern": {
                "regexp": "browser-app: webpack (.*?) compiled successfully"
            }
        }
    },
    "options": {
        "cwd": "${workspaceFolder}/theia"
    }
},
{
    "label": "Watch and Start Theia Browser",
    "dependsOrder": "sequence",
    "dependsOn": [
        "Watch Theia Browser",
        "Start Theia Browser"
    ],
    "problemMatcher": []
},
{
  "label": "Build Theia Electron",
  "type": "npm",
  "script": "build:electron",
  "isBackground": true,
  "group": "build",
  "options": {
    "cwd": "${workspaceFolder}/theia"
  }
},
{
  "label": "Start Theia Electron",
  "type": "npm",
  "script": "start:electron",
  "isBackground": true,
  "options": {
    "cwd": "${workspaceFolder}/theia"
  }
},
{
  "label": "Watch Theia Electron",
  "type": "npm",
  "script": "watch:electron",
  "isBackground": true,
  "problemMatcher": {
    "owner": "typescript",
    "pattern": "$tsc",
    "background": {
      "activeOnStart": true,
      "beginsPattern": {
        "regexp": "(.*?)"
      },
      "endsPattern": {
        "regexp": "electron-app: webpack (.*?) compiled successfully"
      }
    }
  },
  "options": {
    "cwd": "${workspaceFolder}/theia"
  }
},
{
  "label": "Watch and Start Theia Electron",
  "dependsOrder": "sequence",
  "dependsOn": ["Watch Theia Electron", "Start Theia Electron"],
  "problemMatcher": []
}

This step is optional, because you can perform those steps also from a Terminal window. I personally like to work with the Task Explorer Visual Studio Code Extension, which is added to the Dev Container configuration in my example. Using this extension you can trigger the task Build Theia Browser and Start Theia Browser from the Task Explorer tree view.

Interlude: Dependency Hell

From my experience over the last months, the dependency management with npm is a nightmare! I often followed my own notes to create a new Theia application from scratch, and suddenly came across some issues because of version updates in dependent modules. One was for example an incompatible node-abi version. Somehow the newest version was pulled on creating a new Theia application stub via the generator, which then failed because the current node-abi version required node@>=22.12.0 while the Dev Container was using node@20.18.1. Another example was a breaking change in inversify, and creating a new application and pulling the latest version caused compile errors on the way.

Of course the correct solution is that the downstream projects fix their dependencies, which for example happened in Theia via PR 14435 or Issue 15139. As an intermediate solution you can pin the version of a dependency that breaks in its newest version by configuring a Selective Version Resolution. This means to add a resolutions field to the package.json and define the version override. As an example, to pin the version of node-abi to 3.74.0, which was used in the electron-rebuild version used by Theia, you could add the following snippet to the theia/package.json:

"resolutions": {
  "node-abi": "3.74.0"
},

Verify

To verify that the intial Theia application setup works, let’s build and start the Theia browser application.

If you created the tasks as explained in Optional: Define Tasks you can either

Press F1
- Select Tasks: Run Task
- Select Build Theia Browser to build the Theia browser application
- Select Start Theia Browser to start the Theia browser application
Use the Task Explorer Visual Studio Code Extension
- Expand vscode_theia_cookbook - vscode in the Task Explorer view
- Run the Build Theia Browser task from the tree to build the Theia browser application
- Run the Start Theia Browser task from the tree to start the Theia browser application

If you want to work with the Terminal and execute the npm scripts manually

Open a Terminal
Switch to the theia folder
Run npm run build:browser to build the Theia browser application
Run npm run start:browser to start the Theia browser application

Note:
You can also use the Launch Configuration from the .vscode/launch.json via Run and Debug. This will start the application and enable debugging. But you first need to build the application via commandline or Task. The debugging topic will be covered at a later time in this blog post.

Once started, you can open a browser on http://localhost:3000 and see the started Theia application.

Interlude: JavaScript heap out of memory

If you phase a JavaScript heap out of memory error on building the browser-app, you probably need to increase the memory limit in Node.js. This can be done via the --max-old-space-size command line option.

Open .devcontainer/devcontainer.json
Add the following NODE_OPTIONS via the containerEnv property

  "containerEnv": {
    "NODE_OPTIONS": "--max-old-space-size=8192"
  },

Rebuild the dev container and verify if the memory issue is resolved.

Script Updates

To get the Theia dependencies installed when creating a new Dev Container, update the install:all script.

Update the package.json in the repository root

{
  "name": "vscode-theia-cookbook",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "install:all": "cd vscode-extension && npm install && cd ../angular-extension && npm run install:all && cd ../react-extension && npm run install:all && cd ../theia && npm install"
  }
}

Theia - Visual Studio Code Extension

As already mentioned, Theia is compatible with Visual Studio Code Extensions. This means it is possible to build a custom tool based on Eclipse Theia that integrates the Visual Studio Code Extensions that were created in the previous blog post.

In this section we will extend the Theia Application that we just created with the Visual Studio Code Extensions created in the previous blog post.

Add support for Visual Studio Code Extensions to the Theia application.
- Update the package.json of the browser-app and the electron-app
  - Open a Terminal
  - Switch to the Theia Application directory (theia/browser-app and theia/electron-app)
  - Add @theia/plugin-ext as a dependency for the webview support
    npm install @theia/plugin-ext
    Note:
    By including @theia/plugin-ext all Theia packages and their dependencies to which plugins/extensions can contribute are added. This can be quite a lot compared to the initially created application and might even introduce dependencies you would not directly have thought of (e.g. @theia/ai-mcp and @theia/ai-core).
  - Add @theia/plugin-ext-vscode as a dependency
    npm install @theia/plugin-ext-vscode
  - Open the package.json of the application project
    - Specify the location of the plugins that should be loaded on initialization via the --plugins option of the start script. We add them on the same level as the application projects, to have a single location for our workspace.
    - Add a script download:plugins to download the plugins
    - Add scripts to perform a clean build in a prepare script and additionally download the plugins
    - Configure the options to pre-install Visual Studio Code Extensions
      - theiaPluginsDir - the folder in which the pre-installed extensions are located
      - theiaPlugins- list of published vs code extension urls, can be empty here, because we will pre-install our extension manually
    "scripts": { "prepare": "npm run clean && npm run build && npm run download:plugins", "clean": "theia clean", "build": "theia build --mode development", "download:plugins": "theia download:plugins", "bundle": "npm run rebuild && theia build --mode development", "rebuild": "theia rebuild:browser --cacheRoot ..", "start": "theia start --plugins=local-dir:../plugins", "watch": "npm run rebuild && theia build --watch --mode development" }, "theiaPluginsDir": "../plugins", "theiaPlugins": {},
  - Build the Theia applications to take up the updated dependencies
    - Open a Terminal
    - Switch to the theia directory
    - Execute the following commands to trigger the application builds.
      npm run build:browser npm run build:electron
    Note:
    If you created the tasks as described before, you can of course use the the tasks to perform the application build.
- Open the file .vscode/launch.json
  - Locate the Start Browser Backend configuration
    - Add "--plugins=local-dir:${workspaceRoot}/theia/plugins" to the args
  - Locate the Start Electron Backend configuration
    - Add "--plugins=local-dir:${workspaceRoot}/theia/plugins" to the args
Pre-install the Visual Studio Code extensions
You have basically two options:
- Option 1: Symbolic Links
  Use symlink-dir to link the extension to the plugin folder location of the Theia application as described in Developing VS Code Extensions in a Theia Project
  - Open a Terminal
  - Switch to the vscode-extension directory
  - Add the following packages as devDependencies
    - rimraf to delete the directory
      npm i -D rimraf
    - symlink-dir to create a symbolic link
      npm i -D symlink-dir
      Note:
      With a symlink-dir version > 7.1.0 you might face Endless self reference to target parent folder. In that case force an earlier version via
      npm i -D symlink-dir@7.1.0
  - Open the file vscode-extension/package.json and add the following scripts
    "scripts": { "prepare": "npm run clean && npm run vscode:prepublish && npm run symlink", "clean": "rimraf ../theia/plugins/vscode-extension", "symlink": "symlink-dir . ../theia/plugins/vscode-extension", ... }
  - Execute the prepare script
    npm run prepare
  - Verify that the symbolic link to the vscode-extension folder is created in theia/plugins
  - Repeat the above steps for angular-extension and react-extension. Remember to update the folder references in the clean and the symlink scripts to match the extension.
  Note:
  The prepare script is a life cycle script that is automatically executed at various points which is described in Life Cycle Scripts. By adding the prepare script, the install:all scripts in angular-extension and react-extension will fail because of the execution order. There are two solutions for this issue:
  1. Change the order in the install:all scripts to first call npm install in the webview-ui folder
    "scripts": { "install:all": "cd webview-ui && npm install && cd .. && npm install", ... }
  2. Call npm install with the --ignore-scripts flag
    "scripts": { "install:all": "npm install --ignore-scripts && cd webview-ui && npm install", ... }
- Option 2: VSIX
  This means to create the .vsix extension package file and extract it to the plugins folder manually. This has the advantage that the result is the same as if you install a Visual Studio Code extension from a marketplace. So it is a real integration test and makes it easier to create a container image as I will show later.
  - Switch to the vscode-extension folder in a Terminal
  - Add the following packages as devDependencies
    - mkdirp to create the directory
      npm i -D mkdirp
    - rimraf to delete the directory
      npm i -D rimraf
    - run-script-os to execute the unzip operation in an OS dependent way
      npm i -D run-script-os
  - Open the file vscode-extension/package.json and add the following scripts
    "scripts": { ... "clean": "rimraf ../theia/plugins/vscode-extension", "package": "vsce package --allow-missing-repository", "theia:prepare-app": "npm run package && npm run theia:extract-vsix", "theia:extract-vsix": "npm run clean && npm run theia:prepare && npm run unzip", "theia:prepare": "mkdirp ../theia/plugins/vscode-extension", "unzip": "run-script-os", "unzip:windows": "tar -xf vscode-extension-0.0.1.vsix -C ../theia/plugins/vscode-extension", "unzip:nix": "unzip vscode-extension-0.0.1.vsix -d ../theia/plugins/vscode-extension" },
  - Execute npm run theia:prepare-app on the commandline of the vscode-extension project folder
    This will build the project, package it to a .vsix file and extract the file to the theia/plugins folder.
    
    Note:
    If you get the following error on running the script:
    It seems the README.md still contains template text. Make sure to edit the README.md file before you package or publish your extension.
    Open the vscode-extension/README.md of the extension project that shows the error and delete the following sentence This is the README for your extension "vscode-extension".
    Of course the real solution is to provide a meaningful README instead of the template. But for this tutorial, we can simply fix the error this way. Or simply delete the README.md of the extension for this tutorial.
    
    To avoid the question about the license on packaging, add a LICENSE file to vscode-extension folder with the information about the extension’s license.
  - Verify that the folder theia/plugins/vscode-extension is created and contains the content of the .vsix file
  - Repeat the above steps for angular-extension and react-extension. Remember to update the folder references according to the extension.
Verify the installation of the extensions
- Option 1: Via task Start Theia Browser
- Option 2: Via Terminal
  - Run the Theia browser application
  - Open a Terminal
  - Switch to the theia directory
  - Start the Theia browser application
    npm run start:browser
- Open a browser and go to http://localhost:3000
- Open the Plugins view via Menu - View - Plugins
  - Verify that the angular-extension, the react-extension and the vscode-extension are listed in the PLUGINS view.
- Open a folder somewhere
  For example, create a folder example in the home directory of the node user via Terminal of the Theia browser application.
- Create a new file named homer.person
  - The file should open with a custom editor from the installed Visual Studio Code extensions.
  - Try to open the file with another editor via right click on the file, Open With… and then selecting one of the provided editors
    If you do not see the contributed custom editors in the list, try to rebuild the Theia browser application and start it again.
Open the file theia/.gitignore
- Add the plugins folder to avoid that the plugins are added to the repository.

Possible issues with the Visual Studio Code webview integration in Theia

The following chapter contains some issues I came across when integrating a Visual Studio Code Extension in Theia.

Webview file URIs

If you use path or fsPath on the URI object of a file resource obtained via webview.asWebviewUri, you will get an incorrect value, because Theia prefixes the URL with \webview\theia-resource\file\\\.

This can be worked around with code like this:

const fileUri = getUri(webview, this.context.extensionUri, [
  "webview-ui",
  "assets",
  "myFile.yaml",
]);

// workaround to fix file path issue with Theia
var filePath = fileUri.fsPath;
if (fileUri.fsPath.startsWith("\\webview\\theia-resource\\file\\\\\\")) {
  filePath = fileUri.fsPath.replace(
    "\\webview\\theia-resource\\file\\\\\\",
    ""
  );
}

This issue was already reported and will likely be fixed in an upcoming Theia release. Issue #14727

Webviews not showing up in Theia

If the webviews do not show up on opening them, it could be an issue with the security settings related to the webview origin pattern. The reason is that webviews in the browser app are shown in an iframe. You can find further information in the @theia/plugin-ext README.

Set THEIA_WEBVIEW_EXTERNAL_ENDPOINT="" to switch to the unsecure mode for testing as described in the Theia 0.13.0 Release Plan. For the productive deployment hosting the webview handlers on a sub-domain is more secure.

Open the file .devcontainer/devcontainer.json

Add the containerEnv variable

"containerEnv": {
  "THEIA_WEBVIEW_EXTERNAL_ENDPOINT": ""
},

Note:
On opening the Theia app with the changed THEIA_WEBVIEW_EXTERNAL_ENDPOINT, you will see a notification at the bottom right, mentioning the potential security issue. This can be disabled by setting "warnOnPotentiallyInsecureHostPattern": false.

Open theia/browser-app/package.json

Add a frontend configuration to theia

  "theia": {
    "target": "browser",
    "frontend": {
      "config": {
        "warnOnPotentiallyInsecureHostPattern": false
      }
    }
  }

Welcome views do not show content

This seems to be an issue in Theia and was already reported via Issue #9361.

A possible workaround is to register a TreeDataProvider which returns an empty tree.

Consume third-party Visual Studio Code Extensions in Theia

In the previous section we integrated our Visual Studio Code Extension to the Theia application. Additionally you can consume third-party Visual Studio Code Extensions from the Open VSX Registry.

The first option to consume a Visual Studio Code Extension is to pre-install it at build-time. We have already prepared the package.json files for this in the previous section by adding theiaPlugins and theiaPluginsDir and the download:plugins script. Let’s for example pre-install the Eclipse Keymap to help people like me that are coming from Eclipse and are used to the Eclipse keybindings:

Note:
Only Microsoft products can use and connect to Microsoft’s Extension Marketplace. So it is not allowed to install extensions from there to a Theia application. Further information can be found in this article. Also note that there are also some Extensions that are only allowed to be installed in Microsoft products, e.g. Pylance the language server for Python from Microsoft can not be installed in a Theia application.

Open the file theia/browser-app/package.json

Add the following entry in the theiaPlugins section

"theiaPlugins": {
  "eclipse-keybindings": "https://open-vsx.org/api/alphabotsec/vscode-eclipse-keybindings/0.16.1/file/alphabotsec.vscode-eclipse-keybindings-0.16.1.vsix"
},

Note:
You find the link to the .vsix file on the extension page with the Download button.

Open the file theia/electron-app/package.json

Add the following entry in the theiaPlugins section

"theiaPlugins": {
  "eclipse-keybindings": "https://open-vsx.org/api/alphabotsec/vscode-eclipse-keybindings/0.16.1/file/alphabotsec.vscode-eclipse-keybindings-0.16.1.vsix"
},

Note:
You find the link to the .vsix file on the extension page with the Download button.

Open a Terminal
Switch to the folder theia
Execute npm run prepare
You could also run npm install which triggers the prepare script while processing, or switch to the browser-app and electron-app folders directly and only call npm run download:plugins.

If you now start the Theia application and open the Plugins view via Menu - View - Plugins you should see the angular-extension, the react-extension, the vscode-extension and the vscode-eclipse-keybindings listed in the PLUGINS view.

At this time we pre-installed extensions. A user is not able to change this. And users are still not able to install and uninstall additional extensions at runtime to customize their own instance of the application. To enable this feature you need to add @theia/vsx-registry as a dependency.

Open a Terminal
Switch to the folder theia/browser-app
- Add the dependency to @theia/vsx-registry via
```
npm i @theia/vsx-registry
```
Switch to the folder theia/electron-app
- Add the dependency to @theia/vsx-registry via
```
npm i @theia/vsx-registry
```
Rebuild the Theia applications

If you now start the Theia application and open the Extensions view via Menu - View - Extensions you you are able to install additional extensions to your Theia instance. You might need to refresh the browser window.

Note:
The pre-installed extensions still can not be uninstalled. This is intended, as you as a developer decided that the pre-installed extensions are required to make the application work as designed. This should not be modifiable by a customer.

The above steps and further information are also described in

Built-in Visual Studio Code Extensions

Visual Studio Code contains multiple pre-integrated extensions that make up several base functionalities of Visual Studio Code. To get an idea about those builtin extension, you can open the Extensions view in Visual Studio Code and type @builtin in the search field.

Those extensions are part of the vscode repository. To make them usable in Theia, there is the vscode-builtin-extensions repository. It packages those builtins as .vsix and publishes them. In the past the publishing was done via Open VSX. But Open VSX changed its ownership behavior, which lead to the current temporary decision by the Theia team to publish the builtin extensions via GitHub releases.

You can find further information about the temporary decision via:

Note:
Since the built-in extensions in version 1.108.2, the release contains the single built-in extensions as .vsix files and the archive of the built-in extension pack. The latest version of single built-in extensions in Open VSX is currently 1.95.3.

For example, to extend the Theia application for Typescript support, the following two built-in extensions need to be added:

TypeScript Language Basics (built-in)
TypeScript and JavaScript Language Features (built-in)

Open the file theia/browser-app/package.json

Add the following entries in the theiaPlugins section

"theiaPlugins": {
  "eclipse-keybindings": "https://open-vsx.org/api/alphabotsec/vscode-eclipse-keybindings/0.16.1/file/alphabotsec.vscode-eclipse-keybindings-0.16.1.vsix",
  "vscode-typescript": "https://github.com/eclipse-theia/vscode-builtin-extensions/releases/download/1.108.2/vscode.typescript.vsix",
  "vscode-typescript-language-features": "https://github.com/eclipse-theia/vscode-builtin-extensions/releases/download/1.108.2/vscode.typescript-language-features.vsix"
},

Open the file theia/electron-app/package.json

Add the following entries in the theiaPlugins section

"theiaPlugins": {
  "eclipse-keybindings": "https://open-vsx.org/api/alphabotsec/vscode-eclipse-keybindings/0.16.1/file/alphabotsec.vscode-eclipse-keybindings-0.16.1.vsix",
  "vscode-typescript": "https://github.com/eclipse-theia/vscode-builtin-extensions/releases/download/1.108.2/vscode.typescript.vsix",
  "vscode-typescript-language-features": "https://github.com/eclipse-theia/vscode-builtin-extensions/releases/download/1.108.2/vscode.typescript-language-features.vsix"
},

Open a Terminal
Switch to the folder theia/browser-app
Execute npm run download:plugins
As the browser-app and the electron-app share the same plugins folder in our setup, we only need to execute this for one app.

Start the Theia application and verify that syntax highlighting and code completion works for typescript files. This can be done for example by opening the workspace folder you are currently working on in the Theia Application.

Built-in Extension-Pack

To create a Theia application that provides the same functionality as vanilla Visual Studio Code, you can also install all built-in extensions by using the builtin-extension-pack. In this case you should exclude the extensions that are not working in Theia via the theiaPluginsExcludeIds setting the the package.json.

The following snippet is quite the same as in the package.json of the Theia IDE (without the Java Visual Studio Code Extensions):

  "theiaPlugins": {
    "vscode-builtin-extensions": "https://github.com/eclipse-theia/vscode-builtin-extensions/releases/download/1.108.2/vscode-builtin-extensions-1.108.2.tar.gz"
  },
  "theiaPluginsExcludeIds": [
    "ms-vscode.js-debug-companion",
    "VisualStudioExptTeam.vscodeintellicode",
    "vscode.extension-editing",
    "vscode.github",
    "vscode.github-authentication",
    "vscode.microsoft-authentication"
  ],

Theia Customization

When you create a Visual Studio Code Extension, the intention is to add a new functionality to Visual Studio Code. Apart from adding new functionality, there is not much you can do to customize Visual Studio Code. Of course you can customize the color theme, which I will show later, and you can change some settings like key bindings etc. But you can for example not remove some basic functionality in Visual Studio Code or replace it with a customized variant. In Theia it is possible to remove or replace existing features to create a custom Theia Application.

In the following sections I will describe the different ways to customize a Theia Application. It is not intended as a recommendation what to do, more a description on how to customize it by example.

Configuration

One first step in customizing a Theia Application is to configure it via Application Properties and Default Preferences. Further information can be found in ECLIPSE THEIA - CLI - Configure.

Let`s configure a custom application name for the Theia Application.

Open theia/browser-app/package.json

Add a frontend configuration to theia if it does not exist yet

  "theia": {
    "target": "browser",
    "frontend": {
      "config": {
        "applicationName": "My Custom Theia Application",
        "warnOnPotentiallyInsecureHostPattern": false
      }
    }
  }

After rebuilding and starting the browser application, you will see the application name in the browser tab.

Theia Extension for customization

If your goal is to create a Theia Application with custom functionality, the recommended way is to create a Theia Extension. This gives you full access to Theia internals with almost no limitations in terms of accessible API. Theia Extensions are installed at compile time and not intended to be installed at runtime in an existing Theia application. And of course a Theia Extension can not be installed into Visual Studio Code, unlike the Visual Studio Code Extension that we created in the previous blog post.

A more detailed comparison of the different extension mechanisms that are possible with Theia is described in Theia - Extensions and Plugins.

In the following section we create a Theia Extension that is used to customize the app.

Open a Terminal
Switch to the theia folder

Create a new Theia extension by using the theia-extension generator

yo theia-extension
? The extension's type Empty
? The extension's name theia-customization

Select do not overwrite (n) for every file that comes up with a conflict. It would otherwise remove all changes we applied before.

Note:
If you have already committed the previous work, you could also let the generator overwrite those files and merge the changes manually of course.

Make the necessary modifications manually
- Update the theia/package.json and add the new theia-customization module to the workspaces section
```
  "workspaces": [
    "theia-customization",
    "browser-app",
    "electron-app"
  ]
```
- Add the theia-customization module as a dependency to the browser-app and the electron-app
```
  "dependencies": {
    ...,
    "theia-customization": "0.0.0"
  },
```
- Optional: Update the theia-customization/package.json
  - Replace yarn in the scripts section with npm
    This is only necessary if you use a generator-theia-extension < 0.1.45
- Run npm install to update the project after the manual modifications

Now you can create a customization, like adding a banner on top of the application shell or removing things from the application, like the Terminal.

Replace an existing Theia implementation

The Theia framework uses dependency injection to wire up services and contribution points. This is described in more detail in Services and Contributions. Because of this architectural design it is easy to contribute customizations that replace existing Theia implementations.

In the following section we will replace the Theia ApplicationShell with a custom implementation that adds a banner on top.

Create a new folder theia/theia-customization/src/browser/style

Create a new file theia/theia-customization/src/browser/style/index.css

:root {
  --brand-color1: rgb(53, 52, 52);
  --brand-color2: rgb(218, 122, 8);
}

#theia-app-shell {
  top: 2.8rem;
}

#example-header {
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
  height: 2.8rem;
  display: flex;
  justify-content: space-between;
  align-items: center;
  background: linear-gradient(
    to right,
    var(--brand-color1),
    var(--brand-color2)
  );
  color: white;
  padding: 0 1rem;
  -webkit-app-region: drag;
}

#example-app-title {
  margin: 0;
  font-size: 1.33rem;
  font-weight: 400;
}

Open the file theia/theia-customization/src/theia-customization-contribution.ts

Replace the content of the file with the following content:

Import the index.css file
Extend ApplicationShell
Add a banner on top of the Theia Application Shell:

import { ApplicationShell } from "@theia/core/lib/browser";
import { injectable, postConstruct } from "@theia/core/shared/inversify";

import "../../src/browser/style/index.css";

@injectable()
export class TheiaCustomizationContribution extends ApplicationShell {
  @postConstruct()
  protected init(): void {
    super.init();

    const div = document.createElement("div");
    div.id = "example-header";

    const h1 = document.createElement("h1");
    h1.id = "example-app-title";
    const appTitle = document.createTextNode("My Custom Theia Application");
    h1.append(appTitle);
    div.append(h1);

    document.body.prepend(div);
  }
}

Open the file theia/theia-customization/src/theia-customization-frontend-module.ts

Bind the TheiaCustomizationContribution in the ContainerModule instance
Rebind the ApplicationShell with the TheiaCustomizationContribution
in the ContainerModule instance

import { ContainerModule } from "@theia/core/shared/inversify";
import { TheiaCustomizationContribution } from "./theia-customization-contribution";
import { ApplicationShell } from "@theia/core/lib/browser";

export default new ContainerModule((bind, unbind, isBound, rebind) => {
  bind(TheiaCustomizationContribution).toSelf().inSingletonScope();
  rebind(ApplicationShell)
    .to(TheiaCustomizationContribution)
    .inSingletonScope();
});

To make the integration of the new package more convenient in development, we add and modify some scripts in the theia top level package.json:

Open the file theia/package.json
Add a new script build:customization to trigger the build of the new Theia extension from the top level folder

Call that script in the build scripts of browser and electron

  "scripts": {
    "build:customization": "npm --prefix theia-customization run build",
    "build:browser": "npm run build:customization && npm --prefix browser-app run bundle",
    "build:electron": "npm run build:customization && npm --prefix electron-app run bundle",
    "prepare": "lerna run prepare",
    "postinstall": "theia check:theia-version",
    "start:browser": "npm --prefix browser-app start",
    "start:electron": "npm --prefix electron-app start",
    "watch:browser": "lerna run --parallel watch --ignore electron-app",
    "watch:electron": "lerna run --parallel watch --ignore browser-app"
  },

Open a Terminal
Switch to the theia folder
Run npm i to get the dependencies correctly resolved.
This also triggers a clean build via the prepare script.

If you now start the Theia application, the Theia Application will show a banner on top.

Further information on that topic:

Remove Default Theia Functionality

The most obvious way to remove a default Theia functionality is of course to remove the Theia package from the dependencies of the application project. But sometimes a dependency sneaks in as a transitive dependency, which you can not simply remove. For example @theia/plugin-ext has a lot of dependencies to ensure that installed Visual Studio Code extensions work correctly in Theia.

Let’s try to remove the Terminal view from the application, which comes in as a transitive dependency of @theia/plugin-ext for example.

Create a new file theia/theia-customization/src/browser/theia-customization-filter-contribution.ts

Create a new class TheiaCustomizationFilterContribution that extends FilterContribution
Implement the method registerContributionFilters(registry: ContributionFilterRegistry) and register a filter that filters out the TerminalFrontendContribution

import {
  FilterContribution,
  ContributionFilterRegistry,
  Filter,
} from "@theia/core/lib/common";
import { injectable } from "@theia/core/shared/inversify";

@injectable()
export class TheiaCustomizationFilterContribution
  implements FilterContribution
{
  registerContributionFilters(registry: ContributionFilterRegistry): void {
    registry.addFilters("*", [
      // Filter out the main outline contribution at:
      // https://github.com/eclipse-theia/theia/blob/master/packages/terminal/src/browser/terminal-frontend-contribution.ts
      filterClassName((name) => name !== "TerminalFrontendContribution"),
    ]);
  }
}

function filterClassName(filter: Filter<string>): Filter<Object> {
  return (object) => {
    const className = object?.constructor?.name;
    return className ? filter(className) : false;
  };
}

Create a new file theia/theia-customization/src/browser/theia-customization-cleanup-contribution.ts

Create a new class CleanupFrontendContribution that implements FrontendApplicationContribution
Implement the lifecycle method onDidInitializeLayout(app: FrontendApplication) and dispose any terminal widget
This is a way to ensure that a widget that is opened by default somehow is closed before the user sees anything.

import { injectable } from "inversify";
import {
  FrontendApplicationContribution,
  FrontendApplication,
} from "@theia/core/lib/browser";
import { MaybePromise } from "@theia/core/lib/common/types";
import { Widget } from "@theia/core/lib/browser/widgets";

@injectable()
export class CleanupFrontendContribution
  implements FrontendApplicationContribution
{
  /**
   * Called after the application shell has been attached in case there is no previous workbench layout state.
   * Should return a promise if it runs asynchronously.
   */
  onDidInitializeLayout(app: FrontendApplication): MaybePromise<void> {
    // Remove unused widgets
    app.shell.widgets.forEach((widget: Widget) => {
      if (widget.id.startsWith("terminal")) {
        widget.dispose();
      }
    });
  }
}

Open the file theia/theia-customization/src/theia-customization-frontend-module.ts

Bind the TheiaCustomizationFilterContribution and the CleanupFrontendContribution in the ContainerModule instance

import { ContainerModule } from "@theia/core/shared/inversify";
import { TheiaCustomizationContribution } from "./theia-customization-contribution";
import {
  ApplicationShell,
  FrontendApplicationContribution,
} from "@theia/core/lib/browser";
import { TheiaCustomizationFilterContribution } from "./theia-customization-filter-contribution";
import { bindContribution, FilterContribution } from "@theia/core";
import { CleanupFrontendContribution } from "./theia-customization-cleanup-contribution";

export default new ContainerModule((bind, unbind, isBound, rebind) => {
  bind(TheiaCustomizationContribution).toSelf().inSingletonScope();
  rebind(ApplicationShell)
    .to(TheiaCustomizationContribution)
    .inSingletonScope();

  bind(TheiaCustomizationFilterContribution).toSelf().inSingletonScope();
  bindContribution(bind, TheiaCustomizationFilterContribution, [
    FilterContribution,
  ]);

  bind(CleanupFrontendContribution).toSelf().inSingletonScope();
  bind(FrontendApplicationContribution).toService(
    CleanupFrontendContribution
  );
});

If you now build and start the Theia application, the Theia Application should not show any previously opened Terminal views and you should not be able to open a new Terminal.

Further information can be found here:

Contribution Filter

Color Themes

When you create a custom application you typically want to apply your color theme, e.g. according to your corporate style guide. Visual Studio Code offers a way to generate and publish custom color themes, and Theia adopted the usage of such Visual Studio Code themes.

Create a new color theme:

In your Visual Studio Code instance, switch to the theme to use a base for our custom color theme
- Press F1
- Enter theme
- Select Preferences: Color Theme
- Select for example Light Modern
Modify the theme via settings
- Press F1
- Enter settings
- Select Preferences: Open User Settings (JSON)
- Add the property workbench.colorCustomizations and some customizations that should be applied, for example the color of the active activity bar icons and the color of the active status bar.
```
"workbench.colorCustomizations": {
  "statusBar.background": "#da7a08",
  "activityBar.foreground": "#da7a08",
  "activityBar.activeBorder": "#da7a08"
},
```
Generate a theme file
- Press F1
- Enter theme
- Select Developer: Generate Color Theme from Current Settings
  This opens a new editor with the content of the generated color theme.

Generate a new Visual Studio Code Theme Extension
As the Theme Extension could generally be used by multiple Theia applications, and even in Visual Studio Code, we create it on the same folder level as the theia folder.

Open a Terminal
Ensure that you are on the top level of the repository.
Create a new project using generator-code
```
yo code
```

Answer the questions of the wizard for example like shown below:

? What type of extension do you want to create? New Color Theme
? Do you want to import or convert an existing TextMate color theme? No, start fresh
? What's the name of your extension? custom-theme
? What's the identifier of your extension? custom-theme
? What's the description of your extension?
? What's the name of your theme shown to the user? Custom Theme (Light)
? Select a base theme: Light
? Initialize a git repository? No

? Do you want to open the new folder with Visual Studio Code? Skip

Delete the folder custom-theme/.vscode
Open the file custom-theme/themes/Custom Theme (Light)-color-theme.json
- Copy the content of the previously generated color theme (the Untitled-1 file) and replace the content of custom-theme/themes/Custom Theme (Light)-color-theme.json with the copied content.
- Add the name property, which is missing in the generated color theme
```
{
  "name": "Custom Theme (Light)",
  ...
}
```

Pre-install the theme extension to the Theia application

Open a Terminal
Switch to the custom-theme directory
Add the following packages as devDependencies
- rimraf to delete the directory
```
npm i -D rimraf
```
- symlink-dir to create a symbolic link
```
npm i -D symlink-dir
```
- mkdirp to create the directory
```
npm i -D mkdirp
```
- run-script-os to execute the unzip operation in an OS dependent way
```
npm i -D run-script-os
```

Open the file custom-theme/package.json and add the following scripts

"scripts": {
  "prepare": "npm run clean && npm run symlink",
  "clean": "rimraf ../theia/plugins/custom-theme",
  "symlink": "symlink-dir . ../theia/plugins/custom-theme",
  "package": "vsce package --allow-missing-repository",
  "theia:prepare-app": "npm run package && npm run theia:extract-vsix",
  "theia:extract-vsix": "npm run clean && npm run theia:prepare && npm run unzip",
  "theia:prepare": "mkdirp ../theia/plugins/custom-theme",
  "unzip": "run-script-os",
  "unzip:windows": "tar -xf custom-theme-0.0.1.vsix -C ../theia/plugins/custom-theme",
  "unzip:nix": "unzip custom-theme-0.0.1.vsix -d ../theia/plugins/custom-theme"
}

Execute the prepare script
```
npm run prepare
```
Verify that the symbolic link to the custom-theme folder is created in theia/plugins

Note:
If you execute npm run theia:prepare-app on the commandline of the custom-theme project folder the project is built, packaged to a .vsix file which is then extracted to the theia/plugins folder. This mechanism will be used for the containerization of the Theia Application.

Enable the custom theme on startup via predefined preferences

Open the file theia/browser-app/package.json

Add the theia/frontend/config/preferences property to set the workbench.colorTheme

"theia": {
  "target": "browser",
  "frontend": {
    "config": {
      "applicationName": "My Custom Theia Application",
      "warnOnPotentiallyInsecureHostPattern": false,
      "preferences": {
        "workbench.colorTheme": "Custom Theme (Light)"
      }
    }
  }
}

Open the file theia/electron-app/package.json

Add the theia/frontend/config/preferences property to set the workbench.colorTheme

"theia": {
  "target": "electron",
  "frontend": {
    "config": {
      "applicationName": "My Custom Theia Application",
      "preferences": {
        "workbench.colorTheme": "Custom Theme (Light)"
      }
    }
  }
}

Build and start the Theia Application and verify that the custom theme is applied on startup

Further information about Visual Studio Code Color Themes can be found here:

Containerizing the Theia Browser Application

To containerize the Theia application, you need to setup a Dockerfile with the necessary dependencies. These are described in How to build Theia and the example applications.

It is also recommended to setup a multi-stage build, where the first step is the build of the application and the second step is the image creation with only the build result. This keeps the final image as small as possible.

For this task we need to ensure that the Visual Studio Code Extensions are added to the plugins folder in the extracted .vsix way, as the symbolic links would not work in the Theia Application container if you don’t copy the extension projects folders also to the final container image.

Open the package.json in the repository root

Extend the install:all script to run npm install on the custom-theme project
Add a new script build:all:browser that calls theia:prepare-app for each Visual Studio Code Extension and then builds the Theia Browser Application.

{
  "name": "vscode-theia-cookbook",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "install:all": "cd vscode-extension && npm install && cd ../angular-extension && npm run install:all && cd ../react-extension && npm run install:all && cd ../custom-theme && npm install && cd ../theia && npm install",
    "build:all:browser": "cd vscode-extension && npm run theia:prepare-app && cd ../angular-extension && npm run theia:prepare-app && cd ../react-extension && npm run theia:prepare-app && cd ../custom-theme && npm run theia:prepare-app && cd ../theia && npm run build:browser"
  }
}

Create a Dockerfile in the repository root

# Builder stage
ARG NODE_VERSION=20
FROM node:${NODE_VERSION}-bullseye AS build

# install required tools to build the application
RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
    && apt-get -y install --no-install-recommends \
    make \
    gcc \
    pkg-config \
    build-essential \
    python3 \
    software-properties-common \
    libx11-dev \
    libxkbfile-dev \
    libsecret-1-dev \
    libssl-dev

RUN npm install -g @vscode/vsce @angular/cli

WORKDIR /home

# copy sources to the container
COPY ./angular-extension ./angular-extension
COPY ./react-extension ./react-extension
COPY ./vscode-extension ./vscode-extension
COPY ./custom-theme ./custom-theme
COPY ./theia ./theia
COPY package.json ./package.json

# set the GITHUB_TOKEN environment variable
# needed to avoid API rate limit when the build tries to download vscode-ripgrep
# see https://github.com/microsoft/vscode/issues/28434
ARG GITHUB_TOKEN
ENV GITHUB_TOKEN=$GITHUB_TOKEN

# run the build
RUN npm run install:all && \
    npm run build:all:browser && \
    cd theia && \
    rm package-lock.json && \
    rm -rf node_modules **/node_modules

# create the execution image
FROM node:${NODE_VERSION}-bullseye-slim

# Create theia user and directories
# Application will be copied to /home/theia
# Default workspace is located at /home/project
RUN adduser --system --group theia
RUN chmod g+rw /home && \
    mkdir -p /home/project && \
    chown -R theia:theia /home/theia && \
    chown -R theia:theia /home/project;

# Install required tools for application
RUN apt-get update && \
    apt-get install -y \
    openssh-client \
    openssh-server \
    libsecret-1-0 && \
    apt-get clean

ENV HOME=/home/theia \
    THEIA_DEFAULT_PLUGINS=local-dir:/home/theia/plugins \
    THEIA_WEBVIEW_EXTERNAL_ENDPOINT=""

WORKDIR /home/theia

# Copy application from build stage
COPY --from=build --chown=theia:theia /home/theia/browser-app /home/theia/browser-app
COPY --from=build --chown=theia:theia /home/theia/plugins /home/theia/plugins

EXPOSE 3000

# Switch to Theia user
USER theia

# Launch the backend application via node
ENTRYPOINT [ "node", "/home/theia/browser-app/lib/backend/main.js" ]

# Arguments passed to the application
CMD [ "/home/project", "--hostname=0.0.0.0" ]

You can also have a look at the Theia IDE Browser Dockerfile for an example.

Note:
The configuration of the GITHUB_TOKEN is only necessary if you are hitting the GitHub API rate limit. This could happen because of the vscode-ripgrep dependency, which uses the GitHub API to download the native binary part of the library. See Possible Issues for further information.

Create a .dockerignore file in the repository root to ensure that only the relevant parts for the build are copied to the image.
This is especially necessary because of the native artifacts like GLIBC in the local build results, which does not need to be the same on the host and in the resulting container image.
```
**/dist/
**/build/
**/node_modules/
theia/**/lib
theia/plugins
theia/**/src-gen/
theia/electron-app
**/target/
yarn.lock
package-lock.json
gen-webpack*.*
**/*.vsix
```
Ensure that you have Docker or Podman installed. In case you are using the Dev Container
- Open the file .devcontainer/devcontainer.json
- Add the docker-in-docker feature
```
"features": {
  // https://github.com/devcontainers/features/tree/main/src/docker-in-docker
  "ghcr.io/devcontainers/features/docker-in-docker:2": {}
},
```
- Rebuild the Dev Container to get the docker-in-docker feature installed
Build the container image
- Open a Terminal
- Execute the following command in the repository root folder
```
docker build -t theia_custom_application .
```

If a previous attempt failed and you want to a clean rebuild, use the --no-cache option.
If the console output of the build process does not show the necessary detailed output, use the option --progress=plain to get the container output.

Run the container either via:

docker run -d --rm -p 3000:3000 --name theia_custom_application theia_custom_application

or if you configured your WSL via networkingMode=mirrored

docker run -d --rm --network=host --name theia_custom_application theia_custom_application

Connect to the running container in case of issues:

docker exec -ti theia_custom_application /bin/bash

Possible issues

There could be multiple issues in building the container image:

Build fails with error Downloading ripgrep failed: Error: API rate limit exceeded
The error is reported in https://github.com/microsoft/vscode/issues/28434. The explained workaround is to create and configure a GITHUB_TOKEN environment variable.
This can be done via GitHub - Settings - Developer Settings - Personal access tokens - Tokens (classic) - Generate Token. To avoid that the token is hardcoded in the Dockerfile, configure it as an environment variable. To forward an environment variable from the Windows Host to the WSL, you can additionally configure the special environment variable WSLENV like this: WSLENV=GITHUB_TOKEN/u. Have a look at Share Environment Vars between WSL and Windows. Once the environment variable is set and available, update the .devcontainer/devcontainer.json file and add the following configuration as described in Visual Studio Code - Environment variables
```
"remoteEnv": {
  "GITHUB_TOKEN": "${localEnv:GITHUB_TOKEN}"
},
```
Then run the build using the --build-arg GITHUB_TOKEN=${GITHUB_TOKEN} argument:
```
docker build -t theia_custom_application --build-arg GITHUB_TOKEN=${GITHUB_TOKEN} .
```

Alternatively you can manually download the native executable for your operating system from ripgrep-prebuilt/releases and extract it to theia/node_modules/@vscode/ripgrep/bin. For the container build, copy the binary in the image creation process to avoid the download at image creation time.

Conclusion

In this blog post I collected the information I gathered over the last months related to getting started with Eclipse Theia. I hope the information helps others who also want to start with Eclipse Theia. There is of course a lot more to learn about it, so this post is just the beginning.

At this point I want to thank Stefan Dirix and Philip Langer and the Eclipse Theia Community for the support. Whenever I had questions, opened issues or even contributed something, I got a friendly and helpful response.

The sources of this and the previous blog posts can be found in my Github repository.

I hope you again enjoyed my tutorial and I could share some information via my “external memory”.

Multiple webviews in a single Visual Studio Code Extension

2025-05-07T00:00:00+00:00

In my previous blog post Getting Started with Visual Studio Code Extension Development I described how to create a Visual Studio Code Extension that contributes a custom editor that is implemented using a webview. And I compared how this can be done using vanilla HTML and Javascript, using Angular and using React. Only a single webview is contributed by each Visual Studio Code Extension in the examples of that blog post, which is sufficient for a lot of use cases. But after the publishing of that blog post I was asked several times how to contribute multiple editors with a single extension. It turned out that this is not as intuitive as initially thought, so I decided to write a new blog post dedicated to this topic.

To demonstrate the solutions for the different variants I will add a simple pet editor to the extensions.

Note:
The following content is based on the Getting Started with Visual Studio Code Extension Development blog post. If you want to follow the steps described in this post, work through the previous blog post or get the sources from the getting_started branch.

Visual Studio Code Extension Project

Let’s start by adding a second custom editor to the Vanilla HTML and Javascript Visual Studio Code Extension.

Open the vscode-extension/package.json

Extend the contributes section to add a Pet editor for the .pet file extension:

"contributes": {
    "customEditors": [
    {
        "viewType": "vscode-extension.personEditor",
        "displayName": "Visual Studio Code Person Editor",
        "selector": [
        {
            "filenamePattern": "*.person"
        }
        ],
        "priority": "default"
    },
    {
        "viewType": "vscode-extension.petEditor",
        "displayName": "Visual Studio Code Pet Editor",
        "selector": [
        {
            "filenamePattern": "*.pet"
        }
        ],
        "priority": "default"
    }
    ]
},

Create a new file vscode-extension/src/abstractEditor.ts
To avoid that we need to copy a lot of code for the new editor, we create an abstract base class AbstractEditorProvider that will be used by both editor implementations.

Copy the content of vscode-extension/src/personEditor.ts to vscode-extension/src/abstractEditor.ts
Rename PersonEditorProvider to AbstractEditorProvider and make it abstract
Remove the viewType constant, the constructor and the register method
Change the visibility of getWebviewHtml() method to protected and make it abstract

import * as vscode from "vscode";

export abstract class AbstractEditorProvider
  implements vscode.CustomTextEditorProvider
{
  public async resolveCustomTextEditor(
    document: vscode.TextDocument,
    webviewPanel: vscode.WebviewPanel,
    _token: vscode.CancellationToken
  ): Promise<void> {
    // Setup initial content for the webview
    webviewPanel.webview.options = {
      // Enable scripts in the webview
      enableScripts: true,
    };

    webviewPanel.webview.html = this.getWebviewHtml(webviewPanel.webview);

    // Hook up event handlers so that we can synchronize the webview with the text document.
    //
    // The text document acts as our model, so we have to sync change in the document to our
    // editor and sync changes in the editor back to the document.
    //
    // Remember that a single text document can also be shared between multiple custom
    // editors (this happens for example when you split a custom editor)

    const changeDocumentSubscription =
      vscode.workspace.onDidChangeTextDocument((e) => {
        if (e.document.uri.toString() === document.uri.toString()) {
          this.updateWebview(webviewPanel, document);
        }
      });

    // Make sure we get rid of the listener when our editor is closed.
    webviewPanel.onDidDispose(() => {
      changeDocumentSubscription.dispose();
    });

    // Receive message from the webview.
    webviewPanel.webview.onDidReceiveMessage((e) => {
      switch (e.type) {
        case "updateDocument":
          this.updateDocument(document, e.text);
          return;
      }
    });

    this.updateWebview(webviewPanel, document);
  }

  /**
   * Updates the webview with the content of the current document.
   * @param webviewPanel The webview panel to post the message to.
   * @param document The current document.
   */
  private updateWebview(
    webviewPanel: vscode.WebviewPanel,
    document: vscode.TextDocument
  ) {
    // Post message with text of the document to the webview
    webviewPanel.webview.postMessage({
      type: "update",
      text: document.getText(),
    });
  }

  /**
   * Applies a set of text edits to a document.
   * @param document The current document.
   * @param text The text to set to the document.
   * @returns A thenable that resolves when the edit could be applied.
   */
  private updateDocument(document: vscode.TextDocument, text: string) {
    const edit = new vscode.WorkspaceEdit();
    edit.replace(
      document.uri,
      new vscode.Range(0, 0, document.lineCount, 0),
      text
    );
    return vscode.workspace.applyEdit(edit);
  }

  /**
   * Get the static html used for the editor webviews.
   */
  protected abstract getWebviewHtml(webview: vscode.Webview): string;

  /**
   * A helper function that returns a unique alphanumeric identifier called a nonce.
   *
   * @remarks This function is primarily used to help enforce content security
   * policies for resources/scripts being executed in a webview context.
   *
   * @returns A nonce
   */
  getNonce() {
    let text = "";
    const possible =
      "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
    for (let i = 0; i < 32; i++) {
      text += possible.charAt(Math.floor(Math.random() * possible.length));
    }
    return text;
  }
}

Update the file vscode-extension/src/personEditor.ts

Extend AbstractEditorProvider
Call super() in the constructor
Change the visibility of getWebviewHtml() to protected
Delete the other methods that are now defined in AbstractEditorProvider

import * as vscode from "vscode";
import { AbstractEditorProvider } from "./abstractEditor";

export class PersonEditorProvider extends AbstractEditorProvider {
  private static readonly viewType = "vscode-extension.personEditor";

  constructor(private readonly context: vscode.ExtensionContext) {
    super();
  }

  public static register(
    context: vscode.ExtensionContext
  ): vscode.Disposable {
    const provider = new PersonEditorProvider(context);
    const providerRegistration = vscode.window.registerCustomEditorProvider(
      PersonEditorProvider.viewType,
      provider
    );
    return providerRegistration;
  }

  /**
   * Get the static html used for the editor webviews.
   */
  protected getWebviewHtml(webview: vscode.Webview): string {
    // Local path to script and css for the webview
    const stylesUri = webview.asWebviewUri(
      vscode.Uri.joinPath(this.context.extensionUri, "media", "styles.css")
    );
    const scriptUri = webview.asWebviewUri(
      vscode.Uri.joinPath(this.context.extensionUri, "media", "main.js")
    );

    const elementsUri = webview.asWebviewUri(
      vscode.Uri.joinPath(
        this.context.extensionUri,
        "node_modules",
        "@vscode-elements/elements",
        "dist",
        "bundled.js"
      )
    );

    const nonce = this.getNonce();

    // Tip: Install the es6-string-html Visual Studio Code extension to enable code highlighting below
    return /* html */ `
      
      
      
          
  
          
          ${webview.cspSource}; font-src ${webview.cspSource}; style-src ${webview.cspSource}; script-src 'nonce-${nonce}';">
  
          
  
          ${stylesUri}" rel="stylesheet" />
  
          Person EditorVisual Studio Code Person EditorFirstname:
                      
                  
Lastname:
                      
                  

      
      `;
  }
}

Create a new file vscode-extension/src/petEditor.ts

Copy the content of vscode-extension/src/personEditor.ts
Rename the class to PetEditorProvider
Update the value of viewType to "vscode-extension.petEditor"
Update the register() implementation to register the PetEditorProvider
Update the getWebviewHtml() implementation to return the HTML for a pet editor

import * as vscode from "vscode";
import { AbstractEditorProvider } from "./abstractEditor";

export class PetEditorProvider extends AbstractEditorProvider {
  private static readonly viewType = "vscode-extension.petEditor";

  constructor(private readonly context: vscode.ExtensionContext) {
    super();
  }

  public static register(
    context: vscode.ExtensionContext
  ): vscode.Disposable {
    const provider = new PetEditorProvider(context);
    const providerRegistration = vscode.window.registerCustomEditorProvider(
      PetEditorProvider.viewType,
      provider
    );
    return providerRegistration;
  }

  /**
   * Get the static html used for the editor webviews.
   */
  protected getWebviewHtml(webview: vscode.Webview): string {
    // Local path to script and css for the webview
    const stylesUri = webview.asWebviewUri(
      vscode.Uri.joinPath(this.context.extensionUri, "media", "styles.css")
    );
    const scriptUri = webview.asWebviewUri(
      vscode.Uri.joinPath(this.context.extensionUri, "media", "main.js")
    );

    const elementsUri = webview.asWebviewUri(
      vscode.Uri.joinPath(
        this.context.extensionUri,
        "node_modules",
        "@vscode-elements/elements",
        "dist",
        "bundled.js"
      )
    );

    const nonce = this.getNonce();

    // Tip: Install the es6-string-html Visual Studio Code extension to enable code highlighting below
    return /* html */ `
      
      
      
          
  
          
          ${webview.cspSource}; font-src ${webview.cspSource}; style-src ${webview.cspSource}; script-src 'nonce-${nonce}';">
  
          
  
          ${stylesUri}" rel="stylesheet" />
  
          Pet EditorVisual Studio Code Pet EditorName:
                      
                  
Species:
                      
                          -
                          Bird
                          Cat
                          Dog
                      
                  

      
      `;
  }
}

Update the file vscode-extension/media/main.js so the code is able to handle persons and pets

// Script run within the webview itself.
(function () {
  // Get a reference to the Visual Studio Code webview api.
  // We use this API to post messages back to our extension.

  const vscode = acquireVsCodeApi();

  const personContainer = /** @type {HTMLElement} */ (
    document.querySelector(".person")
  );
  const petContainer = /** @type {HTMLElement} */ (
    document.querySelector(".pet")
  );

  const errorContainer = document.createElement("div");
  document.body.appendChild(errorContainer);
  errorContainer.className = "error";
  errorContainer.style.display = "none";

  /**
   * Render the document in the webview.
   */
  function updateContent(/** @type {string} */ text) {
    let json;
    try {
      if (!text) {
        text = "{}";
      }
      json = JSON.parse(text);
    } catch {
      if (personContainer) {
        personContainer.style.display = "none";
      }
      if (petContainer) {
        petContainer.style.display = "none";
      }
      errorContainer.innerText = "Error: Document is not valid json";
      errorContainer.style.display = "";
      return;
    }
    if (personContainer) {
      personContainer.style.display = "";
    }
    if (petContainer) {
      petContainer.style.display = "";
    }
    errorContainer.style.display = "none";

    const firstname = document.getElementById("firstname");
    const lastname = document.getElementById("lastname");

    const name = document.getElementById("name");
    const species = document.getElementById("species");

    if (firstname && lastname) {
      if (json.firstname) {
        firstname.value = json.firstname;
      }
      if (json.lastname) {
        lastname.value = json.lastname;
      }

      firstname.oninput = () => {
        let value = firstname.value;
        // wait 500 ms before updating the document
        // only update if in the meantime no other input was given
        setTimeout(() => {
          if (value === firstname.value) {
            json.firstname = firstname.value;
            vscode.postMessage({
              type: "updateDocument",
              text: JSON.stringify(json, null, 2),
            });
          }
        }, 500);
      };

      lastname.oninput = () => {
        let value = lastname.value;
        // wait 500 ms before updating the document
        // only update if in the meantime no other input was given
        setTimeout(() => {
          if (value === lastname.value) {
            json.lastname = lastname.value;
            vscode.postMessage({
              type: "updateDocument",
              text: JSON.stringify(json, null, 2),
            });
          }
        }, 500);
      };
    }

    if (name && species) {
      if (json.name) {
        name.value = json.name;
      }
      if (json.species) {
        species.value = json.species;
      }

      name.oninput = () => {
        let value = name.value;
        // wait 500 ms before updating the document
        // only update if in the meantime no other input was given
        setTimeout(() => {
          if (value === name.value) {
            json.name = name.value;
            vscode.postMessage({
              type: "updateDocument",
              text: JSON.stringify(json, null, 2),
            });
          }
        }, 500);
      };

      species.oninput = () => {
        let value = species.value;
        // wait 500 ms before updating the document
        // only update if in the meantime no other input was given
        setTimeout(() => {
          if (value === species.value) {
            json.species = species.value;
            vscode.postMessage({
              type: "updateDocument",
              text: JSON.stringify(json, null, 2),
            });
          }
        }, 500);
      };
    }
  }

  // Handle messages sent from the extension to the webview
  window.addEventListener("message", (event) => {
    const message = event.data; // The json data that the extension sent
    switch (message.type) {
      case "update":
        const text = message.text;

        // Update our webview's content
        updateContent(text);

        // Then persist state information.
        // This state is returned in the call to `vscode.getState` below when a webview is reloaded.
        vscode.setState({ text });

        return;
    }
  });

  // Webviews are normally torn down when not visible and re-created when they become visible again.
  // State lets us save information across these re-loads
  const state = vscode.getState();
  if (state) {
    updateContent(state.text);
  }
})();

Update vscode-extension/src/extension.ts

// The module 'vscode' contains the Visual Studio Code extensibility API
// Import the module and reference it with the alias vscode in your code below
import * as vscode from "vscode";
import { PersonEditorProvider } from "./personEditor";
import { PetEditorProvider } from "./petEditor";

// This method is called when your extension is activated
export function activate(context: vscode.ExtensionContext) {
  // Register our custom editor provider
  context.subscriptions.push(PersonEditorProvider.register(context));
  context.subscriptions.push(PetEditorProvider.register(context));
}

// This method is called when your extension is deactivated
export function deactivate() {}

If everything is correctly in place, you can verify the editor by

pressing F5 to start a new Visual Studio Code instance with the extension
opening a folder somewhere
Create a folder example in the home directory of the node user in the Dev Container for example.
creating a new file named santas.pet

Now a webview with two input fields should be visible.

enter values for Name and Species,
e.g. Name: Santa’s little helper, Species: Dog
Save via CTRL + S
Right click on the created file in the Explorer
Select Open With… - Text Editor

The default text editor should open with the JSON content of the created file.

Angular Webview Implementation

To provide multiple webviews in an extension that uses Angular as webframework, there is some more work to do. In the Getting Started with Visual Studio Code Extension Development - Angular Webview Implementation I implemented the webview as a Angular Standalone Component and I removed the RouterOutlet to make the usage of assets from third-party modules work correctly.

The following section describes how to add a second custom editor to the Angular Visual Studio Code Extension.

Open the angular-extension/package.json

Extend the contributes section to add a Pet editor for the .pet file extension:

"contributes": {
  "customEditors": [
    {
      "viewType": "angular-extension.personEditor",
      "displayName": "Angular Person Editor",
      "selector": [
        {
          "filenamePattern": "*.person"
        }
      ],
      "priority": "option"
    },
    {
      "viewType": "angular-extension.petEditor",
      "displayName": "Angular Pet Editor",
      "selector": [
        {
          "filenamePattern": "*.pet"
        }
      ],
      "priority": "option"
    }
  ]
},

Create a new file angular-extension/src/abstractEditor.ts
To avoid that we need to copy a lot of code for the new editor, we create an abstract base class AbstractEditorProvider that will be used by both editor implementations.

Copy the content of angular-extension/src/personEditor.ts to angular-extension/src/abstractEditor.ts
Rename PersonEditorProvider to AbstractEditorProvider and make it abstract
Remove the viewType constant and the register method
Add an abstract method getRootComponentSelector()
Update getWebviewHtml() to use getRootComponentSelector() as the app root component and as an attribute data-root in the html tag

import * as vscode from "vscode";

export abstract class AbstractEditorProvider
  implements vscode.CustomTextEditorProvider
{
  constructor(private readonly context: vscode.ExtensionContext) {}

  public async resolveCustomTextEditor(
    document: vscode.TextDocument,
    webviewPanel: vscode.WebviewPanel,
    _token: vscode.CancellationToken
  ): Promise<void> {
    // Setup initial content for the webview
    webviewPanel.webview.options = {
      // Enable scripts in the webview
      enableScripts: true,

      // Restrict the webview to only load resources from the `dist` and `webview-ui/build` directories
      localResourceRoots: [
        vscode.Uri.joinPath(this.context.extensionUri, "dist"),
        vscode.Uri.joinPath(this.context.extensionUri, "webview-ui/build"),
      ],
    };

    webviewPanel.webview.html = this.getWebviewHtml(webviewPanel.webview);

    // Hook up event handlers so that we can synchronize the webview with the text document.
    //
    // The text document acts as our model, so we have to sync change in the document to our
    // editor and sync changes in the editor back to the document.
    //
    // Remember that a single text document can also be shared between multiple custom
    // editors (this happens for example when you split a custom editor)

    const changeDocumentSubscription =
      vscode.workspace.onDidChangeTextDocument((e) => {
        if (e.document.uri.toString() === document.uri.toString()) {
          this.updateWebview(webviewPanel, document);
        }
      });

    // Make sure we get rid of the listener when our editor is closed.
    webviewPanel.onDidDispose(() => {
      changeDocumentSubscription.dispose();
    });

    // Receive message from the webview.
    webviewPanel.webview.onDidReceiveMessage((e) => {
      switch (e.type) {
        case "updateDocument":
          this.updateDocument(document, e.text);
          return;
      }
    });

    this.updateWebview(webviewPanel, document);
  }

  /**
   * Updates the webview with the content of the current document.
   * @param webviewPanel The webview panel to post the message to.
   * @param document The current document.
   */
  private updateWebview(
    webviewPanel: vscode.WebviewPanel,
    document: vscode.TextDocument
  ) {
    // Post message with text of the document to the webview
    webviewPanel.webview.postMessage({
      type: "update",
      text: document.getText(),
    });
  }

  /**
   * Applies a set of text edits to a document.
   * @param document The current document.
   * @param text The text to set to the document.
   * @returns A thenable that resolves when the edit could be applied.
   */
  private updateDocument(document: vscode.TextDocument, text: string) {
    const edit = new vscode.WorkspaceEdit();
    edit.replace(
      document.uri,
      new vscode.Range(0, 0, document.lineCount, 0),
      text
    );
    return vscode.workspace.applyEdit(edit);
  }

  /**
   * Get the static html used for the editor webviews.
   */
  private getWebviewHtml(webview: vscode.Webview): string {
    // The CSS file from the Angular build output
    const stylesUri = webview.asWebviewUri(
      vscode.Uri.joinPath(
        this.context.extensionUri,
        "webview-ui",
        "build",
        "styles.css"
      )
    );
    // The JS files from the Angular build output
    const polyfillsUri = webview.asWebviewUri(
      vscode.Uri.joinPath(
        this.context.extensionUri,
        "webview-ui",
        "build",
        "polyfills.js"
      )
    );
    const scriptUri = webview.asWebviewUri(
      vscode.Uri.joinPath(
        this.context.extensionUri,
        "webview-ui",
        "build",
        "main.js"
      )
    );

    const rootSelector = this.getRootComponentSelector();
    const nonce = this.getNonce();

    // Tip: Install the es6-string-html VS Code extension to enable code highlighting below
    return /*html*/ `
      
      ${rootSelector}">
      
          
          
          ${webview.cspSource} 'unsafe-inline'; font-src ${webview.cspSource}; img-src ${webview.cspSource}; script-src 'nonce-${nonce}';">
          ${stylesUri}">
      
      
          <${rootSelector}>${rootSelector}>
          
          
      
      
    `;
  }

  /**
   * Return the selector of the root component to use.
   */
  abstract getRootComponentSelector(): string;

  /**
   * A helper function that returns a unique alphanumeric identifier called a nonce.
   *
   * @remarks This function is primarily used to help enforce content security
   * policies for resources/scripts being executed in a webview context.
   *
   * @returns A nonce
   */
  getNonce() {
    let text = "";
    const possible =
      "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
    for (let i = 0; i < 32; i++) {
      text += possible.charAt(Math.floor(Math.random() * possible.length));
    }
    return text;
  }
}

Update the file angular-extension/src/personEditor.ts

Extend AbstractEditorProvider
Call super(context) in the constructor
Add the getRootComponentSelector() method which returns person-root
Delete the other methods that are now defined in AbstractEditorProvider

import * as vscode from "vscode";
import { AbstractEditorProvider } from "./abstractEditor";

export class PersonEditorProvider extends AbstractEditorProvider {
  private static readonly viewType = "angular-extension.personEditor";

  constructor(context: vscode.ExtensionContext) {
    super(context);
  }

  public static register(
    context: vscode.ExtensionContext
  ): vscode.Disposable {
    const provider = new PersonEditorProvider(context);
    const providerRegistration = vscode.window.registerCustomEditorProvider(
      PersonEditorProvider.viewType,
      provider
    );
    return providerRegistration;
  }

  getRootComponentSelector(): string {
    return "person-root";
  }
}

Create a new file angular-extension/src/petEditor.ts

Copy the content of angular-extension/src/personEditor.ts
Rename the class to PetEditorProvider
Update the value of viewType to "angular-extension.petEditor"
Update the register() implementation to register the PetEditorProvider
Change the return value of getRootComponentSelector() to pet-root

import * as vscode from "vscode";
import { AbstractEditorProvider } from "./abstractEditor";

export class PetEditorProvider extends AbstractEditorProvider {
  private static readonly viewType = "angular-extension.petEditor";

  constructor(context: vscode.ExtensionContext) {
    super(context);
  }

  public static register(
    context: vscode.ExtensionContext
  ): vscode.Disposable {
    const provider = new PetEditorProvider(context);
    const providerRegistration = vscode.window.registerCustomEditorProvider(
      PetEditorProvider.viewType,
      provider
    );
    return providerRegistration;
  }

  getRootComponentSelector(): string {
    return "pet-root";
  }
}

Update angular-extension/src/extension.ts

// The module 'vscode' contains the Visual Studio Code extensibility API
// Import the module and reference it with the alias vscode in your code below
import * as vscode from "vscode";
import { PersonEditorProvider } from "./personEditor";
import { PetEditorProvider } from "./petEditor";

// This method is called when your extension is activated
export function activate(context: vscode.ExtensionContext) {
  // Register our custom editor provider
  context.subscriptions.push(PersonEditorProvider.register(context));
  context.subscriptions.push(PetEditorProvider.register(context));
}

// This method is called when your extension is deactivated
export function deactivate() {}

Now that the extension code is prepared for multiple custom editors, the webview needs to be implemented in the Angular webview-ui structure. There is also some refactoring involved

Update angular-extension/webview-ui/src/app/vscode-textfield-input.directive.ts
I want to use the VSCode Elements - Single Select component in the new pet editor. The VSCode Elements implementation is based on the Lit library. So the usage requires the implementation of a ControlValueAccessor as a Directive, which is described in Getting Started with Visual Studio Code Extension Development. As the vscode-single-select component also tracks its state in the value attribute, we can simply add vscode-single-select to the selector of the existing Directive.
```
@Directive({
  selector: 'vscode-textfield, vscode-single-select',
  providers: [VSCODE_TEXTFIELD_INPUT_VALUE_ACCESSOR],
})
export class VscodeTextfieldInputDirective implements ControlValueAccessor {
```
We could of course also think about renaming it to something more general, but let’s keep the modifications minimal at this point.
Create a new folder angular-extension/webview-ui/src/app/person
Move the following files to angular-extension/webview-ui/src/app/person
- angular-extension/webview-ui/src/app/app.component.html
- angular-extension/webview-ui/src/app/app.component.ts
- angular-extension/webview-ui/src/app/app.component.spec.ts
Rename those files by replacing app with person

Edit the file angular-extension/webview-ui/src/app/person/person.component.ts

Change the selector to person-root
Rename the AppComponent class to PersonComponent

Correct the references in templateUrl and styleUrl

@Component({
selector: 'person-root',
imports: [ReactiveFormsModule, VscodeTextfieldInputDirective],
templateUrl: './person.component.html',
styleUrl: '../app.component.css',
schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class PersonComponent {

Now create a PetComponent as the second custom editor in the Angular extension:

Create a new folder angular-extension/webview-ui/src/app/pet

Create a new file angular-extension/webview-ui/src/app/pet/pet.component.html

<main class="main">
  <h1>Angular Pet Editor</h1>
  <div class="content">
    <div class="pet">
      <div class="row">
        <vscode-label for="name">Name:</vscode-label>
        <div class="value">
          <vscode-textfield
            type="text"
            [formControl]="name"
            (input)="updateDocument()"
          />
        </div>
      </div>
      <div class="row">
        <vscode-label for="species">Species:</vscode-label>
        <div class="value">
          <vscode-single-select
            [formControl]="species"
            (input)="updateDocument()"
          >
            <vscode-option>-</vscode-option>
            <vscode-option description="bird">Bird</vscode-option>
            <vscode-option description="cat">Cat</vscode-option>
            <vscode-option description="dog">Dog</vscode-option>
          </vscode-single-select>
        </div>
      </div>
    </div>
  </div>
</main>

Create a new file angular-extension/webview-ui/src/app/pet/pet.component.ts
The content of this file is almost the same as angular-extension/webview-ui/src/app/person/person.component.ts, but of course with changes related to the pet data structure and the selector is changed to pet-root.

import {
  Component,
  CUSTOM_ELEMENTS_SCHEMA,
  HostListener,
} from "@angular/core";
import { FormControl, ReactiveFormsModule } from "@angular/forms";
import { vscode } from "../utilities/vscode";
import { VscodeTextfieldInputDirective } from "../vscode-textfield-input.directive";
import "../../../node_modules/@vscode-elements/elements/dist/vscode-label";
import "../../../node_modules/@vscode-elements/elements/dist/vscode-textfield";
import "../../../node_modules/@vscode-elements/elements/dist/vscode-single-select";
import "../../../node_modules/@vscode-elements/elements/dist/vscode-option";

@Component({
  selector: "pet-root",
  imports: [ReactiveFormsModule, VscodeTextfieldInputDirective],
  templateUrl: "./pet.component.html",
  styleUrl: "../app.component.css",
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class PetComponent {
  name = new FormControl("");
  species = new FormControl("");
  petObject: any;

  constructor() {
    // Webviews are normally torn down when not visible and re-created when they become visible again.
    // State lets us save information across these re-loads
    const state = vscode.getState() as any;
    if (state) {
      this.updateContent(state.text);
    }
  }

  // Handle messages sent from the extension to the webview
  @HostListener("window:message", ["$event"])
  handleMessage(event: MessageEvent) {
    const message = event.data; // The json data that the extension sent
    switch (message.type) {
      case "update":
        const text = message.text;

        // Update our webview's content
        this.updateContent(text);

        // Then persist state information.
        // This state is returned in the call to `vscode.getState` below when a webview is reloaded.
        vscode.setState({ text });
        return;
    }
  }

  /**
   * Update the data shown in the document in the webview.
   */
  updateContent(text: string) {
    if (text !== "") {
      this.petObject = JSON.parse(text);
      this.name.setValue(this.petObject.name);
      this.species.setValue(this.petObject.species);
    }
  }

  /**
   * Update the document in the extension.
   */
  updateDocument() {
    let name = this.name.value;
    let species = this.species.value;

    // wait 500 ms before updating the document
    // only update if in the meantime no other input was given
    setTimeout(() => {
      if (this.name.value === name && this.species.value === species) {
        this.petObject = {
          name: this.name.value,
          species: this.species.value,
        };

        vscode.postMessage({
          type: "updateDocument",
          text: JSON.stringify(this.petObject, null, 2),
        });
      }
    }, 500);
  }
}

Update the file angular-extension/webview-ui/src/main.ts

Decide which component to use for bootstrapping based on the data-root attribute.
This is actually the crucial step if you want to provide multiple webviews in one extension when you use Angular. The bootstrapping of the standalone component needs to be dynamic, and this is implemented by inspecting an attribute added to the webview html in the extension code.

import { bootstrapApplication } from "@angular/platform-browser";
import { appConfig } from "./app/app.config";
import { PersonComponent } from "./app/person/person.component";
import { PetComponent } from "./app/pet/pet.component";

const currentPath = document.documentElement.getAttribute("data-root");
if (currentPath === "person-root") {
  bootstrapApplication(PersonComponent, appConfig).catch((err) =>
    console.error(err)
  );
} else if (currentPath === "pet-root") {
  bootstrapApplication(PetComponent, appConfig).catch((err) =>
    console.error(err)
  );
}

To verify that it works

Launch the Visual Studio Code Extension(s)
- Open Run and Debug
- Ensure Run Extension is selected in the dropdown
- Click Start Debugging or press F5
Right click on the file created in the previous example in the Explorer
Select Open With… - Angular Pet Editor

This should open the webview with the content of the Angular PetComponent.

React Webview Implementation

To provide multiple webviews in an extension that uses React as webframework, we need to perform similar steps like before with Angular as webframework.

Open the react-extension/package.json

Extend the contributes section to add a Pet editor for the .pet file extension:

"contributes": {
  "customEditors": [
    {
      "viewType": "react-extension.personEditor",
      "displayName": "React Person Editor",
      "selector": [
        {
          "filenamePattern": "*.person"
        }
      ],
      "priority": "option"
    },
    {
      "viewType": "react-extension.petEditor",
      "displayName": "React Pet Editor",
      "selector": [
        {
          "filenamePattern": "*.pet"
        }
      ],
      "priority": "option"
    }
  ]
},

Create a new file react-extension/src/abstractEditor.ts
To avoid that we need to copy a lot of code for the new editor, we create an abstract base class AbstractEditorProvider that will be used by both editor implementations.

Copy the content of react-extension/src/personEditor.ts to react-extension/src/abstractEditor.ts
Rename PersonEditorProvider to AbstractEditorProvider and make it abstract
Remove the viewType constant and the register method
Add an abstract method getRootComponentSelector()
Update getWebviewHtml() to use getRootComponentSelector() as an attribute data-root in the html tag

import * as vscode from "vscode";

export abstract class AbstractEditorProvider
  implements vscode.CustomTextEditorProvider
{
  constructor(private readonly context: vscode.ExtensionContext) {}

  public async resolveCustomTextEditor(
    document: vscode.TextDocument,
    webviewPanel: vscode.WebviewPanel,
    _token: vscode.CancellationToken
  ): Promise<void> {
    // Setup initial content for the webview
    webviewPanel.webview.options = {
      // Enable scripts in the webview
      enableScripts: true,

      // Restrict the webview to only load resources from the `dist` and `webview-ui/build` directories
      localResourceRoots: [
        vscode.Uri.joinPath(this.context.extensionUri, "dist"),
        vscode.Uri.joinPath(this.context.extensionUri, "webview-ui/build"),
      ],
    };

    webviewPanel.webview.html = this.getWebviewHtml(webviewPanel.webview);

    // Hook up event handlers so that we can synchronize the webview with the text document.
    //
    // The text document acts as our model, so we have to sync change in the document to our
    // editor and sync changes in the editor back to the document.
    //
    // Remember that a single text document can also be shared between multiple custom
    // editors (this happens for example when you split a custom editor)

    const changeDocumentSubscription =
      vscode.workspace.onDidChangeTextDocument((e) => {
        if (e.document.uri.toString() === document.uri.toString()) {
          this.updateWebview(webviewPanel, document);
        }
      });

    // Make sure we get rid of the listener when our editor is closed.
    webviewPanel.onDidDispose(() => {
      changeDocumentSubscription.dispose();
    });

    // Receive message from the webview.
    webviewPanel.webview.onDidReceiveMessage((e) => {
      switch (e.type) {
        case "updateDocument":
          this.updateDocument(document, e.text);
          return;
      }
    });

    this.updateWebview(webviewPanel, document);
  }

  /**
   * Updates the webview with the content of the current document.
   * @param webviewPanel The webview panel to post the message to.
   * @param document The current document.
   */
  private updateWebview(
    webviewPanel: vscode.WebviewPanel,
    document: vscode.TextDocument
  ) {
    // Post message with text of the document to the webview
    webviewPanel.webview.postMessage({
      type: "update",
      text: document.getText(),
    });
  }

  /**
   * Applies a set of text edits to a document.
   * @param document The current document.
   * @param text The text to set to the document.
   * @returns A thenable that resolves when the edit could be applied.
   */
  private updateDocument(document: vscode.TextDocument, text: string) {
    const edit = new vscode.WorkspaceEdit();
    edit.replace(
      document.uri,
      new vscode.Range(0, 0, document.lineCount, 0),
      text
    );
    return vscode.workspace.applyEdit(edit);
  }

  /**
   * Get the static html used for the editor webviews.
   */
  private getWebviewHtml(webview: vscode.Webview): string {
    // The CSS file from the React build output
    const stylesUri = webview.asWebviewUri(
      vscode.Uri.joinPath(
        this.context.extensionUri,
        "webview-ui",
        "build",
        "assets",
        "index.css"
      )
    );
    // The JS file from the React build output
    const scriptUri = webview.asWebviewUri(
      vscode.Uri.joinPath(
        this.context.extensionUri,
        "webview-ui",
        "build",
        "assets",
        "index.js"
      )
    );

    const rootSelector = this.getRootComponentSelector();
    const nonce = this.getNonce();

    // Tip: Install the es6-string-html VS Code extension to enable code highlighting below
    return /*html*/ `
    
    ${rootSelector}">
    
      
      
        ${webview.cspSource}; font-src ${webview.cspSource}; style-src ${webview.cspSource}; script-src 'nonce-${nonce}';">
      ${stylesUri}">
    
    
      

    
    `;
  }

  /**
   * Return the selector of the root component to use.
   */
  abstract getRootComponentSelector(): string;

  /**
   * A helper function that returns a unique alphanumeric identifier called a nonce.
   *
   * @remarks This function is primarily used to help enforce content security
   * policies for resources/scripts being executed in a webview context.
   *
   * @returns A nonce
   */
  getNonce() {
    let text = "";
    const possible =
      "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
    for (let i = 0; i < 32; i++) {
      text += possible.charAt(Math.floor(Math.random() * possible.length));
    }
    return text;
  }
}

Update the file react-extension/src/personEditor.ts

Extend AbstractEditorProvider
Call super(context) in the constructor
Add the getRootComponentSelector() method which returns person-root
Delete the other methods that are now defined in AbstractEditorProvider

import * as vscode from "vscode";
import { AbstractEditorProvider } from "./abstractEditor";

export class PersonEditorProvider extends AbstractEditorProvider {
  private static readonly viewType = "react-extension.personEditor";

  constructor(context: vscode.ExtensionContext) {
    super(context);
  }

  public static register(
    context: vscode.ExtensionContext
  ): vscode.Disposable {
    const provider = new PersonEditorProvider(context);
    const providerRegistration = vscode.window.registerCustomEditorProvider(
      PersonEditorProvider.viewType,
      provider
    );
    return providerRegistration;
  }

  getRootComponentSelector(): string {
    return "person-root";
  }
}

Create a new file react-extension/src/petEditor.ts

Copy the content of react-extension/src/personEditor.ts
Rename the class to PetEditorProvider
Update the value of viewType to "react-extension.petEditor"
Update the register() implementation to register the PetEditorProvider
Change the return value of getRootComponentSelector() to pet-root

import * as vscode from "vscode";
import { AbstractEditorProvider } from "./abstractEditor";

export class PetEditorProvider extends AbstractEditorProvider {
  private static readonly viewType = "react-extension.petEditor";

  constructor(context: vscode.ExtensionContext) {
    super(context);
  }

  public static register(
    context: vscode.ExtensionContext
  ): vscode.Disposable {
    const provider = new PetEditorProvider(context);
    const providerRegistration = vscode.window.registerCustomEditorProvider(
      PetEditorProvider.viewType,
      provider
    );
    return providerRegistration;
  }

  getRootComponentSelector(): string {
    return "pet-root";
  }
}

Update react-extension/src/extension.ts

// The module 'vscode' contains the Visual Studio Code extensibility API
// Import the module and reference it with the alias vscode in your code below
import * as vscode from "vscode";
import { PersonEditorProvider } from "./personEditor";
import { PetEditorProvider } from "./petEditor";

// This method is called when your extension is activated
export function activate(context: vscode.ExtensionContext) {
  // Register our custom editor provider
  context.subscriptions.push(PersonEditorProvider.register(context));
  context.subscriptions.push(PetEditorProvider.register(context));
}

// This method is called when your extension is deactivated
export function deactivate() {}

Now that the extension code is prepared for multiple custom editors, the webview needs to be implemented in the React webview-ui structure.

Update react-extension/src/webview-ui/src/global.d.ts and add the VscodeSingleSelect and the VscodeOption web component.
To use custom tag names, you must configure the TypeScript parser to recognize the custom elements. This can be done via a TypeScript definition which is described in Getting Started with Visual Studio Code Extension Development.

import {
  VscodeLabel,
  VscodeTextfield,
  VscodeSingleSelect,
  VscodeOption,
} from "@vscode-elements/elements";

type ElementProps<I> = Partial<Omit<I, keyof HTMLElement>>;
type CustomEventHandler<E> = (e: E) => void;

type WebComponentProps<I extends HTMLElement> = React.DetailedHTMLProps<
  React.HTMLAttributes<I>,
  I
> &
  ElementProps<I>;

declare module "react" {
  namespace JSX {
    interface IntrinsicElements {
      "vscode-label": WebComponentProps<VscodeLabel>;
      "vscode-textfield": WebComponentProps<VscodeTextfield>;
      "vscode-single-select": WebComponentProps<VscodeSingleSelect>;
      "vscode-option": WebComponentProps<VscodeOption>;
    }
  }
}

Rename react-extension/src/webview-ui/src/App.tsx to react-extension/src/webview-ui/src/Person.tsx
In react-extension/src/webview-ui/src/Person.tsx rename the App function to Person
Create a new file react-extension/src/webview-ui/src/Pet.tsx

Copy the content of react-extension/src/webview-ui/src/Person.tsx to the new file and adapt the code to handle a pet instead of a person

import { useState } from "react";
import { vscode } from "./utilities/vscode";
import "./App.css";
import "@vscode-elements/elements/dist/vscode-label";
import "@vscode-elements/elements/dist/vscode-textfield";
import "@vscode-elements/elements/dist/vscode-single-select";
import "@vscode-elements/elements/dist/vscode-option";

function Pet() {
  const [petObject, setPetObject] = useState(loadState);

  /**
   * Load the initial state via vscode API or return an empty object as initial state.
   */
  function loadState() {
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const state = vscode.getState() as any;
    if (state) {
      return JSON.parse(state.text);
    }

    return {
      name: "",
      species: "",
    };
  }

  // Handle messages sent from the extension to the webview
  window.addEventListener("message", (event) => {
    const message = event.data; // The json data that the extension sent
    switch (message.type) {
      case "update": {
        const text = message.text;

        // Update our webview's content
        updateContent(text);

        // Then persist state information.
        // This state is returned in the call to `vscode.getState` below when a webview is reloaded.
        vscode.setState({ text });

        return;
      }
    }
  });

  /**
   * Update the data shown in the document in the webview.
   */
  function updateContent(text: string) {
    if (text !== "") {
      const parsed = JSON.parse(text);
      setPetObject({
        name: parsed.name,
        species: parsed.species,
      });
    }
  }

  /**
   * Update the document in the extension.
   */
  function updateDocument() {
    vscode.postMessage({
      type: "updateDocument",
      text: JSON.stringify(petObject, null, 2),
    });
  }

  return (
    <>
      <main className="main">
        <h1>React Pet Editor</h1>
        <div className="content">
          <div className="pet">
            <div className="row">
              <vscode-label htmlFor="name" className="vscode-label">
                Name:
              </vscode-label>
              <div className="value">
                <vscode-textfield
                  type="text"
                  id="name"
                  className="vscode-textfield"
                  value={petObject.name}
                  onInput={(event) => {
                    const value = event.currentTarget.value;
                    const target = event.currentTarget;
                    // wait 500 ms before updating the document
                    // only update if in the meantime no other input was given
                    setTimeout(() => {
                      if (value === target.value) {
                        petObject.name = value;
                        updateDocument();
                      }
                    }, 500);
                  }}
                />
              </div>
            </div>
            <div className="row">
              <vscode-label htmlFor="species" className="vscode-label">
                Species:
              </vscode-label>
              <div className="value">
                <vscode-single-select
                  id="species"
                  value={petObject.species}
                  onInput={(event) => {
                    const value = event.currentTarget.value;
                    const target = event.currentTarget;
                    // wait 500 ms before updating the document
                    // only update if in the meantime no other input was given
                    setTimeout(() => {
                      if (value === target.value) {
                        petObject.species = value;
                        updateDocument();
                      }
                    }, 500);
                  }}
                >
                  <vscode-option>-</vscode-option>
                  <vscode-option description="bird">Bird</vscode-option>
                  <vscode-option description="cat">Cat</vscode-option>
                  <vscode-option description="dog">Dog</vscode-option>
                </vscode-single-select>
              </div>
            </div>
          </div>
        </div>
      </main>
    </>
  );
}

export default Pet;

Update react-extension/src/webview-ui/src/main.tsx

Decide which component to use as root based on the data-root attribute
This is actually the crucial step if you want to provide multiple webviews in one extension when you use React. The definition of the root component needs to be dynamic, and this is implemented by inspecting an attribute added to the webview html in the extension code.

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import "./index.css";
import Person from "./Person.tsx";
import Pet from "./Pet.tsx";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <RootComponent />
  </StrictMode>
);

// eslint-disable-next-line react-refresh/only-export-components
function RootComponent() {
  const currentPath = document.documentElement.getAttribute("data-root");
  if (currentPath === "person-root") {
    return <Person />;
  } else if (currentPath === "pet-root") {
    return <Pet />;
  }
}

To verify that it works

Launch the Visual Studio Code Extension(s)
- Open Run and Debug
- Ensure Run Extension is selected in the dropdown
- Click Start Debugging or press F5
Right click on the file created in the previous example in the Explorer
Select Open With… - React Pet Editor

This should open the webview with the content of the React Pet component.

Bonus: Automatic Termination of Watch Tasks

In the setup of this project multiple watch tasks are started when you launch the Visual Studio Code Extensions for debugging via Run and Debug or by pressing F5 or F11. I configured the watch tasks as defaultBuildTask to get code changes directly reflected in the running instance. This is similar to the Hot Code Replace debugging technique in Java. After a code change in a webview implementation, the changes can be directly seen by either closing and reopening the webview, or by reloading the webview by pressing F1 - Developer: Reload Webviews. To reload the Extension Development Host after changes in the extension code, you can either click on the debug restart action or press Ctrl + R / Cmd + R in the Extension Development Host window. This makes the development flow a bit more comfortable compared to always having to close and restart the debugging launch configuration.

There is a nasty side effect with this setup. If you close the Extension Development Host, the watch tasks are not automatically stopped. So if you want to start a new debugging session afterwards, nothing happens, because the watch scripts are still running and therefore the patterns that are used to match the started state are not matched in a new start. To make the start of a debug instance work again, you first need to stop the running watch tasks, so they are started freshly. As this is quite annoying when it happens often that you kill the Extension Development Host instead of reloading it, I was searching for a solution. A colleague of mine found a nice solution for this, and I modified it to be even more convenient. Of course I found the necessary information in the web, but you know, the blog posts are my external memory.

To automatically terminate the watch tasks

Open the file .vscode/tasks.json

Add the following Terminate Tasks to the tasks and the terminate input to the inputs

{
"version": "2.0.0",
"tasks": [
  ...
  {
    "label": "Terminate Tasks",
    "command": "echo ${input:terminate}",
    "type": "shell",
    "problemMatcher": [],
    "presentation": {
      "reveal": "never",
      "close": true
    }
  },
],
"inputs": [
  {
    "id": "terminate",
    "type": "command",
    "command": "workbench.action.tasks.terminate",
    "args": "terminateAll"
  }
]
}

The above Terminate Tasks configuration triggers the workbench.action.tasks.terminate command with the argument terminateAll. So actually this kills all running tasks. Via the close property of the presentation task property, we configure that the terminal the tasks runs in is closed the task exits. This way our Terminal list stays clean.

Open the file .vscode/launch.json

Add "postDebugTask": "Terminate Tasks" to the Run Extension configuration

{
"version": "0.2.0",
"configurations": [
  {
    "name": "Run Extension",
    "type": "extensionHost",
    "request": "launch",
    "args": [
      "--extensionDevelopmentPath=${workspaceFolder}/vscode-extension",
      "--extensionDevelopmentPath=${workspaceFolder}/angular-extension",
      "--extensionDevelopmentPath=${workspaceFolder}/react-extension"
    ],
    "outFiles": [
      "${workspaceFolder}/vscode-extension/out/**/*.js",
      "${workspaceFolder}/angular-extension/dist/**/*.js",
      "${workspaceFolder}/react-extension/dist/**/*.js"
    ],
    "preLaunchTask": "${defaultBuildTask}",
    "postDebugTask": "Terminate Tasks"
  },
  ...
]
}

If you now start the debugging instance via the Run Extension launch configuration, you will again see that the three watch scripts are started before the Extension Development Host comes up. If you now stop the Extension Development Host, the watch scripts will be stopped also.

Note: This will also affect the restart behavior of the Extension Development Host. Without the postDebugTask the Extension Development Host will restart while the watch tasks keep running. With the postDebugTask the watch tasks will be killed and also restarted. If you are working on the extension sources and need to restart the Extension Development Host to make the changes visible, it might be annoying that the watch scripts are killed and restarted. But if you are working on the webview sources and don’t need to restart the Extension Development Host, this change might not really be noticable.

Conclusion

With a Vanilla Javascript and HTML webview, it is straight forward to provide multiple webviews in one extension. The webview HTML is provided by each custom editor provider implementation. And the special handling in the Javascript needs to be implemented accordingly.

Using a webframework like Angular or React the crucial fact is to determine the root component dynamically. If you know how this can be done, it is quite easy, but finding out how to achieve this was indeed a journey.

If you are annoyed by watch scripts that keep running after closing the Extension Development Host, the postDebugTask of a launch configuration could be helpful. But there are also use cases where the behavior that is introduced by the postDebugTask could be annoying, e.g. on restarting the Extension Development Host. So you need to use that configuration based on your use cases and personal development/testing preferences.

The sources for this and the following tutorials are located in my Github repository.

Getting Started with Visual Studio Code Extension Development

2025-03-05T00:00:00+00:00

Over the past years I wrote several blog posts about Java, Eclipse and OSGi. While I still like those technologies very much, I can’t ignore that Visual Studio Code, Eclipse Theia and several web technologies became more important. The following blog posts will therefore cover these topics, to help developers like me, that need to switch and provide tools based on Visual Studio Code and/or Eclipse Theia.

I will start my new series of blog post with this tutorial about Visual Studio Code Extension development. This tutorial is a Getting Started for developing Visual Studio Code Extensions that contribute a custom editor using a webview. It is intended for developers that are not familiar with Visual Studio Code Extension development and covers the following topics:

Project setup using a Dev Container
Developing a custom editor using a webview with Vanilla HTML and Javascript
Developing a custom editor using a webview with Angular
Developing a custom editor using a webview with React
Usage of the VSCode Elements web component library to get an almost native Visual Studio Code look and feel

Let’s start!

Dev Container

When starting a new project, it is recommended to define a Dev Container to

reduce the time a new developer in the project needs to setup the environment
encapsulate the development environment for the project

This makes it easy to get a working environment, without having to install all required tools locally. To make this work you of course need to have at least:

Working on Windows you can either use Docker Desktop, or if you work inside a WSL you can also install Docker in the WSL distribution directly. Note that on Windows it is recommended to checkout the sources in the WSL and start Visual Studio Code from there. This improves the performance of the Dev Container, because there is no performance loss caused by disk performance issues when transforming from a Windows file system to a Linux file system in the container. See Improve disk performance for further information and alternatives.

Note:
A possible WSL setup is described in the WSL Setup tutorial in this repository.

Prepare the project to provide a Dev Container for the development:

Create a folder .devcontainer

Create a file devcontainer.json
The simplest form of a devcontainer.json for starting to develop a Visual Studio Code Extension could look like this:

// For format details, see https://aka.ms/devcontainer.json. For config options, see the
// README at: https://github.com/devcontainers/templates/tree/main/src/typescript-node
{
  "name": "Node.js & TypeScript",
  // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
  "image": "mcr.microsoft.com/devcontainers/typescript-node:1-20-bookworm",
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "amodio.tsl-problem-matcher",
        "ms-vscode.extension-test-runner"
      ]
    }
  },
  // Features to add to the dev container. More info: https://containers.dev/features.
  // "features": {},
  // Use 'forwardPorts' to make a list of ports inside the container available locally.
  // "forwardPorts": [],
  // Enable to connect the dev container to the host network, needed in case of WSL with networkingMode=mirrored
  // "runArgs": ["--network=host"],
  // Use 'postCreateCommand' to run commands after the container is created.
  "postCreateCommand": "npm install -g npm yo generator-code @vscode/vsce"
  // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
  // "remoteUser": "root"
}

The above devcontainer.json uses the predefined Dev Container template for Typescript and Node, adds the recommended extensions and installs a new version of npm, the code generator for Visual Studio Code Extensions and the Visual Studio Code Extension Manager used for packaging.

Dependent on the framework you want to use for implementing the webview, you might want to add additional extensions, e.g. the Angular Language Service angular.ng-template.

I also have some Visual Studio Code Extension that I like, for example the Markdown All in One and the Task Explorer. But of course, the selection of Visual Studio Code Extensions is opinionated, and therefore feel free to add or remove dependent on your project needs.

To further customize the Dev Container, you basically have three options:

extend the postCreateCommand in the devcontainer.json
This makes sense if you have only few commands to execute, like the installation of the code generator. But it becomes quite uncomfortable when you want to execute several commands.
use a script file that contains the commands to execute and call that script file in postCreateCommand, e.g. like this "postCreateCommand": "bash ./.devcontainer/postCreateCommand.sh"
This has the advantage that you can call multiple commands in a bash script which is more comfortable than writing it in a single line in JSON.
use a dedicated Dockerfile that extends the default dev container
This makes especially sense if you need to add additional files or need to extend the default dev container in several ways.

Once you are done with creating the Dev Container, open the workspace in the Dev Container:

Press F1 - Dev Containers: Reopen in Container

Further information about Visual Studio Code development container:

Project Structure

In the following sections we will create Visual Studio Code Extensions that provide a custom editor using the Webview API. I will guide you through the creation of the projects by using different frameworks. The reason is to get an idea about how to use different Javascript frameworks for the webview development and to compare the approaches.

The ideas for the following descriptions are based on the Webview UI Toolkit Sample Extensions repository.

Note:
The Webview UI Toolkit had the intention to provide a component library for building webview-based extensions in Visual Studio Code. The main idea was to allow the creation of user interfaces that look like the native user interface of Visual Studio Code.

The Webview UI Toolkit itself is deprecated, but the project structures in the examples repository are still interesting. Basically you create a new Visual Studio Code Extension project, and inside that project you create a subfolder for the webview-ui.

The following implementations will be shown:

Webview with Vanilla HTML and Javascript
Angular Webview Implementation
React Webview Implementation

Additionally I will show how to use the VSCode Elements component library for implementing a webview.

Note:
If you are only interested in one of the implementations, you can jump directly to the corresponding section.

Visual Studio Code Extension Project

After the Dev Container is ready, we can start to create the project structure.

As mentioned before, in this tutorial the same editor will be created using different frameworks. But the first steps are always the same:

Create the Visual Studio Code Extension project
Implement the Visual Studio Code Extension
In our case this means to contribute a custom editor.
Implement the webview
This is specific to the used framework.

Create the Visual Studio Code Extension project

First create a new Visual Studio Code Extension project:

Open a Terminal and execute the following command
```
yo code
```

Answer the questions of the wizard for example like shown below:

# ? What type of extension do you want to create? New Extension (TypeScript)
# ? What's the name of your extension? vscode-extension
# ? What's the identifier of your extension? vscode-extension
# ? What's the description of your extension? LEAVE BLANK
# ? Initialize a git repository? N
# ? Which bundler to use? unbundled
# ? Which package manager to use? npm

# ? Do you want to open the new folder with Visual Studio Code? Skip

Further information:

Your First Extension

A new subfolder vscode-extension will be created that contains the sources of the Visual Studio Code Extension. We keep the subfolder as we will add further projects in this repository. To make the setup work with the Visual Studio Code Extension in a subfolder, the following modifications are needed:

In the opened Terminal move the vscode-extension/.vscode folder to the root folder. This is necessary so the Visual Studio Code settings are resolved from the project root and not a subfolder.
```
mv vscode-extension/.vscode .
```

Edit the .vscode/launch.json and add the project folder to the extensionDevelopmentPath and the outFiles

"args": [
	"--extensionDevelopmentPath=${workspaceFolder}/vscode-extension"
],
"outFiles": [
	"${workspaceFolder}/vscode-extension/out/**/*.js"
],

Edit the .vscode/tasks.json and change the working directory the existing task to the project directory
```
"options": {
  "cwd": "${workspaceFolder}/vscode-extension"
}
```

To verify that the setup works, open the file vscode-extension/src/extension.ts and press F5 to start a new Visual Studio Code instance with the extension, open the Command Palette (CTRL + SHIFT + P) and search for Hello to run the command.

Create a .gitignore in the repository root
As we did not initialize a git repository by the code generator, there is no .gitignore. We therefore need to create one ourselves to ensure that not too much will be added to the repository.
```
# Compiled output
dist
out
tmp
out-tsc

# Node
node_modules

# Visual Studio Code
.vscode/*
!.vscode/settings.json
!.vscode/tasks.json
!.vscode/launch.json
!.vscode/extensions.json
.history/*
*.vsix
```

Implement the Visual Studio Code Extension

Instead of showing a message or opening a simple example view, we will create a custom editor.

Open the vscode-extension/package.json

Replace the contributes section with the following snippet:

"contributes": {
  "customEditors": [
    {
      "viewType": "vscode-extension.personEditor",
      "displayName": "Visual Studio Code Person Editor",
      "selector": [
        {
          "filenamePattern": "*.person"
        }
      ],
      "priority": "default"
    }
  ]
},

Create a new file vscode-extension/src/personEditor.ts

Implement vscode.CustomTextEditorProvider

import * as vscode from "vscode";

export class PersonEditorProvider
  implements vscode.CustomTextEditorProvider
{
  private static readonly viewType = "vscode-extension.personEditor";

  constructor(private readonly context: vscode.ExtensionContext) {}
}

Add the following register() method that is used to register the provider via vscode.window.registerCustomEditorProvider()

public static register(context: vscode.ExtensionContext): vscode.Disposable {
  const provider = new PersonEditorProvider(context);
  const providerRegistration = vscode.window.registerCustomEditorProvider(
    PersonEditorProvider.viewType,
    provider
  );
  return providerRegistration;
}

Implement resolveCustomTextEditor() that uses a webview

public async resolveCustomTextEditor(
  document: vscode.TextDocument,
  webviewPanel: vscode.WebviewPanel,
  _token: vscode.CancellationToken
): Promise<void> {
  // Setup initial content for the webview
  webviewPanel.webview.options = {
    // Enable scripts in the webview
    enableScripts: true,
  };

  webviewPanel.webview.html = this.getWebviewHtml(webviewPanel.webview);

  // Hook up event handlers so that we can synchronize the webview with the text document.
  //
  // The text document acts as our model, so we have to sync change in the document to our
  // editor and sync changes in the editor back to the document.
  //
  // Remember that a single text document can also be shared between multiple custom
  // editors (this happens for example when you split a custom editor)

  const changeDocumentSubscription = vscode.workspace.onDidChangeTextDocument(
    (e) => {
      if (e.document.uri.toString() === document.uri.toString()) {
        this.updateWebview(webviewPanel, document);
      }
    }
  );

  // Make sure we get rid of the listener when our editor is closed.
  webviewPanel.onDidDispose(() => {
    changeDocumentSubscription.dispose();
  });

  this.updateWebview(webviewPanel, document);
}

Implement the bidirectional messaging between webview and editor

Add the following code in resolveCustomTextEditor()

// Receive message from the webview.
webviewPanel.webview.onDidReceiveMessage((e) => {
  switch (e.type) {
    case "updateDocument":
      this.updateDocument(document, e.text);
      return;
  }
});

Add the following methods to the PersonEditorProvider

/**
 * Updates the webview with the content of the current document.
* @param webviewPanel The webview panel to post the message to.
* @param document The current document.
*/
private updateWebview(
  webviewPanel: vscode.WebviewPanel,
  document: vscode.TextDocument
) {
  // Post message with text of the document to the webview
  webviewPanel.webview.postMessage({
    type: "update",
    text: document.getText(),
  });
}

/**
 * Applies a set of text edits to a document.
* @param document The current document.
* @param text The text to set to the document.
* @returns A thenable that resolves when the edit could be applied.
*/
private updateDocument(document: vscode.TextDocument, text: string) {
  const edit = new vscode.WorkspaceEdit();
  edit.replace(
    document.uri,
    new vscode.Range(0, 0, document.lineCount, 0),
    text
  );
  return vscode.workspace.applyEdit(edit);
}

/**
 * Get the static html used for the editor webviews.
*/
private getWebviewHtml(webview: vscode.Webview): string {
  // TODO implement
  return "";
}

Change vscode-extension/src/extension.ts

Replace the existing example code with the following snippet

// The module 'vscode' contains the Visual Studio Code extensibility API
// Import the module and reference it with the alias vscode in your code below
import * as vscode from "vscode";
import { PersonEditorProvider } from "./personEditor";

// This method is called when your extension is activated
export function activate(context: vscode.ExtensionContext) {
  // Register our custom editor provider
  context.subscriptions.push(PersonEditorProvider.register(context));
}

// This method is called when your extension is deactivated
export function deactivate() {}

Implement the webview

Note:
The following code is inspired and adapted from Custom Editor API Samples.

Open the file vscode-extension/src/personEditor.ts

Replace the getWebviewHtml() method that was added before

Add the getNonce() method to PersonEditorProvider

/**
 * Get the static html used for the editor webviews.
*/
private getWebviewHtml(webview: vscode.Webview): string {
  // Local path to script and css for the webview
  const stylesUri = webview.asWebviewUri(
    vscode.Uri.joinPath(this.context.extensionUri, "media", "styles.css")
  );
  const scriptUri = webview.asWebviewUri(
    vscode.Uri.joinPath(this.context.extensionUri, "media", "main.js")
  );

  const nonce = this.getNonce();

  // Tip: Install the es6-string-html Visual Studio Code extension to enable code highlighting below
  return /* html */ `
  
  
  
      

      
      ${webview.cspSource}; font-src ${webview.cspSource}; style-src ${webview.cspSource}; script-src 'nonce-${nonce}';">

      

      ${stylesUri}" rel="stylesheet" />

      Person EditorVisual Studio Code Person EditorFirstname:
            
          
Lastname:
            
          

  
  `;
}

/**
 * A helper function that returns a unique alphanumeric identifier called a nonce.
*
* @remarks This function is primarily used to help enforce content security
* policies for resources/scripts being executed in a webview context.
*
* @returns A nonce
*/
getNonce() {
  let text = "";
  const possible =
    "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
  for (let i = 0; i < 32; i++) {
    text += possible.charAt(Math.floor(Math.random() * possible.length));
  }
  return text;
}

Create the folder vscode-extension/media

Create the file vscode-extension/media/main.js with the following content

// Script run within the webview itself.
(function () {
  // Get a reference to the Visual Studio Code webview api.
  // We use this API to post messages back to our extension.

  const vscode = acquireVsCodeApi();

  const personContainer = /** @type {HTMLElement} */ (
    document.querySelector(".person")
  );

  const errorContainer = document.createElement("div");
  document.body.appendChild(errorContainer);
  errorContainer.className = "error";
  errorContainer.style.display = "none";

  /**
   * Render the document in the webview.
   */
  function updateContent(/** @type {string} */ text) {
    let json;
    try {
      if (!text) {
        text = "{}";
      }
      json = JSON.parse(text);
    } catch {
      personContainer.style.display = "none";
      errorContainer.innerText = "Error: Document is not valid json";
      errorContainer.style.display = "";
      return;
    }
    personContainer.style.display = "";
    errorContainer.style.display = "none";

    const firstname = document.getElementById("firstname");
    const lastname = document.getElementById("lastname");

    if (json.firstname) {
      firstname.value = json.firstname;
    }
    if (json.lastname) {
      lastname.value = json.lastname;
    }

    firstname.oninput = () => {
      let value = firstname.value;
      // wait 500 ms before updating the document
      // only update if in the meantime no other input was given
      setTimeout(() => {
        if (value === firstname.value) {
          json.firstname = firstname.value;
          vscode.postMessage({
            type: "updateDocument",
            text: JSON.stringify(json, null, 2),
          });
        }
      }, 500);
    };

    lastname.oninput = () => {
      let value = lastname.value;
      // wait 500 ms before updating the document
      // only update if in the meantime no other input was given
      setTimeout(() => {
        if (value === lastname.value) {
          json.lastname = lastname.value;
          vscode.postMessage({
            type: "updateDocument",
            text: JSON.stringify(json, null, 2),
          });
        }
      }, 500);
    };
  }

  // Handle messages sent from the extension to the webview
  window.addEventListener("message", (event) => {
    const message = event.data; // The json data that the extension sent
    switch (message.type) {
      case "update":
        const text = message.text;

        // Update our webview's content
        updateContent(text);

        // Then persist state information.
        // This state is returned in the call to `vscode.getState` below when a webview is reloaded.
        vscode.setState({ text });

        return;
    }
  });

  // Webviews are normally torn down when not visible and re-created when they become visible again.
  // State lets us save information across these re-loads
  const state = vscode.getState();
  if (state) {
    updateContent(state.text);
  }
})();

Create the file vscode-extension/media/styles.css with the following content
```
label {
  font-weight: 600;
  display: block;
}
```

If everything is correctly in place, you can verify the editor by

pressing F5 to start a new Visual Studio Code instance with the extension
opening a folder somewhere
Create a folder example in the home directory of the node user in the Dev Container for example.
creating a new file named homer.person

Now a webview with two input fields should be visible.

enter values for Firstname and Lastname
Save via CTRL + S
Right click on the created file in the Explorer
Select Open With… - Text Editor

The default text editor should open with the JSON content of the created file.

Further information about the used API and official examples:

Install scripts

When new developers in the project check out the repository and open it in a Dev Container, they first need to run the npm commands to install the project dependencies. This can be also automated via scripts and a Dev Container configuration.

Create a package.json in the repository root

{
  "name": "vscode-theia-cookbook",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "install:all": "cd vscode-extension && npm install"
  }
}

Execute the script on postCreateCommand
- If you use the postCreateCommand directly, open .devcontainer/devcontainer.json and update the instruction
```
"postCreateCommand": "npm install -g npm yo generator-code @vscode/vsce; npm run install:all"
```
- If you use a init shell script, add the following instruction at the end of the script file
```
npm run install:all
```

If you now rebuild the Dev Container, you will notice that at the npm install scripts are automatically executed.

VSCode Elements Lite

You might have noticed that the input fields in the webview do not look like the input fields in Visual Studio Code, e.g. in the Settings. To achieve this, we would need to spend quite some time in the definition of the CSS. And of course we need to use the various CSS variables defined in Visual Studio Code.

To avoid this effort, we can also use the VSCode Elements component library, or in case of vanilla HTML and CSS, VSCode Elements Lite.

As a first step, we will only use the styling variant by using VSCode Elements Lite.

Add @vscode-elements/elements-lite as a dependency in the package.json and reference the CSS files in the webview HTML.

Open a Terminal
Switch to the vscode-extension folder
Install @vscode-elements/elements-lite as a dependency
```
npm install @vscode-elements/elements-lite
```

Open the file vscode-extension/src/personEditor.ts

Resolve the URIs to the VSCode Elements Lite CSS files
Add the references to the CSS files in the section of the HTML content

Add class="vscode-label" to the label tags, and class="vscode-textfield" to the input fields

/**
 * Get the static html used for the editor webviews.
 */
private getWebviewHtml(webview: vscode.Webview): string {
  // Local path to script and css for the webview
  const stylesUri = webview.asWebviewUri(
    vscode.Uri.joinPath(this.context.extensionUri, "media", "styles.css")
  );
  const scriptUri = webview.asWebviewUri(
    vscode.Uri.joinPath(this.context.extensionUri, "media", "main.js")
  );

  const labelUri = webview.asWebviewUri(
    vscode.Uri.joinPath(
      this.context.extensionUri,
      "node_modules",
      "@vscode-elements/elements-lite",
      "components",
      "label",
      "label.css"
    )
  );

  const textfieldUri = webview.asWebviewUri(
    vscode.Uri.joinPath(
      this.context.extensionUri,
      "node_modules",
      "@vscode-elements/elements-lite",
      "components",
      "textfield",
      "textfield.css"
    )
  );

  const nonce = this.getNonce();

  // Tip: Install the es6-string-html Visual Studio Code extension to enable code highlighting below
  return /* html */ `
  
  
  
      

      
      ${webview.cspSource}; font-src ${webview.cspSource}; style-src ${webview.cspSource}; script-src 'nonce-${nonce}';">

      

      ${stylesUri}" rel="stylesheet" />
      ${labelUri}" rel="stylesheet" />
      ${textfieldUri}" rel="stylesheet" />

      Person EditorVisual Studio Code Person EditorFirstname:
          
        
Lastname:
          
        

  
  `;
}

If you now restart the application, the input fields in the webview of the custom editor will look like native Visual Studio Code components.

VSCode Elements

If you like to use the Javascript enabled web components, you can use the VSCode Elements component library.

Add @vscode-elements/elements as a dependency in the package.json and reference the CSS files in the webview HTML.

Open a Terminal
Switch to the vscode-extension folder
Install @vscode-elements/elements as a dependency
```
npm install @vscode-elements/elements
```

Open the file vscode-extension/src/personEditor.ts

Resolve the URI to the VSCode Elements bundled version Javascript file
Add the reference to the Javascript file in the section of the HTML content and use the attribute type="module"

Replace the label tag with vscode-label, and the input tag with vscode-textfield

/**
 * Get the static html used for the editor webviews.
 */
private getWebviewHtml(webview: vscode.Webview): string {
  // Local path to script and css for the webview
  const stylesUri = webview.asWebviewUri(
    vscode.Uri.joinPath(this.context.extensionUri, "media", "styles.css")
  );
  const scriptUri = webview.asWebviewUri(
    vscode.Uri.joinPath(this.context.extensionUri, "media", "main.js")
  );

  const elementsUri = webview.asWebviewUri(
    vscode.Uri.joinPath(
      this.context.extensionUri,
      "node_modules",
      "@vscode-elements/elements",
      "dist",
      "bundled.js"
    )
  );

  const nonce = this.getNonce();

  // Tip: Install the es6-string-html Visual Studio Code extension to enable code highlighting below
  return /* html */ `
  
  
  
      

      
      ${webview.cspSource}; font-src ${webview.cspSource}; style-src ${webview.cspSource}; script-src 'nonce-${nonce}';">

      

      ${stylesUri}" rel="stylesheet" />

      Person EditorVisual Studio Code Person EditorFirstname:
            
          
Lastname:
            
          

  
  `;
}

If you now restart the application, the input fields in the webview of the custom editor will look and behave like native Visual Studio Code components.

Angular Webview Implementation

The above steps showed how to create a basic Visual Studio Code Extension with vanilla HTML, Javascript and CSS. If the user interface is more complicated than two simple input fields, this can become quite complicated. In such a case it can be interesting to use a Javascript framework for the implementation of the webview.

In the following chapter we create an Angular project that serves as the webview frontend of the Visual Studio Code Extension.

Note:
The following description is based on the vscode-webview-ui-toolkit-samples Hello World (Angular) example. I reused several parts of the sample code and adapted it where necessary.
Also note that I am not an expert in developing Angular applications. So probably the following sample can be more efficient, but the goal is to help getting started in setting up a Visual Studio Code Extension with Angular webview.

Add the Angular related extensions and configurations to the Dev Container
- Edit the .devcontainer/devcontainer.json and add the angular.ng-template to the customizations/vscode/extensions
- Edit the npm install -g command to additionally install @angular/cli
  Dependent on your setup, this is either in the postCreateCommand of the devcontainer.json or in the postCreateCommand.sh script file.
- Optional:
  In case you use the postCreateCommand.sh script file, you can also add the following two instructions to load the Angular CLI autocompletion by default
```
echo '# Load Angular CLI autocompletion.' >> ~/.bashrc
echo 'source <(ng completion script)' >> ~/.bashrc
```
- Edit the .vscode/extension.json and add the angular.ng-template to the recommendations
- Rebuild the Dev Container
  Press F1 - Dev Containers: Rebuild Container

Create a new Visual Studio Code Extension project.

Open a Terminal and execute the following command
```
yo code
```

Answer the questions of the wizard for example like shown below:

# ? What type of extension do you want to create? New Extension (TypeScript)
# ? What's the name of your extension? angular-extension
# ? What's the identifier of your extension? angular-extension
# ? What's the description of your extension? LEAVE BLANK
# ? Initialize a git repository? N
# ? Which bundler to use? unbundled
# ? Which package manager to use? npm

# ? Do you want to open the new folder with Visual Studio Code? Skip

Delete the created angular-extension/.vscode folder
```
rm -rf angular-extension/.vscode
```

Open the .vscode/launch.json

Add the extensionDevelopmentPath to the newly created angular-extension to the args get both extensions started on launch

Add the path to the build result directory of the newly created angular-extension to the outFiles

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Run Extension",
      "type": "extensionHost",
      "request": "launch",
      "args": [
        "--extensionDevelopmentPath=${workspaceFolder}/vscode-extension",
        "--extensionDevelopmentPath=${workspaceFolder}/angular-extension"
      ],
      "outFiles": [
        "${workspaceFolder}/vscode-extension/out/**/*.js",
        "${workspaceFolder}/angular-extension/out/**/*.js"
      ],
      "preLaunchTask": "${defaultBuildTask}"
    }
  ]
}

Create a new ng application as described in Create a workspace and initial application.
It is created inside the Visual Studio Code Extension project folder, as it serves as the implementation of the webview.
- Open a Terminal
- Switch to the angular-extension folder
- Execute the following command to create the ng application
```
ng new webview-ui
```
- Answer the questions of the wizard for example like shown below:
```
# ? Would you like to share pseudonymous usage data ... N
# ? Which stylesheet format would you like to use? CSS
# ? Do you want to enable Server-Side Rendering (SSR) and Static Site Generation (SSG/Prerendering)? N
```

This command creates a new Angular project in the folder angular-extension/webview-ui with Static Site Generation.

Of course this creates much more than we need for our setup. Therefore we need to cleanup as a next step.

If no git repository is initialized already, it will be done automatically for the webview-ui folder. In that case delete the generated .git folder.
```
rm -rf webview-ui/.git
```

Transfer the generated content in angular-extension/webview-ui/.vscode to the files in .vscode.

launch.json
Copy the two configurations to .vscode/launch.json and add the webRoot setting

{
  "name": "ng serve",
  "type": "chrome",
  "request": "launch",
  "preLaunchTask": "npm: start",
  "url": "http://localhost:4200/",
  "webRoot": "${workspaceFolder}/angular-extension/webview-ui"
},
{
  "name": "ng test",
  "type": "chrome",
  "request": "launch",
  "preLaunchTask": "npm: test",
  "url": "http://localhost:9876/debug.html",
  "webRoot": "${workspaceFolder}/angular-extension/webview-ui"
}

tasks.json
Copy the two configurations to .vscode/tasks.json and add the cwd option

{
  "type": "npm",
  "script": "start",
  "isBackground": true,
  "problemMatcher": {
    "owner": "typescript",
    "pattern": "$tsc",
    "background": {
      "activeOnStart": true,
      "beginsPattern": {
        "regexp": "(.*?)"
      },
      "endsPattern": {
        "regexp": "bundle generation complete"
      }
    }
  },
  "options": {
    "cwd": "${workspaceFolder}/angular-extension/webview-ui"
  }
},
{
  "type": "npm",
  "script": "test",
  "isBackground": true,
  "problemMatcher": {
    "owner": "typescript",
    "pattern": "$tsc",
    "background": {
      "activeOnStart": true,
      "beginsPattern": {
        "regexp": "(.*?)"
      },
      "endsPattern": {
        "regexp": "bundle generation complete"
      }
    }
  },
  "options": {
    "cwd": "${workspaceFolder}/angular-extension/webview-ui"
  }
}

After the configurations are transfered, the generated .vscode folder can be deleted from the webview-ui folder
```
rm -rf webview-ui/.vscode
```
Update the angular-extension/webview-ui/package.json
- Change the name to angular-webview-ui

To verify that the setup works, you can now either run the task via

Press F1 - Tasks: Run Task - npm:start
Run the launch configuration
- Open Run and Debug
- Select ng serve in the dropdown
- Click Start Debugging or press F5

This will start the ng application and host it via http://localhost:4200.

Prepare the NG Application as webview

In the next steps the two projects need to be configured so the NG application can be used as webview in the Visual Studio Code Extension.

Update angular-extension/tsconfig.json
- Change the outDir to ./dist
  This might not be really necessary, but having a good naming convention for the folders helps in understanding the structure. The dist folder will contain the content that gets distributed in the packaged Visual Studio Code Extension.
- Add DOM to the lib configuration
- Configure exclude to avoid node_modules and webview-ui being included in the codebase
```
{
  "compilerOptions": {
    "module": "Node16",
    "target": "ES2022",
    "outDir": "./dist",
    "lib": ["ES2022", "DOM"],
    "sourceMap": true,
    "rootDir": "src",
    "strict": true
  },
  "exclude": ["node_modules", "webview-ui"]
}
```
Update angular-extension/package.json
- Change main to point to ./dist/extension.js
Update .vscode/launch.json
- Correct the outFiles value to "${workspaceFolder}/angular-extension/dist/**/*.js"

Update angular-extension/.vscodeignore to ignore all webview-ui files except the build directory

# Ignore extension configs
.vscode/**

# Ignore test files
.vscode-test/**
**/.vscode-test.*
dist/test/**

# Ignore source code
src/**

# Ignore all webview-ui files except the build directory
node_modules/**
webview-ui/**
!webview-ui/build/**

# Ignore Misc
.yarnrc
vsc-extension-quickstart.md
**/.gitignore
**/tsconfig.json
**/vite.config.ts
**/.eslintrc.json
**/*.map
**/*.ts

Update angular-extension/webview-ui/tsconfig.json
- Add the following configurations in the compilerOptions
```
"baseUrl": "./",
"lib": ["ES2022", "dom"],
"sourceMap": true,
"declaration": false
```

Update angular-extension/webview-ui/angular.json

Set the schematics to the following

"schematics": {
  "@schematics/angular:application": {
    "strict": true
  }
},

Change the builder from application to browser-esbuild

"builder": "@angular-devkit/build-angular:browser-esbuild",
"options": {
  "outputPath": "build",
  "index": "src/index.html",
  "main": "src/main.ts",
  "polyfills": ["zone.js"],
  "tsConfig": "tsconfig.app.json",
  "assets": [
    {
      "glob": "**/*",
      "input": "public"
    }
  ],
  "styles": ["src/styles.css"],
  "scripts": []
},

Ensure that the outputHashing is set to none for the production and the development configuration, otherwise resources can not be referenced in the webview correctly.
```
"outputHashing": "none"
```

Update angular-extension/webview-ui/.gitignore
- Add the /build folder
After we changed the output folder to dist you can delete the folder angular-extension/out if it was already created.
Remove the RouterOutlet
This is necessary to make the usage of assets from third-party modules that are transfered to the media folder work correctly.
- Update angular-extension/webview-ui/src/app/app.component.html
  - Remove usage (bottom of the file)
- Update angular-extension/webview-ui/src/app/app.component.ts
  - Remove the RouterOutlet import
- Update angular-extension/webview-ui/src/app/app.config.ts
  - Remove the router configuration
    import { ApplicationConfig, provideZoneChangeDetection, } from "@angular/core"; export const appConfig: ApplicationConfig = { providers: [provideZoneChangeDetection({ eventCoalescing: true })], };
- Delete angular-extension/webview-ui/src/app/app.routes.ts
Test if the build succeeds
- Open a Terminal
- Switch to the angular-extension/webview-ui folder
- Call ng build
  This should create the folder angular-extension/webview-ui/build
- Switch to the angular-extension folder
- Call npm run compile
  This should create the folder angular-extension/dist.

Use the NG Application as webview

The next step is to use the NG Application as a Visual Studio Code Extension WebView. For this we need to perform the same steps as described previously in Implement the Visual Studio Code Extension.

Open the angular-extension/package.json

Replace the contributes section with the following snippet:

"contributes": {
  "customEditors": [
    {
      "viewType": "angular-extension.personEditor",
      "displayName": "Angular Person Editor",
      "selector": [
        {
          "filenamePattern": "*.person"
        }
      ]
    }
  ]
},

Create a new file angular-extension/src/personEditor.ts

Copy the content from vscode-extension/src/personEditor.ts
Note:
If you have not created that file in the previous vanilla HTML, CSS, Javascript part, follow the steps in Implement the Visual Studio Code Extension to create the content of the file.

Change the value of viewType to angular-extension.personEditor

private static readonly viewType = "angular-extension.personEditor";

Optional:
Extend the webview.options to restrict the webview to only load resources from dist and webview-ui/build directories

// Setup initial content for the webview
webviewPanel.webview.options = {
  // Enable scripts in the webview
  enableScripts: true,

  // Restrict the webview to only load resources from the `dist` and `webview-ui/build` directories
  localResourceRoots: [
    vscode.Uri.joinPath(this.context.extensionUri, "dist"),
    vscode.Uri.joinPath(this.context.extensionUri, "webview-ui/build"),
  ],
};

Change the implementation of getWebviewHtml() so that it basically returns the same HTML as in angular-extension/webview-ui/src/index.html. But instead of relative URLs to resources like CSS and the Javascript files, special WebView URIs are used. This is necessary so the resources can be correctly resolved inside a webview, which is described in Loading local content.

/**
 * Get the static html used for the editor webviews.
 */
private getWebviewHtml(webview: vscode.Webview): string {
  // The CSS file from the Angular build output
  const stylesUri = webview.asWebviewUri(
    vscode.Uri.joinPath(
      this.context.extensionUri,
      "webview-ui",
      "build",
      "styles.css"
    )
  );
  // The JS files from the Angular build output
  const polyfillsUri = webview.asWebviewUri(
    vscode.Uri.joinPath(
      this.context.extensionUri,
      "webview-ui",
      "build",
      "polyfills.js"
    )
  );
  const scriptUri = webview.asWebviewUri(
    vscode.Uri.joinPath(
      this.context.extensionUri,
      "webview-ui",
      "build",
      "main.js"
    )
  );

  const nonce = this.getNonce();

  // Tip: Install the es6-string-html VS Code extension to enable code highlighting below
  return /*html*/ `
      
      
      
          
          
          ${webview.cspSource} 'unsafe-inline'; font-src ${webview.cspSource}; img-src ${webview.cspSource}; script-src 'nonce-${nonce}';">
          ${stylesUri}">
          Person Editor
      
      
          
          
          
      
      
    `;
}

Change the content of angular-extension/src/extension.ts

Replace the content with the following code

// The module 'vscode' contains the Visual Studio Code extensibility API
// Import the module and reference it with the alias vscode in your code below
import * as vscode from "vscode";
import { PersonEditorProvider } from "./personEditor";

// This method is called when your extension is activated
export function activate(context: vscode.ExtensionContext) {
  // Register our custom editor provider
  context.subscriptions.push(PersonEditorProvider.register(context));
}

// This method is called when your extension is deactivated
export function deactivate() {}

Script Updates

We now have a NG application project inside a Visual Studio Code Extension project. The build and run scripts are not automatically connected. For example, if you change code in the NG application and then launch the Visual Studio Code Extension, the changes are not automatically reflected. This is because the Visual Studio Code Extension is using the build results of the NG Application, and not the sources.

To connect the two projects, we need to update the scripts section in angular-extension/package.json

Note:
The watch script needs to execute the watch operations in parallel and not sequentially. While one solution to this could be the usage of & instead of && on a Unix system, a better and OS independent solution is the usage of concurrently.

Add concurrently as a devDependency to the angular-extension/package.json
- Open a Terminal
- Switch to the angular-extension folder
- Execute the following command
```
npm i -D concurrently
```

Open angular-extension/package.json

Add scripts for the webview-ui

"start:webview": "npm --prefix webview-ui run start",
"build:webview": "npm --prefix webview-ui run build",
"watch:webview": "npm --prefix webview-ui run watch",

Update vscode:prepublish to call the build:webview script additionally

"vscode:prepublish": "npm run build:webview && npm run compile",

Update the watch script to call also watch:webview by using concurrently

"watch": "concurrently --kill-others \"npm run watch:webview\" \"tsc -watch -p ./\"",

To make the updated watch script also work when launching the extension, the corresponding task in .vscode/tasks.json needs to be updated.

If you only want to watch the angular-extension, update the configuration like this (notice the endsPattern). Replace the npm:watch script at the top of the tasks.json.

{
  "type": "npm",
  "script": "watch",
  "problemMatcher": {
    "base": "$tsc-watch",
    "background": {
      "activeOnStart": true,
      "beginsPattern": {
        "regexp": "(.*?)"
      },
      "endsPattern": {
        "regexp": "bundle generation complete"
      }
    }
  },
  "isBackground": true,
  "presentation": {
    "reveal": "never"
  },
  "group": {
    "kind": "build",
    "isDefault": true
  },
  "options": {
    "cwd": "${workspaceFolder}/angular-extension"
  }
},

If you want to watch the vscode-extension and the angular-extension at the same time, update the configuration like this:

{
  "label": "Watch Extensions",
  "group": {
    "kind": "build",
    "isDefault": true
  },
  "dependsOn": ["VS Code Extension Watch", "Angular Extension Watch"]
},
{
  "label": "VS Code Extension Watch",
  "type": "shell",
  "command": "npm run watch",
  "problemMatcher": "$tsc-watch",
  "isBackground": true,
  "presentation": {
    "reveal": "never"
  },
  "group": {
    "kind": "build"
  },
  "options": {
    "cwd": "${workspaceFolder}/vscode-extension"
  }
},
{
  "label": "Angular Extension Watch",
  "type": "shell",
  "command": "npm run watch",
  "problemMatcher": {
    "base": "$tsc-watch",
    "background": {
      "activeOnStart": true,
      "beginsPattern": {
        "regexp": "(.*?)"
      },
      "endsPattern": {
        "regexp": "bundle generation complete"
      }
    }
  },
  "isBackground": true,
  "presentation": {
    "reveal": "never"
  },
  "group": {
    "kind": "build"
  },
  "options": {
    "cwd": "${workspaceFolder}/angular-extension"
  }
},

The above snippet defines a Compound Task, makes it the default task that should be executed via launch.json preLaunchTask configuration and changes the task types from npm to shell. This change is necessary because otherwise there is a name collision in the Task auto-detection.

To verify that it works

Launch the Visual Studio Code Extension(s)
- Open Run and Debug
- Ensure Run Extension is selected in the dropdown
- Click Start Debugging or press F5
Right click on the file created in the previous example in the Explorer
Select Open With… - Angular Person Editor

This should open the webview with the content of the Angular application.

In the Visual Studio Code instance that is used for development, open the file angular-extension/webview-ui/src/app/app.component.html
Search for the string Congratulations, change the sentence, e.g. by adding May the force by with you, and save the changes
Switch to the Visual Studio Code instance launched for testing the extension
- Either close and reopen the webview
- Reload the webview by pressing F1 - Developer: Reload Webviews

You should now see the applied changes.

In the Visual Studio Code instance that is used for development, open the file angular-extension/src/personEditor.ts
Change for example the webview HTML by adding Hello World in the .
Switch to the Visual Studio Code instance launched for testing the extension
Reload the Extension Development Host so that it picks up the changes. You have two options to do this:
- Click on the debug restart action
- Press Ctrl + R / Cmd + R in the Extension Development Host window

You should see the applied changes now. If not reopen the webview and verify that the applied changes are visible.

Note:
Don’t forget to remove the modification to the webview HTML, so it does not affect the next steps.

Angular Editor Implementation

The next step is to implement a custom editor, just like in the vanilla HTML, CSS, Javascript example before. It uses the same principles with regards to communication between extension and webview, and looks quite the same. But of course we use Angular for the UI implementation, in this case Reactive forms for the implementation.

Add @types/vscode-webview as a devDependency to the angular-extension/webview-ui project
- Open a Terminal
- Switch to the folder angular-extension/webview-ui
- Run the following command
```
npm i -D @types/vscode-webview
```
Create a new folder angular-extension/webview-ui/src/app/utilities

Create a new file vscode.ts in the new folder

Add the following code, which is a copy of vscode-webview-ui-toolkit-samples

import type { WebviewApi } from "vscode-webview";

/**
 * A utility wrapper around the acquireVsCodeApi() function, which enables
 * message passing and state management between the webview and extension
 * contexts.
 *
 * This utility also enables webview code to be run in a web browser-based
 * dev server by using native web browser features that mock the functionality
 * enabled by acquireVsCodeApi.
 */
class VSCodeAPIWrapper {
  private readonly vsCodeApi: WebviewApi<unknown> | undefined;

  constructor() {
    // Check if the acquireVsCodeApi function exists in the current development
    // context (i.e. VS Code development window or web browser)
    if (typeof acquireVsCodeApi === "function") {
      this.vsCodeApi = acquireVsCodeApi();
    }
  }

  /**
   * Post a message (i.e. send arbitrary data) to the owner of the webview.
   *
   * @remarks When running webview code inside a web browser, postMessage will instead
   * log the given message to the console.
   *
   * @param message Abitrary data (must be JSON serializable) to send to the extension context.
   */
  public postMessage(message: unknown) {
    if (this.vsCodeApi) {
      this.vsCodeApi.postMessage(message);
    } else {
      console.log(message);
    }
  }

  /**
   * Get the persistent state stored for this webview.
   *
   * @remarks When running webview source code inside a web browser, getState will retrieve state
   * from local storage (https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage).
   *
   * @return The current state or `undefined` if no state has been set.
   */
  public getState(): unknown | undefined {
    if (this.vsCodeApi) {
      return this.vsCodeApi.getState();
    } else {
      const state = localStorage.getItem("vscodeState");
      return state ? JSON.parse(state) : undefined;
    }
  }

  /**
   * Set the persistent state stored for this webview.
   *
   * @remarks When running webview source code inside a web browser, setState will set the given
   * state using local storage (https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage).
   *
   * @param newState New persisted state. This must be a JSON serializable object. Can be retrieved
   * using {@link getState}.
   *
   * @return The new state.
   */
  public setState<T extends unknown | undefined>(newState: T): T {
    if (this.vsCodeApi) {
      return this.vsCodeApi.setState(newState);
    } else {
      localStorage.setItem("vscodeState", JSON.stringify(newState));
      return newState;
    }
  }
}

// Exports class singleton to prevent multiple invocations of acquireVsCodeApi.
export const vscode = new VSCodeAPIWrapper();

The VSCodeAPIWrapper is used for
- Aquiring the VSCode API
- Managing the persistent state of the webview
- Posting messages from the webview to the extension

Update angular-extension/webview-ui/src/app/app.component.ts by replacing the content with the following code

import { Component, HostListener } from "@angular/core";
import { FormControl, ReactiveFormsModule } from "@angular/forms";
import { vscode } from "./utilities/vscode";

@Component({
  selector: "app-root",
  imports: [ReactiveFormsModule],
  templateUrl: "./app.component.html",
  styleUrl: "./app.component.css",
})
export class AppComponent {
  firstname = new FormControl("");
  lastname = new FormControl("");
  personObject: any;

  constructor() {
    // Webviews are normally torn down when not visible and re-created when they become visible again.
    // State lets us save information across these re-loads
    const state = vscode.getState() as any;
    if (state) {
      this.updateContent(state.text);
    }
  }

  // Handle messages sent from the extension to the webview
  @HostListener("window:message", ["$event"])
  handleMessage(event: MessageEvent) {
    const message = event.data; // The json data that the extension sent
    switch (message.type) {
      case "update":
        const text = message.text;

        // Update our webview's content
        this.updateContent(text);

        // Then persist state information.
        // This state is returned in the call to `vscode.getState` below when a webview is reloaded.
        vscode.setState({ text });
        return;
    }
  }

  /**
   * Update the data shown in the document in the webview.
   */
  updateContent(text: string) {
    if (text !== "") {
      this.personObject = JSON.parse(text);
      this.firstname.setValue(this.personObject.firstname);
      this.lastname.setValue(this.personObject.lastname);
    }
  }

  /**
   * Update the document in the extension.
   */
  updateDocument() {
    let firstname = this.firstname.value;
    let lastname = this.lastname.value;

    // wait 500 ms before updating the document
    // only update if in the meantime no other input was given
    setTimeout(() => {
      if (
        this.firstname.value === firstname &&
        this.lastname.value === lastname
      ) {
        this.personObject = {
          firstname: this.firstname.value,
          lastname: this.lastname.value,
        };

        vscode.postMessage({
          type: 'updateDocument',
          text: JSON.stringify(this.personObject, null, 2),
        });
      }
    }, 500);
  }
}

Update angular-extension/webview-ui/src/app/app.component.html by replacing the content with the following code

 class="main">
  Angular Person Editor
   class="content">
     class="person">
       class="row">
         for="firstname">Firstname:
         class="value">
          
            type="text"
            [formControl]="firstname"
            (input)="updateDocument()"
          />
        

      


       class="row">
         for="lastname">Lastname:
         class="value">
          
            type="text"
            [formControl]="lastname"
            (input)="updateDocument()"
          />

Install scripts

Like with the Visual Studio Code Extension project before, add a install script to the angular-extension that is called on postCreateCommand of the Dev Container. It needs to run npm install for the extension and the contained webview-ui project.

VSCode Elements Lite

Like the vanilla HTML, CSS, Javascript example in the first section of this tutorial, the UI components do not look like native Visual Studio Code components. To get a more native Visual Studio Code look and feel you would need to spend quite some time to implement this yourself.

Add @vscode-elements/elements-lite as a dependency in the package.json and reference the CSS files in the webview HTML.

If you now restart the application, the input fields in the webview of the custom editor will look like native Visual Studio Code components.

VSCode Elements

If you like to use the Javascript enabled web components, you can use the VSCode Elements component library. Unfortunately the implementation of VSCode Elements is based on the Lit library. And using Lit Webcomponents with Angular requires some more work.

Add @vscode-elements/elements as a dependency in the package.json and reference the CSS files in the webview HTML.

To be able to use Lit Webcomponents in an Angular application, you need to implement a ControlValueAccessor as a Directive.

If you now restart the application, the input fields in the webview of the custom editor will look and behave like native Visual Studio Code components.

React Webview Implementation

When discussing about which Javascript framework should be used for implementing the webview, there can be several answers. The most prominent are Angular or React as far as I can tell. There are also others like Vue or Svelte, but well, in that area you are never done.

In the following chapter we create a React project that serves as the webview frontend of the Visual Studio Code Extension.

Note:
The following description is based on the vscode-webview-ui-toolkit-samples Hello World (React + Vite) example. I reused several parts of the sample code and adapted it where necessary.
Also note that I am not an expert in developing React applications. So probably the following sample can be more efficient, but the goal is to help getting started in setting up a Visual Studio Code Extension with a React webview.

To create a React application you typically use either CRA or Vite. I tried to use CRA and came across issue React Issue 32016. There is a statement that “CRA has become somewhat outdated”. Instead of trying to workaround the issue, I therefore decided to switch to Vite directly.

This will start the React + Vite + TS application and host it via http://localhost:5173.

Prepare the React application as webview

In the next steps the two projects need to be configured so the React application can be used as webview in the Visual Studio Code Extension.

Use the React Application as webview

The next step is to use the React Application as a Visual Studio Code Extension WebView. For this we need to perform the same steps as described previously in Implement the Visual Studio Code Extension.

Script Updates

We now have a React application project as frontend inside a Visual Studio Code Extension project. The build and run scripts are not automatically connected. For example, if you change code in the React application and then launch the Visual Studio Code Extension, the changes are not automatically reflected. This is because the Visual Studio Code Extension is using the build results of the React Application, and not the sources.

To connect the two projects, we need to update the scripts section in react-extension/webview-ui/package.json and react-extension/package.json

To make the updated watch script also work when launching the extension, the corresponding task in .vscode/tasks.json needs to be updated like this (notice the endsPattern):

If you only want to watch the react-extension, update the configuration like this (notice the endsPattern). Replace the npm:watch script at the top of the tasks.json.

If you want to watch the vscode-extension, the angular-extension and the react-extension at the same time, update the configuration like this:

You should see the applied changes now. If not reopen the webview and verify that the applied changes are visible.

Note:
Don’t forget to remove the modification to the webview HTML, so it does not affect the next steps.

React Editor Implementation

The next step is to implement a custom editor, just like in the examples before. It uses the same principles with regards to communication between extension and webview, and looks quite the same. But of course we use React for the UI implementation.

Install scripts

Like with the Visual Studio Code Extension project and the Angular project before, add a install script to the react-extension that is called on postCreateCommand of the Dev Container. It needs to run npm install for the extension and the contained webview-ui project.

VSCode Elements Lite

As a first step, we will only use the styling variant by using VSCode Elements Lite.

Add @vscode-elements/elements-lite as a dependency in the package.json and reference the CSS files in the webview HTML.

If you now restart the application, the input fields in the webview of the custom editor will look like native Visual Studio Code components.

VSCode Elements

If you like to use the Javascript enabled web components, you can use the VSCode Elements component library. In the previous section we only applied the styling approach by using VSCode Elements Lite. But since React 19 web components are fully supported, therefore it is easy to use them directly.

Add @vscode-elements/elements as a dependency in the package.json and reference the CSS files in the webview HTML.

To use custom tag names, you must configure the TypeScript parser to recognize the custom elements. This can be done via a TypeScript definition.

If you now restart the application, the input fields in the webview of the custom editor will look and behave like native Visual Studio Code components.

Conclusion

At the end this blog post got again longer than I initially intended. And it contains more information than I planned. But as I use my blog posts as my external memory I am quite satisfied with the outcome.

If you have any improvements you would like to share, feel free to open an issue in the corresponding Github repository. I am happy to learn and to improve this blog post and my external memory.

The sources for this and the following tutorials are located in my Github repository.

I hope you enjoyed this tutorial and I could share some information that I had to gather via various resources.