@henryqw/pi-add-dir
Add external directories to a Pi session with context, skills, and file search.
Package details
Install @henryqw/pi-add-dir from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:@henryqw/pi-add-dir- Package
@henryqw/pi-add-dir- Version
3.3.0- Published
- Oct 29, 2026
- Downloads
- 3,323/mo · 747/wk
- Author
- henrywang
- License
- MIT
- Types
- extension
- Size
- 462.9 KB
- Dependencies
- 1 dependency · 3 peers
Pi manifest JSON
{
"image": "https://raw.githubusercontent.com/HenryQW/pi-harness/main/extensions/pi-add-dir/example.png",
"extensions": [
"./extensions/add-dir.ts"
]
}
Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
@henryqw/pi-add-dir
Use external context, external skills, and searchable files in Pi without copying or linking external directories.
Install
pi install npm:@henryqw/pi-add-dirUse
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.
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.