@henryqw/pi-add-dir 3.1.3 → 3.1.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +21 -13
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# `@henryqw/pi-add-dir`
|
|
2
2
|
|
|
3
|
-
Give the current Pi session
|
|
3
|
+
Give the current Pi session external context, external skills, and searchable files from external directories. Pi uses these resources in place, so you do not copy or link the directories.
|
|
4
4
|
|
|
5
5
|
|
|
6
6
|
|
|
@@ -14,7 +14,7 @@ Requires Pi 1.1.0 or later in the 1.x series.
|
|
|
14
14
|
|
|
15
15
|
## Use
|
|
16
16
|
|
|
17
|
-
Run `/dir-add
|
|
17
|
+
Run `/dir-add`. Enter a directory. Then run `/dir-ls` to make sure that Pi added it. Pi lists the directory and makes its supported resources available.
|
|
18
18
|
|
|
19
19
|
Humans use the slash commands from the Pi prompt. Pi agents use the tools.
|
|
20
20
|
|
|
@@ -28,19 +28,21 @@ Humans use the slash commands from the Pi prompt. Pi agents use the tools.
|
|
|
28
28
|
| `@` file autocomplete | ui | Find files in added directories and insert their absolute paths. |
|
|
29
29
|
| External directory widget | ui | Show added directories and refer to `/dir-ls` for management. |
|
|
30
30
|
|
|
31
|
-
|
|
31
|
+
External directories give Pi these resources:
|
|
32
32
|
|
|
33
|
-
-
|
|
34
|
-
-
|
|
33
|
+
- External context from root `AGENTS.md`, `CLAUDE.md`, `.pi/AGENTS.md`, and `.pi/CLAUDE.md` files. Pi injects them into later prompts.
|
|
34
|
+
- External skills that Pi loads from `.pi/skills`, `.agents/skills`, and `.claude/skills`.
|
|
35
35
|
- Files in the editor's `@` autocomplete, with absolute paths.
|
|
36
36
|
|
|
37
|
-
`/dir-add` reloads only when the discovered external skill paths change. A directory that contains skills does not alone cause a reload. `add_directory`
|
|
37
|
+
`/dir-add` reloads only when the discovered external skill paths change. A directory that contains skills does not alone cause a reload. `add_directory` applies only to the session. When its result asks for `/reload`, run `/reload` to update external skills.
|
|
38
38
|
|
|
39
39
|
### Programmatic use
|
|
40
40
|
|
|
41
|
-
`search_external_files` declares an output schema. Programmatic callers, such as Pi `codemode` scripts, receive `{ pattern, maxResults, searchedDirectories, totalFound, truncated, directories }`. `directories` lists each directory that has at least one match, with its label and absolute file paths. `searchedDirectories` counts only the directories that the tool searched, including directories with no matches. It does not count directories that the tool skipped after it reached the
|
|
41
|
+
`search_external_files` declares an output schema. Programmatic callers, such as Pi `codemode` scripts, receive `{ pattern, maxResults, searchedDirectories, totalFound, truncated, directories }`. `directories` lists each directory that has at least one match, with its label and absolute file paths. `searchedDirectories` counts only the directories that the tool searched, including directories with no matches. It does not count directories that the tool skipped after it reached the limit.
|
|
42
42
|
|
|
43
|
-
`
|
|
43
|
+
`truncated` is true when the result limit stopped the search. In that case, later directories or files can contain more matches. The model receives the same matches as text. If there are no external directories, a tool call returns a tool error. Scripts then reject with the error message.
|
|
44
|
+
|
|
45
|
+
Pi declares `add_directory` to the model only (Pi `model-only` exposure). Codemode scripts and other tools cannot call it. Another directory's `AGENTS.md`, `CLAUDE.md`, and skills enter the session only through a model-visible tool call or a user command. This package does not enable codemode.
|
|
44
46
|
|
|
45
47
|
## Config
|
|
46
48
|
|
|
@@ -50,16 +52,22 @@ Package-owned: `~/.pi/agent/config/pi-add-dir/config.json`
|
|
|
50
52
|
| --- | --- | --- | --- |
|
|
51
53
|
| `directories` | Directories loaded for every workspace. `/dir-add --global` updates this list. | Array of unique absolute paths without control characters. | `[]` |
|
|
52
54
|
|
|
53
|
-
If the file is missing, the extension uses the default. At launch, the extension shows a warning for each unknown key and each invalid or duplicate directory entry. It ignores that key or entry and loads the other directories. If the file is malformed or `directories` is not an array, it shows a warning and uses the default. It does not change the file.
|
|
55
|
+
If the file is missing, the extension uses the default. At launch, the extension shows a warning for each unknown key and each invalid or duplicate directory entry. It ignores that key or entry and loads the other directories. If the file is malformed or `directories` is not an array, it shows a warning and uses the default. It does not change the file.
|
|
56
|
+
|
|
57
|
+
`/dir-add --global` and global removal with `/dir-ls` fail until you fix the reported problems. Reload Pi after you edit the file manually.
|
|
54
58
|
|
|
55
59
|
## State and storage
|
|
56
60
|
|
|
57
|
-
|
|
61
|
+
The extension stores session directories in the current session branch. A new session addition rejects a directory that is inside Pi's working directory or that contains it. It also rejects a directory that overlaps another active external directory. When the working directory changes, the extension does not check restored session entries for overlap again.
|
|
58
62
|
|
|
59
|
-
|
|
63
|
+
Project directories use the repeatable local Git config key `pi-add-dir.directory` of the repository. Linked worktrees share local Git config. A cloned repository cannot inject this config. The config stays on the local machine. `/dir-add --project` therefore requires a Git repository.
|
|
64
|
+
|
|
65
|
+
You must explicitly select persistent scopes because external directories can inject `AGENTS.md`, `CLAUDE.md`, and skills.
|
|
60
66
|
|
|
61
67
|
## Limits and recovery
|
|
62
68
|
|
|
63
|
-
Search supports basename and relative-path globs. It skips `.git` and `node_modules` and does not follow symbolic links. It uses Node filesystem
|
|
69
|
+
Search supports basename and relative-path globs. It skips `.git` and `node_modules` and does not follow symbolic links. It uses Node to search the filesystem and returns at most 1,000 results for each call.
|
|
70
|
+
|
|
71
|
+
Missing or overlapping **project and global** directories stay in the config, but the extension skips them with a warning. Restore a missing directory at its original path, or correct the overlap. Then run `/dir-reload` to scan again.
|
|
64
72
|
|
|
65
|
-
|
|
73
|
+
To change or discard a configured path, use `/dir-ls` to **remove** it from its scope. If necessary, run `/dir-add` with the corrected path. `/dir-ls` cannot repair paths in place.
|