Introduction

In the DSH agent workflow, the pwsh tool call often needs to read tokens, paths, and local tool environment variables. If you manually export these at the system layer every time, two problems can easily occur: cross-environment contamination between projects, where variables from the previous project are still present after switching to another workspace; or having to restart the process after editing .env for changes to take effect.

dsh-workspace-env solves this kind of problem: it acts as a DSH plugin to enhance the pwsh executor, reading .env from the current workspace directory on every call and injecting its variables into the subprocess environment. Below is an introduction to its positioning, capabilities, installation method, and verification method.

What is it

dsh-workspace-env is a DSH plugin located at Momojie-S/dsh-workspace-env with an MIT license.

Its one-sentence positioning is:

DSH plugin: pwsh executor enhancement, injecting environment variables from workspace .env into subprocesses.

This plugin is installed as part of the dsh.bundle composite package. After using dsh plugin to install it into the profile, it automatically appends a configuration layer. No manual patch editing is required after installation, and it does not provide extra configuration items.

Core Capabilities

The following lists a few verified behaviors.

  1. Workspace Isolation
    On every call to the pwsh tool, automatically inject environment variables from the .env in the current workspace directory into the subprocess. The environment switches automatically when changing projects; the agent is unaware.

  2. Read on Every Call
    .env is read fresh on every command call. Changes take effect immediately without needing to restart DSH.

  3. Ignore DSH Managed Variables
    Keys with the DSH_* prefix are ignored. This is because DSH managed variables have their own channel, and the workspace .env does not override these keys.

  4. Same Key Override Rules
    When overriding the same key, the workspace .env takes the highest priority, beating system environment variables and DSH-injected variables with the same name (except DSH_*).

  5. Variable Reference Support
    Supports ${VAR} references to parent environments and variables defined earlier in the same file. Undefined variables expand to an empty string. The override is a complete replacement; to append, you need to use references, for example:

   PATH=D:\tools;${PATH}
  1. Basic Parsing Rules
    Supports automatic removal of paired single quotes or double quotes, supports # comments, and skips empty lines or lines without =.

Environment and Limits

Before using, you need to confirm the environment:

  • DSH version requirement: DSH >= 0.1.0-rc.6
  • Verified up to: 0.1.1-rc.2
  • Only covers Windows pwsh
  • bash link is not covered
  • Relies on internal methods of spawnSpec within the shell service
  • It is recommended to re-run verification after upgrading DSH

Installation and Enabling

1. Install Plugin

The official installation command is as follows:

dsh plugin --profile web add github:Momojie-S/dsh-workspace-env

If you use pnpm >= 10, the first add will prompt for authorization to build. You need to write the package key to the allowBuilds section of ~/.dsh/profiles/web/pnpm-workspace.yaml as prompted, then re-run add.

You can also use a tarball for installation:

dsh plugin --profile web add momojie-s-dsh-workspace-env-0.1.0.tgz

2. Verify Configuration Layer

Execute after installation:

dsh web --dump-config | Select-String workspace-env

You should see:

# == dsh-workspace-env

Seeing this layer indicates that the plugin configuration layer is in place.

3. Restart DSH

After the verification layer is in place, you need to restart DSH.

Typical Usage

1. Place .env in the workspace root

In the workspace root (i.e., the session cwd), place a .env file:

GH_TOKEN=gho_xxx
QUOTED="value with spaces"
PATH=D:\mytools;${PATH}

Where:

  • GH_TOKEN=gho_xxx: Injects a normal environment variable.
  • QUOTED="value with spaces": Paired double quotes will be automatically removed.
  • PATH=D:\mytools;${PATH}: References the parent environment via ${PATH} to achieve a prepend to PATH.

2. Verify if Injection is Effective

Write to the workspace .env:

WS_ENV_TEST=hello

Let the agent execute:

pwsh: echo $env:WS_ENV_TEST

If the output is:

hello

It indicates that injection is effective.

3. Verify Workspace Isolation

Switch to a directory without a .env and execute the same command:

pwsh: echo $env:WS_ENV_TEST

If the output is empty, it indicates that workspace-level isolation is working.

Applicable Scenarios and Notes

This plugin is suitable for the following situations:

  • You are using DSH’s Windows pwsh link.
  • Different projects require different environment variables.
  • You want environment variables to follow the workspace switch, rather than manually maintaining system environment variables.
  • You want changes to .env to take effect immediately without restarting DSH every time.

You need to pay attention to:

  • The plugin runs with the current dsh process permissions; you should check the source code and license before installing.
  • This plugin’s license is MIT.
  • Keys with the DSH_* prefix will not be overridden by the workspace .env.
  • ${VAR} expands to an empty string when undefined.
  • The override is a complete replacement; for appending, please use ${VAR} references.
  • Only covers Windows pwsh; the bash link is not covered.
  • It is recommended to re-run verification after upgrading DSH.

Conclusion

The value of dsh-workspace-env lies in sinking environment variable management down to the workspace level: under the same DSH profile, different project directories can carry their own .env, and pwsh subprocesses read and inject them fresh on every call. It is suitable for DSH usage scenarios that require environment variable isolation per project.

GitHub:

https://github.com/Momojie-S/dsh-workspace-env

The community directory URL did not appear in the verified materials in this article, so an unconfirmed link is not attached here; you can search the community directory for the plugin name dsh-workspace-env.