Skip to content

environment-variables.md

Latest commit

 

History

History
88 lines (64 loc) · 4.06 KB

environment-variables.md

File metadata and controls

88 lines (64 loc) · 4.06 KB
Raw

Environment Variables

Diffex uses environment variables in three ways:

  • Variables such as DIFFEX_OFFLINE configure the Diffex process.
  • Diffex sets DIFFEX_CODING_AGENT so child processes can detect that they run inside Diffex.
  • Commands run by the LLM-callable bash tool receive DIFFEX_* variables describing the current session.

Provider API-key variables are documented separately in Providers.

Process Marker

The CLI and RPC entry points set DIFFEX_CODING_AGENT=true. Child processes inherit it and can use it to detect that they run inside Diffex. It is not session-specific and is not set automatically when Diffex is embedded through the SDK.

Bash Tool Session Environment

Commands run by the bash tool receive the current Diffex session state:

Variable Description
DIFFEX_SESSION_ID Current session ID
DIFFEX_SESSION_FILE Absolute path to the current session JSONL file; unset for ephemeral sessions
DIFFEX_PROVIDER Currently selected model provider
DIFFEX_MODEL Currently selected model ID
DIFFEX_REASONING_LEVEL Current effective reasoning level: off, minimal, low, medium, high, xhigh, or max

The values are resolved when each command starts. Switching models or changing the reasoning level therefore affects the next bash command without restarting Diffex. DIFFEX_PROVIDER and DIFFEX_MODEL identify the selected Diffex model, not a different upstream model that a router may choose internally.

When asked which model or provider is running, inspect these variables instead of inferring the answer from the system prompt:

printf '%s/%s\n' "$DIFFEX_PROVIDER" "$DIFFEX_MODEL"
printf 'reasoning=%s session=%s\n' "$DIFFEX_REASONING_LEVEL" "$DIFFEX_SESSION_ID"

The session file can be inspected directly when the session is persistent:

if [ -n "$DIFFEX_SESSION_FILE" ]; then
  tail -n 1 "$DIFFEX_SESSION_FILE"
fi

These variables are injected into the LLM-callable bash tool. They are not injected into user-entered ! or !! commands.

Custom Bash Tools

Bash tools created with createBashTool() expose the session environment by default when registered with Diffex. Injection happens before spawnHook, so a hook receives the variables in ctx.env:

const bashTool = createBashTool(cwd, {
  spawnHook: (ctx) => ({
    ...ctx,
    env: { ...ctx.env, CI: "1" },
  }),
});

Disable session metadata independently of the spawn hook:

const bashTool = createBashTool(cwd, {
  exposeSessionEnvironment: false,
  spawnHook: (ctx) => ctx,
});

When disabled, Diffex removes inherited values for these variables so nested Diffex processes do not expose stale parent-session metadata.

Diffex Process Configuration

These variables are read by Diffex itself:

Variable Description
DIFFEX_CODING_AGENT_DIR Override the config directory; default is ~/.diffex/agent
DIFFEX_CODING_AGENT_SESSION_DIR Override session storage; overridden by --session-dir
DIFFEX_PACKAGE_DIR Override the package directory, useful for Nix/Guix store paths
DIFFEX_OFFLINE Disable startup network operations, including update checks and package updates
DIFFEX_SKIP_VERSION_CHECK Disable the automatic Diffex release check
DIFFEX_PROVIDER_ATTRIBUTION Override optional provider attribution headers: 1/true/yes or 0/false/no; defaults off
DIFFEX_CACHE_RETENTION Set to long for extended provider prompt caching where supported
DIFFEX_SHARE_VIEWER_URL Override the base URL used by /share
DIFFEX_HARDWARE_CURSOR Set to 1 to show the hardware cursor; see Terminal setup
VISUAL, EDITOR External editor fallback when externalEditor is unset
HTTP_PROXY, HTTPS_PROXY Proxy outbound HTTP requests

Provider credentials such as ANTHROPIC_API_KEY, OPENAI_API_KEY, and cloud-provider configuration are listed in Providers.