dsh-direnv

dsh plugin add dsh-direnv

Every command the harness runs then inherits the direnv environment of its own working directory. Two minutes to install; needs direnv on PATH.

~/.dsh $ dsh web                 # no .envrc here
           └── session in ~/projects/api
                 └── bash: build      → has `cargo`, `DATABASE_URL`, …

Install

1. Run direnv version. If it fails, install direnv first — this plugin never runs direnv allow for you.
2. Add the plugin:

# once it is on npm
dsh plugin add dsh-direnv

# from a checkout instead: `npm install` runs the build that produces lib/
npm install && dsh plugin add "file:$PWD"

3. Confirm the patch landed. Expect disabled: true:

dsh --profile <name> --dump-config | grep -A3 'id: subprocess'

Check it works

1. Open a session in a workspace with an approved .envrc.
2. Ask the model to run bash -c 'echo $SOME_VAR_YOUR_ENVRC_SETS'.
3. Read the direnv tab in the right sidebar: state, variable names, and the PATH diff in priority order.

An empty line from step 2 means the environment is not loading. Go to Troubleshooting.

What it does

The plugin takes over the harness's subprocess seam and evaluates direnv export json per working directory. Three flows share that one fact source and never block each other:

Direnv does the walking: the anchor is each spawn's own resolved cwd, so a command that cds into a subdirectory gets that subdirectory's environment, and a change to any .envrc takes effect on the next tool call.

Configure

- id: direnv-subprocess
  name: 'dsh-direnv'
  config:
    enabled: true
    direnvPath: ''            # empty = resolve `direnv` from PATH
    loadTimeoutMs: 300000     # tool calls wait at most this long, then proceed
    evaluateTimeoutMs: 0      # kill the direnv child after this long (0 = never kill)
    gateTools: all            # all | spawning | none   ('spawning' currently behaves like 'all')
    injectSensitive: all      # all | filter
    notifyModel: true         # one sourced message per workspace state change
    sidebar: true             # right-sidebar tab and composer placeholder
    disabledDirs: []          # absolute paths to leave alone

• injectSensitive: filter withholds variables whose names look like credentials (/KEY|PASSWORD|SECRET|TOKEN/i). Cautious setups only; it breaks dev shells that need those values.
• loadTimeoutMs is the gate's budget: how long a tool call may be held before it runs with whatever is known.
• evaluateTimeoutMs bounds the direnv child. 0 never kills it, because a cold use flake has no predictable duration. The price: an .envrc that never finishes keeps one direnv process per directory alive for the session.

Troubleshooting

Almost every failure here is quiet. Read startup output before assuming it works. These five cover nearly all of it:

--dump-config does not predict everything: it composes patches without the row-level preflight. Patch warnings appear only there; compatibility refusals only at startup. Read both.

If the plugin is up but a workspace has no environment, open the sidebar tab: it reports blocked, unreadable and absent separately, and says when a directory is merely indistinguishable from one without an .envrc.

Security

• A .envrc is arbitrary code. Evaluating one runs bash as you, outside any sandbox. The plugin only evaluates files direnv would already evaluate, and never approves one for you.
• Values never reach the model as text. The notice carries counts, paths and warnings; the sidebar is where you inspect names and reveal values on demand.
• Credential-shaped names reach commands by default. The overlay sits on top of the harness's scrubbed environment. That is the point of the plugin — and why injectSensitive exists.
• The evaluator strips every DIRENV_* from the environment it hands to direnv, so a harness started from a direnv-loaded shell cannot resurrect variables the harness scrubbed.
• The status route is fenced. Requests go through the harness's own connection check, unlike the unfenced /plugins/* carrier.

Limits

• MCP servers and host-side helpers bypass the seam. Anything spawning through the MCP SDK or the host process does not see the workspace environment. Covered: the harness's shell, subprocess, search, git and PTY consumers.
• Another subprocess provider would be shadowed. Only one provider holds the seat; the plugin reports loudly when it loses it.
• Some directories look empty. An unreadable .envrc (chmod 000) or a direnv denyed directory produces the same empty output as "no .envrc here".
• A failing .envrc can half-succeed. direnv exits 0 for source misses and syntax errors with earlier variables already applied. Both the sidebar and the notice report these as degraded.
• The harness's name filter wins twice. Ambient names that merely contain KEY, PASSWORD, SECRET or TOKEN (including TURKEY_MODE) are scrubbed before an overlay applies. Only values a .envrc sets explicitly survive.

Development

npm run typecheck           # three projects: host, browser half, tests and harness
npm test                    # unit tests: evaluator (real direnv) + host wiring
npm run test:client         # client half: boot row, byte-identical module, and the fenced status route
test/harness/run.sh --all   # end-to-end cases, no API key needed

Strict TypeScript, no build on your side for the published package: src/**/*.ts compiles per file to lib/ (host half), and client/**/*.ts is bundled into the single file lib/client.js the browser is served. npm install builds through prepare; lib/ is not committed. DESIGN.md records the architecture and the measured evidence behind every decision.

npm test uses an explicit test/*.test.ts glob on purpose: bare node --test would also execute the scripts under test/harness/. Invoke the harness through run.sh, not node test/harness/run.ts — the wrapper scrubs DSH_HOME/DSH_PROFILE_DIR, and the harness refuses to run against a live DSH home by design. The harness drives a stub LLM against dsh headless, so a real turn with real tool execution runs offline.

# build the checkout once (`npm install` runs the build through `prepare`)
cd /path/to/dsh-direnv && npm install

# a demo workspace in a scratch home
export DSH_HOME=$(mktemp -d)/dsh-home && mkdir -p "$DSH_HOME" /tmp/demo/proj
cd /tmp/demo/proj && printf 'export HANDS_ON=yes-from-envrc\n' > .envrc && direnv allow
dsh --profile demo --from-default-profile web --dump-config   # seed a profile
dsh plugin --profile demo add "file:/path/to/dsh-direnv"      # appends our bundle last
dsh --profile demo --no-open --port 30100                     # open the printed URL

curl -s -H "Cookie: $COOKIE" \
  "http://127.0.0.1:30100/plugins/dsh-direnv/status.json?dir=/tmp/demo/proj&force=1"
# {"ok":true,…,"status":{"state":"ok","envrcPath":"/tmp/demo/proj/.envrc","variables":[{"name":"HANDS_ON",…}]}}

cat > /tmp/dsh-direnv.yml <<'EOF'
- id: subprocess
  disabled: true
- insert:
    - id: direnv-subprocess
      name: '/path/to/dsh-direnv/lib/index.js'
EOF
dsh --profile web --patch /tmp/dsh-direnv.yml --no-open --port 30100
# then, in a workspace with an .envrc, ask the model to run:
#   bash -c 'echo $YOUR_VAR'

License

MIT