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

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. 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, the extension constructs a path to a hidden configuration flag by appending .i-have-adhd-always to the agent directory:

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:

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 – Core extension implementation that imports getAgentDir, constructs the flag file path, and implements the conditional activation logic.
• package.json – Declares the @earendil-works/pi-coding-agent dependency that provides the getAgentDir utility.
• 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

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

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

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, the implementation checks this flag file during startup to determine whether to enable specialized output rules defined in 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. 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, 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.

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