Purpose of the .env File in i-have-adhd: Secure Runtime Configuration

The .env file in the ayghri/i-have-adhd repository stores sensitive environment variables like API keys and model configurations that configure the skill at runtime without exposing credentials in version control.

The i-have-adhd project is an open-source skill that integrates with external AI services such as OpenAI and Gemini. Understanding the purpose of the .env file in i-have-adhd is essential for securely managing authentication tokens and feature toggles while keeping the repository safe for public collaboration.

What the .env File Stores

The .env file acts as a secure vault for runtime configuration variables that vary between developers and deployments. According to the source code, it typically contains:

• OPENAI_API_KEY – Authentication token for OpenAI API access
• GEMINI_API_KEY – Authentication token for Google's Gemini API
• MODEL – Default model identifier (e.g., gpt-4o, gemini-1.5-pro)
• ADHD_RULES_PATH – Filesystem path to custom rule sets the skill loads
• DEBUG – Boolean flag (true/false) enabling verbose logging output

These values populate os.environ when the skill initializes, allowing the code to access them via os.getenv().

How Environment Variables Are Loaded

When the skill starts, bootstrap scripts load the .env file using python-dotenv. In scripts/run_evals.py, the implementation resolves the repository root and loads the configuration before executing evaluations:

from pathlib import Path
from dotenv import load_dotenv
import os

# Load .env from the repository root

env_path = Path(__file__).parents[1] / ".env"
load_dotenv(dotenv_path=env_path)

# Access the variables

openai_key = os.getenv("OPENAI_API_KEY")
model = os.getenv("MODEL", "gpt-4o")

This pattern ensures that os.getenv("OPENAI_API_KEY") returns the value defined in your local .env file rather than hardcoded secrets.

Security and Version Control Protection

The repository treats .env as a non-tracked file by listing it in .gitignore. This prevents accidental commits of sensitive credentials to GitHub. Instead, the repository provides .env.example as a template showing all supported variables and their formats.

To configure your local environment:

1. Copy the template to create your private .env file
2. Add your personal API keys to the new file
3. Run the skill, which automatically reads the variables

# Copy the template and edit it

cp .env.example .env

# (Edit .env to add your API keys)

# Execute the main script; the environment is automatically read

python -m skills.i_have_adhd.main

Because the file remains uncommitted, each developer can supply unique credentials without risking repository-wide exposure.

Agent Configuration Files

The environment variables defined in .env directly feed the agent configurations found in the skills directory. The file skills/i-have-adhd/agents/openai.yaml references OPENAI_API_KEY from the environment, while skills/i-have-adhd/agents/gemini.toml consumes GEMINI_API_KEY. These agent definitions demonstrate how the skill bridges external service authentication with local environment configuration.

Summary

• The .env file stores sensitive configuration including API keys (OPENAI_API_KEY, GEMINI_API_KEY), model selections (MODEL), and debug flags (DEBUG)
• python-dotenv loads these values into os.environ at runtime via bootstrap scripts like scripts/run_evals.py
• The file is gitignored to prevent credential leakage, with .env.example serving as the public template
• Agent configurations in skills/i-have-adhd/agents/ reference these environment variables to authenticate with OpenAI and Gemini services

Frequently Asked Questions

What happens if I don't create a .env file?

Without a .env file, the skill will attempt to read environment variables directly from your system shell. If OPENAI_API_KEY or GEMINI_API_KEY are not set, the respective agents in skills/i-have-adhd/agents/ will fail to authenticate, causing os.getenv() to return None and API calls to error.

Is it safe to share my .env file?

Never share your .env file. It contains sensitive authentication tokens that grant access to paid API services. Because the file is listed in .gitignore, it should never appear in pull requests. If accidentally exposed, immediately rotate the compromised API keys in your OpenAI or Gemini dashboards.

What is the difference between .env and .env.example?

.env.example is a public template committed to the repository that shows required variable names and example formats without real values. .env is your private, local copy containing actual API keys and personal settings. Developers copy .env.example to .env and fill in their own credentials.

Can I use environment variables without python-dotenv?

Yes. If you export variables directly in your shell before running Python, os.getenv() will still retrieve them. However, using python-dotenv as implemented in scripts/run_evals.py is the recommended approach because it automatically loads the file from the repository root and ensures consistent configuration across different environments.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}