GitHub - simonwjackson/opencode-direnv: OpenCode plugin that automatically loads direnv environment variables at session start

Seamless direnv integration for OpenCode

Automatically load direnv environment variables when OpenCode sessions start.

Installation • Usage • Configuration • API • Contributing

Overview

opencode-direnv automatically detects and loads .envrc files, ensuring your OpenCode sessions have access to the same environment variables you use in your terminal.

Key Features

Automatic Detection — Searches for .envrc from the project directory up to the git root
Seamless Integration — Applies environment variables to process.env for all subsequent commands
Smart Notifications — Toast alerts for blocked .envrc files and successful environment loads
Zero Configuration — Works out of the box with sensible defaults
Graceful Degradation — Silently skips if direnv is not installed or no .envrc exists

Requirements

Dependency	Version	Required	Notes
OpenCode	`>=1.0.0`	Yes	Plugin host environment
direnv	`>=2.0.0`	Yes	Must be available in PATH
TypeScript	`>=5.0.0`	Dev only	For building from source

Installation

Via OpenCode Config

Just add the plugin to your configuration — OpenCode handles installation automatically.

Configuration

Add the plugin to your OpenCode configuration:

Project-level (./opencode.json):

{
  "plugin": ["@simonwjackson/opencode-direnv"]
}

Global (~/.config/opencode/opencode.json):

{
  "plugin": ["@simonwjackson/opencode-direnv"]
}

Usage

Basic Setup

Ensure direnv is installed on your system
Create or configure your .envrc file in your project
Allow the .envrc file:
Start an OpenCode session — environment variables are loaded automatically

Use Cases

Scenario	Description
Nix Flakes	Automatically load `use flake` environments for reproducible development
Project Secrets	Securely load API keys and credentials from `.envrc`
Tool Versioning	Leverage direnv's `layout` functions for project-specific tooling
Database Connections	Load connection strings and credentials per-project
Cloud Configurations	Set AWS, GCP, or Azure credentials per-project

Example `.envrc`

# Nix flake environment
use flake

# Project-specific variables
export DATABASE_URL="postgresql://localhost/myapp"
export API_KEY="your-api-key-here"

# Tool versions via asdf/mise
use asdf

How It Works

┌─────────────────────────────────────────────────────────────────┐
│                     Session Creation                            │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  1. Search for .envrc (project dir → git root → filesystem root)│
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  2. Execute `direnv export json`                                │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  3. Parse JSON and apply to process.env                         │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  4. All bash commands inherit environment variables             │
└─────────────────────────────────────────────────────────────────┘

Behavior Details

Session Start — Plugin hooks into OpenCode session creation
Directory Traversal — Searches upward from project directory, stopping at git root
Environment Export — Executes direnv export json for structured output
Variable Application — Merges exported variables into process.env

Notifications

Type	Condition	Message
Warning	`.envrc` is blocked	Prompts user to run `direnv allow`
Info	Environment loaded	Confirms successful environment application
Silent	No direnv or `.envrc`	No notification displayed

Limitations

Limitation	Description	Workaround
Single Load	Environment loaded once per session	Start new session for `.envrc` changes
Manual Allow	`.envrc` must be explicitly allowed	Run `direnv allow` (security feature)
No Unload	Variables persist until session ends	Sessions are isolated by design

Troubleshooting

Common Issues

Environment not loading

# Verify direnv is installed
which direnv

# Check if .envrc exists and is allowed
direnv status

Variables not available in commands

# Ensure .envrc is allowed
direnv allow

# Verify export works
direnv export json

Plugin not activating

Confirm plugin is listed in opencode.json
Check OpenCode logs for plugin initialization errors

Contributing

Contributions are welcome. Please read our contributing guidelines before submitting a pull request.

# Clone the repository
git clone https://github.com/simonwjackson/opencode-direnv.git
cd opencode-direnv

# Install dependencies
bun install

# Build
bun run build

License

This project is licensed under the MIT License.