This page documents every environment variable that the superpowers system reads, sets, or depends on. It covers variables used at runtime by hook scripts and plugins, and variables used by the test infrastructure to create isolated environments.
For information about the hook system that consumes CLAUDE_PLUGIN_ROOT, see 10.3 For the OpenCode plugin internals that read OPENCODE_CONFIG_DIR, see 5.2
These variables are set by the host platform or the user's shell and are read by the plugin at runtime.
CLAUDE_PLUGIN_ROOT| Property | Value |
|---|---|
| Set by | Claude Code (automatically, when executing hooks) |
| Read by | hooks/hooks.json |
| Type | Absolute filesystem path |
| Required | Yes, when running under Claude Code |
Claude Code sets CLAUDE_PLUGIN_ROOT to the absolute path of the installed plugin directory before executing any hook command. The hook configuration in hooks/hooks.json1-16 embeds this variable directly in the command string:
'${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd' session-start
The run-hook.cmd polyglot wrapper then uses the derived SCRIPT_DIR (computed from $0/%~dp0) rather than propagating CLAUDE_PLUGIN_ROOT further, so the variable is effectively consumed at the entry point.
Sources: hooks/hooks.json1-16 hooks/run-hook.cmd1-46
OPENCODE_CONFIG_DIR| Property | Value |
|---|---|
| Set by | User environment (optional) |
| Read by | .opencode/plugins/superpowers.js |
| Type | Absolute filesystem path |
| Required | No; falls back to ~/.config/opencode |
The OpenCode plugin reads process.env.OPENCODE_CONFIG_DIR to determine where OpenCode stores its configuration. If the variable is absent or empty, the plugin defaults to path.join(homeDir, '.config/opencode'). This variable allows non-standard OpenCode installations (or test environments) to point the plugin at a different config root.
The relevant resolution logic in .opencode/plugins/superpowers.js52-53:
const envConfigDir = normalizePath(process.env.OPENCODE_CONFIG_DIR, homeDir);
const configDir = envConfigDir || path.join(homeDir, '.config/opencode');
normalizePath (defined at .opencode/plugins/superpowers.js37-47) trims whitespace and expands leading ~/ before calling path.resolve.
Sources: .opencode/plugins/superpowers.js49-95
HOME| Property | Value |
|---|---|
| Set by | Operating system / shell |
| Read by | hooks/session-start, os.homedir() in the OpenCode plugin |
| Type | Absolute filesystem path |
| Required | Yes (standard Unix environment variable) |
The session-start hook script uses ${HOME} directly to locate the legacy skills directory hooks/session-start12-14:
The OpenCode plugin resolves the home directory via Node.js os.homedir(), which reads HOME on Unix and USERPROFILE on Windows. This value is used as the fallback base for configDir and as the expansion target for ~/ paths in OPENCODE_CONFIG_DIR.
Sources: hooks/session-start1-51 .opencode/plugins/superpowers.js50
The OpenCode test suite uses a trio of environment variables to create a fully isolated environment that does not touch the user's real home directory or OpenCode installation. These are set by tests/opencode/setup.sh1-74 and consumed by subsequent test scripts.
TEST_HOME| Property | Value |
|---|---|
| Set by | tests/opencode/setup.sh |
| Read by | Test scripts; cleanup_test_env function |
| Type | Absolute path to a temporary directory |
| Lifetime | Single test run; deleted on exit via trap cleanup_test_env EXIT |
TEST_HOME holds the path created by mktemp -d. It anchors the entire isolated environment and is the target of the cleanup_test_env function tests/opencode/setup.sh65-69:
Sources: tests/opencode/setup.sh10-13
HOME (overridden in tests)During tests, HOME is reassigned to $TEST_HOME. This causes every component that reads $HOME — including the session-start hook's legacy-skills check and the OpenCode plugin's home directory derivation — to use the isolated directory instead of the real user home.
Sources: tests/opencode/setup.sh11
XDG_CONFIG_HOME| Property | Value |
|---|---|
| Set by | tests/opencode/setup.sh |
| Read by | Any XDG-aware process started during testing |
| Type | Absolute filesystem path |
| Value during tests | $TEST_HOME/.config |
Setting XDG_CONFIG_HOME redirects all XDG Base Directory-aware tools to the isolated directory, preventing test runs from reading or writing the user's ~/.config.
Sources: tests/opencode/setup.sh12
OPENCODE_CONFIG_DIR (overridden in tests)During tests, OPENCODE_CONFIG_DIR is explicitly set to $TEST_HOME/.config/opencode. This ensures the OpenCode plugin resolves all paths inside the isolated environment rather than the real OpenCode config directory.
Sources: tests/opencode/setup.sh13
| Variable | Runtime or Test | Set by | Read by | Default |
|---|---|---|---|---|
CLAUDE_PLUGIN_ROOT | Runtime | Claude Code | hooks/hooks.json | (none; required) |
OPENCODE_CONFIG_DIR | Runtime | User / test setup | superpowers.js plugin | ~/.config/opencode |
HOME | Runtime + Test | OS / setup.sh | session-start, superpowers.js | (OS-provided) |
XDG_CONFIG_HOME | Test only | tests/opencode/setup.sh | XDG-aware tools | ~/.config |
TEST_HOME | Test only | tests/opencode/setup.sh | Cleanup function | (none; set by mktemp) |
Diagram: Runtime Variable Resolution
Sources: hooks/hooks.json9 hooks/run-hook.cmd43-46 hooks/session-start12-14 .opencode/plugins/superpowers.js50-53
Diagram: Test Isolation Variable Chain
Sources: tests/opencode/setup.sh10-13 tests/opencode/setup.sh65-69 tests/opencode/test-plugin-loading.sh1-81
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.