# Understanding the getAgentDir Function in the i-have-adhd Project

> Discover the getAgentDir function in i-have-adhd. Learn how it finds the agent's root directory to automatically activate ADHD-friendly mode by locating the .i-have-adhd-always flag.

- Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd)
- Tags: deep-dive
- Published: 2026-08-19

---

**The `getAgentDir` function returns the absolute filesystem path to the Pi coding agent’s root directory, allowing the i-have-adhd extension to reliably locate the `.i-have-adhd-always` flag file and determine whether ADHD-friendly mode should activate automatically.**

The `getAgentDir` function is a critical utility imported from the **@earendil-works/pi-coding-agent** package that underpins persistent configuration management in the **ayghri/i-have-adhd** repository. This function solves cross-platform path resolution by dynamically identifying where the Pi coding agent resides on the filesystem, eliminating the need for hard-coded directory strings that would break across different environments.

## What is the getAgentDir Function?

The `getAgentDir` function is exported by the **@earendil-works/pi-coding-agent** dependency declared in the project’s [`package.json`](https://github.com/ayghri/i-have-adhd/blob/main/package.json). It returns a string representing the absolute path to the directory containing the currently running Pi coding agent installation.

According to the source architecture, this utility abstracts away environment-specific path differences, ensuring that extensions can locate agent-specific resources regardless of whether the code runs on Windows, macOS, or Linux. The function takes no arguments and synchronously returns the resolved directory path.

## How getAgentDir is Utilized in i-have-adhd

The primary utilization of `getAgentDir` within the i-have-adhd project centers on persistent state management through a sentinel flag file.

### Locating the Always-On Flag File

In [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts), the extension constructs a path to a hidden configuration flag by appending `.i-have-adhd-always` to the agent directory:

```typescript
import { getAgentDir } from "@earendil-works/pi-coding-agent";
import { join } from "node:path";

const alwaysOnFlag = join(getAgentDir(), ".i-have-adhd-always");

```

This approach ensures the flag file lives in a consistent, agent-specific location without colliding with user project files or requiring manual path configuration from the user.

### Conditional Activation Logic

After constructing the path, the extension checks for the file’s existence during initialization to determine default behavior:

```typescript
import { existsSync } from "node:fs";

const enabledByDefault =
  pi.getFlag("adhd") === true || existsSync(alwaysOnFlag);

```

If `existsSync(alwaysOnFlag)` returns true, the extension automatically enables ADHD-friendly output formatting for the session, overriding default settings without requiring explicit user commands.

## Key Source Files and Architecture

The following files demonstrate how `getAgentDir` integrates with the broader extension architecture:

- **[`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts)** – Core extension implementation that imports `getAgentDir`, constructs the flag file path, and implements the conditional activation logic.
- **[`package.json`](https://github.com/ayghri/i-have-adhd/blob/main/package.json)** – Declares the **@earendil-works/pi-coding-agent** dependency that provides the `getAgentDir` utility.
- **[`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md)** – Contains the formatting rules that get injected when the flag-based activation triggers ADHD-friendly mode.
- **`.opencode/plugins/i-have-adhd.mjs`** – Plugin entry point that bridges the extension to the OpenCode runtime, inheriting the same agent directory resolution logic.

## Practical Implementation Examples

These runnable examples demonstrate common patterns for utilizing `getAgentDir` within the i-have-adhd ecosystem.

**Example 1: Detecting Always-On Mode**

```typescript
import { getAgentDir } from "@earendil-works/pi-coding-agent";
import { existsSync } from "node:fs";
import { join } from "node:path";

const alwaysOnPath = join(getAgentDir(), ".i-have-adhd-always");

if (existsSync(alwaysOnPath)) {
  console.log("🟢 ADHD mode will start automatically.");
} else {
  console.log("⚪ ADHD mode requires manual activation.");
}

```

**Example 2: Extension Initialization**

```typescript
import { getAgentDir } from "@earendil-works/pi-coding-agent";
import { join } from "node:path";
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default function iHaveAdhdExtension(pi: ExtensionAPI) {
  const alwaysOnFlag = join(getAgentDir(), ".i-have-adhd-always");
  
  // Check persistent flag or runtime flag
  const isEnabled = pi.getFlag("adhd") || existsSync(alwaysOnFlag);
  
  if (isEnabled) {
    pi.registerFormatter("adhd", adhdFormatter);
  }
}

```

**Example 3: Toggling Persistent State**

```typescript
import { getAgentDir } from "@earendil-works/pi-coding-agent";
import { writeFileSync, unlinkSync, existsSync } from "node:fs";
import { join } from "node:path";

const flagPath = join(getAgentDir(), ".i-have-adhd-always");

export function togglePersistentAdhdMode(enable: boolean): void {
  if (enable && !existsSync(flagPath)) {
    writeFileSync(flagPath, "");
  } else if (!enable && existsSync(flagPath)) {
    unlinkSync(flagPath);
  }
}

```

## Summary

- **`getAgentDir`** originates from the **@earendil-works/pi-coding-agent** package and returns the absolute path to the agent’s installation directory.
- The i-have-adhd extension uses this function to construct a path to `.i-have-adhd-always`, a sentinel file that controls automatic activation of ADHD-friendly formatting.
- Located in [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts), the implementation checks this flag file during startup to determine whether to enable specialized output rules defined in [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md).
- This architecture eliminates hard-coded paths, ensuring cross-platform compatibility and persistent configuration storage within the agent’s own file system.

## Frequently Asked Questions

### What package provides the getAgentDir function?

The `getAgentDir` function is exported by **@earendil-works/pi-coding-agent**, a dependency listed in the i-have-adhd project’s [`package.json`](https://github.com/ayghri/i-have-adhd/blob/main/package.json). This package provides filesystem utilities specifically designed for Pi coding agent extensions.

### Why does i-have-adhd use getAgentDir instead of hardcoded paths?

Hardcoded paths would break across different operating systems and installation methods. `getAgentDir` dynamically resolves the agent’s actual installation location, ensuring the `.i-have-adhd-always` flag file is always found regardless of where the Pi coding agent is installed on the host system.

### Where is the .i-have-adhd-always flag file physically stored?

The flag file resides in the root directory returned by `getAgentDir()`, typically within the Pi coding agent’s installation folder. The exact location varies by platform and installation method, but the function guarantees the correct path is resolved at runtime.

### How does getAgentDir affect the extension's startup behavior?

During initialization in [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts), the extension calls `getAgentDir()` to locate the flag file. If `existsSync()` detects the file, the extension automatically enables ADHD-friendly formatting for that session, creating a persistent "always-on" behavior that survives across agent restarts.