Architecture: runtime behavior and communication

January 12, 2026 ยท View on GitHub

Describes the runtime behavior and design of AWS Toolkit. Corresponds to the "Process view" of the 4+1 architectural views.

Environment variables

TODO: move from CONTRIBUTING.md

VSCode context keys

VScode extensions can use vscode 'setContext' command to set special context keys which are available in package.json. Use this only if there is no other alternative (it's shared, global, mutable state).

Defining a new setContext key

If you must define a new key (is it really necessary?), follow these guidelines:

  • Choose a prefix as follows (as recommended):
    • packages/core/ should use aws. prefix
    • packages/toolkit/ should use aws.toolkit. prefix
  • Use brevity. Less is more.
  • Document it in the list below.

setContext keys

setContext keys owned by packages/core/

These keys are currently set by the core/ package, but many of them may eventually be migrated to toolkit/ or amazonq/ if appropriate.

  • aws.codecatalyst.connected: CodeCatalyst connection is active.
  • aws.codewhisperer.connected: CodeWhisperer connection is active.
  • aws.codewhisperer.connectionExpired: CodeWhisperer connection is active, but the connection is expired.
  • aws.isDevMode: AWS Toolkit is running in "developer mode".
  • aws.isWebExtHost: true when the extension host is running in a web browser, as opposed to nodejs (i.e. the environment has no "compute").
    • Compare to isWeb, which vscode defines when the UI is web, but says nothing about the extension host.
  • aws.isSageMaker: AWS Toolkit is running in the SageMaker Code Editor.

setContext keys owned by packages/toolkit/

  • TODO

How our components communicate

TODO: vscode events; the "globals" module; activate(); EventEmitters; ...?