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

> Discover the purpose of the .env file in the i-have-adhd project. Learn how it securely stores runtime configurations and sensitive credentials, keeping them out of version control.

- Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd)
- Tags: how-to-guide
- Published: 2026-07-30

---

**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`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py), the implementation resolves the repository root and loads the configuration before executing evaluations:

```python
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

```bash

# 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`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/agents/openai.yaml) references `OPENAI_API_KEY` from the environment, while [`skills/i-have-adhd/agents/gemini.toml`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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.