---
title: "@henryqw/pi-add-dir"
seo:
  description: "Add external directories to a Pi session with context, skills, and file search."
---

<div class="not-prose my-6 flex flex-wrap items-center gap-3"><a href="https://www.npmjs.com/package/@henryqw/pi-add-dir" aria-label="View @henryqw/pi-add-dir version v3.4.0 on npm"><img alt="Version v3.4.0" height="20" src="https://img.shields.io/static/v1?cacheSeconds=7200&amp;color=1d4ed8&amp;label=version&amp;labelColor=6a7282&amp;style=flat-square&amp;message=v3.4.0" width="96"></a><div class="ml-auto flex flex-wrap items-center justify-end gap-3"><a href="https://www.npmjs.com/package/@henryqw/pi-add-dir" aria-label="View @henryqw/pi-add-dir on npm"><img alt="Monthly npm downloads" height="20" src="https://img.shields.io/npm/dm/%40henryqw%2Fpi-add-dir?cacheSeconds=7200&amp;color=1d4ed8&amp;label=downloads&amp;labelColor=6a7282&amp;style=flat-square" width="144"></a><a href="https://github.com/HenryQW/pi-harness/blob/main/extensions/pi-add-dir/LICENSE" aria-label="View the MIT license for @henryqw/pi-add-dir"><img alt="MIT license" height="20" src="https://img.shields.io/npm/l/%40henryqw%2Fpi-add-dir?cacheSeconds=7200&amp;color=1d4ed8&amp;label=license&amp;labelColor=6a7282&amp;style=flat-square" width="78"></a></div></div>

Use external context, external skills, and searchable files in Pi without copying or linking external directories.

![Pi using added external directories by name](https://raw.githubusercontent.com/HenryQW/pi-harness/2f18065a670bfe9845fb334653840ab7ad5e23e4/extensions/pi-add-dir/example.png)

## Install

```bash
pi install npm:@henryqw/pi-add-dir
```

## Use

Type `/dir-add ` to see described scope flags: `--project` saves a directory for the repository, and `--global` saves it for every workspace. Completion does not suggest paths.

Run `/dir-add`, enter a directory, then run `/dir-ls` to verify it. Humans use commands; agents use tools.

| Surface | Type | Purpose |
| --- | --- | --- |
| `/dir-add [--project\|--global] [path]` | command | Add to this session by default. Use `--project` for this repository and linked worktrees, or `--global` for every workspace. Omit the path for interactive input. Supports `~`. |
| `/dir-ls` | command | List directories and scopes; select one to remove it from that scope. |
| `/dir-reload` | command | Reload external directory resources. |
| `add_directory(path)` | tool | Add session-only context and return instructions. Model-only: scripts and other tools cannot call it. |
| `search_external_files(pattern, maxResults?)` | tool | Search added directories with a glob. Default: 50 results; maximum: 1,000. Codemode receives structured results. |
| `@` file autocomplete | ui | Find external files and insert absolute paths. |
| External directory widget | ui | Show directories; use `/dir-ls` to manage them. |

Pi adds root `AGENTS.md`, `CLAUDE.md`, `.pi/AGENTS.md`, and `.pi/CLAUDE.md` to later prompts. External skills come from `.pi/skills`, `.agents/skills`, and `.claude/skills`.

`/dir-add` reloads only when discovered external skill paths change, not merely because skills exist. If `add_directory` asks for `/reload`, run it to update skills.

### Child repository context

From a parent directory, run `/dir-add first repo` or call `add_directory` with `path: "first repo"`. The path is relative to the session directory. Absolute paths also work.

Session-only additions can load an explicitly selected child directory. Pi does not scan or load child repositories automatically. Only add directories whose instructions and skills you trust. This does not change the session directory or select a project for CodeGraph or other tools.

Project and global additions still reject child directories that overlap the session directory. These persistent overlap protections also apply when you promote a session addition.

### Search results

In `search_external_files` results, `truncated: true` means more matches may exist.

## Config

Package-owned: `~/.pi/agent/config/pi-add-dir/config.json`

| Name | Description | Values | Default |
| --- | --- | --- | --- |
| `directories` | Directories for every workspace. `/dir-add --global` updates this list. | Array of unique absolute paths without control characters. | `[]` |

Pi skips invalid or duplicate entries and loads the valid directories. Global additions and removals fail until you fix reported config problems. Reload Pi after manual edits. For the shared rules, see [Config files](https://pi.henry.wang/overview#config-files).

## State and storage

Session directories belong to the current session branch. New session additions accept child directories but reject the session directory itself, its ancestors, and overlaps with active external directories. Restored session entries do not repeat overlap checks when the working directory changes.

Project directories use repeatable local Git config key `pi-add-dir.directory`, shared by linked worktrees. This machine-local config cannot come from a clone. `/dir-add --project` requires a Git repository.

Select persistent scopes explicitly: external directories can inject `AGENTS.md`, `CLAUDE.md`, and skills.

## Limits and recovery

Search uses Node and supports basename and relative-path globs. It skips `.git`, `node_modules`, and symbolic links.

Missing or overlapping project and global directories stay configured but are skipped with warnings. Restore missing paths, or remove an incorrect path with `/dir-ls` and add the corrected path with `/dir-add`; then run `/dir-reload`.
