Skip to content

AGENTS.md

Latest commit

 

History

History
156 lines (97 loc) · 8.71 KB

AGENTS.md

File metadata and controls

156 lines (97 loc) · 8.71 KB
Raw

AGENTS.md

Project-specific context for AI agents working on the Eclipse Theia code base.

Architecture overview

Theia has a modular architecture and consists of so-called "Theia extensions", which are technically node packages. Most features and generally the source code can be found under "/packages/" which hosts a list of Theia extensions for different sorts of features. Theia applications can be used in the browser or (via Electron) on the desktop, but generally have a front end (browser application) and a backend part (node application). Therefore, extensions can contribute to the front end and the backend. This is reflected in the folder structure of extensions:

  • src/browser: Frontend part of an extensions
  • src/node: Backend part of an extension.
  • src/common: Common/shared components, interfaces and protocol information for front end back end communication

Theia uses dependency injection (via inversify) to wired components. If a class is contributed via dependency injection it needs to be bound in the corresponding frontend or backend module (which usually already exists in existing packages)

Widgets

Widgets are views that are visible in the workbench of a Theia-based application.

Commands

Commands in Theia are actions that can be executed by users and programmatically. They are registered through the CommandRegistry and can be triggered via menus, keybindings, or other UI elements such as toolbar items.

Commands are contributed via CommandContribution, see for example: packages/ai-chat-ui/src/browser/chat-view-widget-toolbar-contribution.tsx

Toolbars

Toolbars in Theia are UI components that provide quick access to commonly used commands. They can be added to various parts of the workbench including the main toolbar, and custom widget toolbars.

Toolbars are typically contributed through:

  • TabBarToolbarContribution: For adding toolbar items to tab bars
  • ToolbarContribution: For contributing to main application toolbars

ToolbarContributions are located in separate files. Browse the following file for an example: packages/ai-chat-ui/src/browser/chat-view-widget-toolbar-contribution.tsx

Coding Guidelines

  • Trailing white spaces and empty lines with white spaces are forbidden
  • Use constants for values that never get reassigned
  • The use of null is forbidden. Use undefined instead for representing absent or uninitialized values.
  • Use single quotes (') for string literals instead of double quotes (").
  • Use Theia's Event/Emitter/Disposable for handling event listener patterns
  • For localization, use nls.localizeByDefault(defaultValue) when the string exists in VS Code's language packs. ESLint will flag nls.localize with a custom key if a matching default string is available. Only use nls.localize('theia/<package>/<id>', 'text') for strings that do not exist in VS Code translations.

Contribution Providers

When binding a ContributionProvider, prefer bindRootContributionProvider over bindContributionProvider.

  • bindRootContributionProvider should be used in most cases. It walks to the root Inversify container before constructing the provider, which avoids a memory leak where the provider permanently retains a reference to a child container. Use this whenever contributions are bound in the main (root) container, which is the typical case for module-level ContainerModule bindings.
  • bindContributionProvider should only be used when some or all of the relevant contributions are scoped to a child container rather than the root container, such as connection-scoped containers (e.g., inside ConnectionContainerModule.create(...)).

Both functions are exported from @theia/core/lib/common/contribution-provider.

Test File References

When writing new tests, refer to the following files to see example tests and ensure consistency in style and methodology within the project:

  • Backend Test Example: packages/core/src/common/content-replacer.spec.ts
  • Frontend Test Example: packages/ai-code-completion/src/browser/code-completion-postprocessor.spec.ts

Tests are located in the same directory as the components under test.

Compile and Test

Use npm (not yarn) for all package management and script execution.

If you want to compile something, run the linter or tests, prefer to execute them for changed packages first, as they will run faster. Only build the full project once you are done for a final validation. There are usually pre-defined tasks for all these operations, prefer to use these instead of npm directly.

Important: Building a package only compiles TypeScript. Before any UI testing, you must also rebuild the browser example application (examples/browser), which bundles the frontend. Bundling runs via theia build, which uses esbuild and the generated esbuild.mjs config of the application. Without this step, the running browser app will not include the latest code changes.

Start Theia

To start Theia as a browser app to show something to the user or for UI testing use the launch config "Start Theia Default (Browser backend, no debug)"

Building Applications

Before running or testing the application UI, you must build the application:

  • Browser application: npm run build:browser
  • Electron application: npm run build:electron

These commands bundle the frontend and must be run after any code changes before launching the application via debug configurations.

Preferences

Theia uses a preferences system for user/workspace settings. To add new preferences:

  1. Define a PreferenceSchema with property definitions (type, default, description)
  2. Create a PreferenceContribution symbol and bind it
  3. Use PreferenceProxy for type-safe access to preference values

Example: packages/workspace/src/common/workspace-trust-preferences.ts

Plugin API Extensions

To extend the plugin API (VS Code compatible API):

  1. Type definitions: Add to packages/plugin/src/theia.d.ts
  2. Plugin-side implementation: packages/plugin-ext/src/plugin/ (e.g., workspace.ts)
  3. Main-side implementation: packages/plugin-ext/src/main/browser/ (e.g., workspace-main.ts)
  4. RPC protocol: Define in packages/plugin-ext/src/common/plugin-api-rpc.ts
  5. Expose to plugins: packages/plugin-ext/src/plugin/plugin-context.ts

Events flow: Main side service → workspace-main.ts → RPC → workspace.ts → plugin context

Proposed APIs

For APIs that are not yet stable, Theia follows VS Code's proposed API pattern:

  1. Define proposed types: Create packages/plugin/src/theia.proposed.<feature>.d.ts
  2. Enable via package.json: Extensions must declare enabledApiProposals in their package.json
  3. Implementation: Same as stable APIs, but types come from the proposed file

Note: Some VS Code APIs that were previously "proposed" are now stable (e.g., workspace trust). Check VS Code's current API status before creating proposed API files.

Styling

Theia permits extensive color theming and makes extensive use of CSS variables. Styles are typically located either in an index.css file for an entire package or in a module-level CSS file.

  • Color variable contribution example: packages/core/src/browser/common-frontend-contribution.ts
  • Package-level CSS example: packages/ai-ide/src/browser/style/index.css
  • Module-specific CSS example: packages/core/src/browser/style/tabs.css

FileService and Filesystem Access (Browser Mode)

The FileService in browser mode communicates with the backend via RPC and has restricted filesystem access:

  • Accessible paths: Files within the current workspace directory or the Theia user config directory (e.g., ~/.theia/)
  • Inaccessible paths: Arbitrary filesystem paths outside these boundaries (e.g., /tmp/, /etc/)

When implementing browser-side services that need to read files from user-configured directories:

  1. Use FileService from @theia/filesystem/lib/browser/file-service
  2. Convert paths to URIs using URI.fromFilePath(path)
  3. Expect fileService.exists() to return false for paths outside allowed boundaries
  4. Document that users should configure paths within their workspace or config directory

Reference implementation: packages/ai-core/src/browser/skill-service.ts and packages/ai-core/src/browser/frontend-prompt-customization-service.ts

Reviewing Pull Requests

Reviews of pull requests follow the pull request rules:

  • Check the PR against the review checklist
  • Do not report personal preferences or style questions, see no nitpicking
  • Report issues outside the scope of the PR as follow-ups. They need no fix in the PR and do not block the AI approval.