@henryqw/pi-add-dir 3.1.1 → 3.1.2
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 +14 -14
- 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 context, skills, and searchable files
|
|
3
|
+
Give the current Pi session the context, skills, and searchable files of external directories. Pi uses these resources in place, so you do not copy or link the directories.
|
|
4
4
|
|
|
5
5
|
|
|
6
6
|
|
|
@@ -14,19 +14,19 @@ 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` and 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
|
|
|
21
21
|
| Surface | Type | Purpose |
|
|
22
22
|
| --- | --- | --- |
|
|
23
|
-
| `/dir-add [path]` | command | Add to this session by default
|
|
24
|
-
| `/dir-ls` | command | List directories with their scope
|
|
23
|
+
| `/dir-add [path]` | command | Add to this session by default. To persist for the linked worktrees of this Git repository or for every workspace, pass `--project` or `--global` before the path. Omit the path to enter it at the prompt. Supports `~`. |
|
|
24
|
+
| `/dir-ls` | command | List directories with their scope. Select one to remove it from that scope. |
|
|
25
25
|
| `/dir-reload` | command | Reload external directory resources. |
|
|
26
26
|
| `add_directory(path)` | tool | Add a directory to this session and return its context and instructions. Model-only: codemode scripts cannot call it. |
|
|
27
|
-
| `search_external_files(pattern, maxResults?)` | tool |
|
|
27
|
+
| `search_external_files(pattern, maxResults?)` | tool | Search added directories with a glob. Returns up to 50 results by default; `maxResults` accepts up to 1,000. Returns a structured result to codemode scripts. |
|
|
28
28
|
| `@` file autocomplete | ui | Find files in added directories and insert their absolute paths. |
|
|
29
|
-
| External directory widget | ui | Show added directories and
|
|
29
|
+
| External directory widget | ui | Show added directories and refer to `/dir-ls` for management. |
|
|
30
30
|
|
|
31
31
|
Added directories give Pi these resources:
|
|
32
32
|
|
|
@@ -34,13 +34,13 @@ Added directories give Pi these resources:
|
|
|
34
34
|
- 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
|
|
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` stays session-local. 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
|
|
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 cap. `truncated` is true when the result cap 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 added directories, a call to the tool is a tool error, and scripts reject with the message.
|
|
42
42
|
|
|
43
|
-
`add_directory` is declared to the model only (Pi `model-only` exposure). Codemode scripts and other tools cannot call it,
|
|
43
|
+
`add_directory` is declared to the model only (Pi `model-only` exposure). Codemode scripts and other tools cannot call it. Thus, the `AGENTS.md`, `CLAUDE.md`, and skills of another directory enter the session only through a model-visible tool call or a user command. This package does not enable codemode.
|
|
44
44
|
|
|
45
45
|
## Config
|
|
46
46
|
|
|
@@ -50,16 +50,16 @@ Package-owned: `~/.pi/agent/config/pi-add-dir/config.json`
|
|
|
50
50
|
| --- | --- | --- | --- |
|
|
51
51
|
| `directories` | Directories loaded for every workspace. `/dir-add --global` updates this list. | Array of unique absolute paths without control characters. | `[]` |
|
|
52
52
|
|
|
53
|
-
|
|
53
|
+
If the file is missing, the extension uses the default. Invalid config stops the load, and the extension does not overwrite the file. Reload Pi after you edit the file manually.
|
|
54
54
|
|
|
55
55
|
## State and storage
|
|
56
56
|
|
|
57
|
-
Session directories
|
|
57
|
+
Session directories are stored in the current session branch. A new session addition rejects a directory that is inside the current working directory or that contains it. It also rejects a directory that overlaps another active added directory. When the working directory changes, the extension does not check restored session entries for overlap again. 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, and it stays on the local machine. Thus, `/dir-add --project` requires a Git repository.
|
|
58
58
|
|
|
59
59
|
Persistent scopes are explicit because added directories can inject `AGENTS.md`, `CLAUDE.md`, and skills.
|
|
60
60
|
|
|
61
61
|
## Limits and recovery
|
|
62
62
|
|
|
63
|
-
Search supports basename and relative-path globs. It skips `.git` and `node_modules` and does not follow symbolic links. It uses Node filesystem traversal and returns at most 1,000 results
|
|
63
|
+
Search supports basename and relative-path globs. It skips `.git` and `node_modules` and does not follow symbolic links. It uses Node filesystem traversal and returns at most 1,000 results for each call.
|
|
64
64
|
|
|
65
|
-
Missing or overlapping **project and global** directories
|
|
65
|
+
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 resolve the overlap. Then run `/dir-reload` to scan again. 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.
|