@thurstonsand/pi-librarian 0.3.0 → 0.3.1

package/README.md

@@ -8,14 +8,21 @@ A GitHub research subagent for the [pi coding agent](https://github.com/badlogic
 
 ## How it works
 
-The `librarian` tool spawns a nested research agent with purpose-built tools:
+The `librarian` tool spawns a research subagent with purpose-built tools:
 
-- **`checkout_repo`** — clone into a local cache; pi's own `grep`/`read`/`find` then work on real files, and `git log -S`/`blame`/`diff` cover history.
-- **`search_repos`** — GitHub repository discovery (stars, topics, language).
+- **`checkout_repo`** — clone into a local cache, where it can be read locally, and `git log -S`/`blame`/`diff` covers history.
+- **`search_repos`** — GitHub repository discovery (stars, topics, other metadata).
 - **`search_code`** — cross-repo public code search via [Grep](https://grep.app/) (regex, global discovery, repo/language/path filters).
 - **`search_github_code`** — GitHub REST code search over public code and private repositories your configured GitHub auth can access.
 - **`read_github_file`** — single-file API reads for quick peeks without cloning.
 
+## Usage
+
+- Ask pi a question involving other repos; it asks the `librarian`.
+- Ask follow-up questions to earlier librarian runs.
+- `/librarian` attaches the research tools directly to your session for direct tool usage.
+- Recommended: install [pi-web-access](https://pi.dev/packages/pi-web-access) (or your web search of choice, tho this one is zero-config to get started) and add `web_search`, `fetch_content`, `get_search_content` to `librarian.tools` to expand past GitHub-only research.
+
 ## GitHub auth for private repos
 
 Public GitHub reads work without configuration. To let the librarian search and read private GitHub repositories, provide a token in one of these ways:
@@ -23,13 +30,7 @@ Public GitHub reads work without configuration. To let the librarian search and
 1. Set `GITHUB_TOKEN` or `GH_TOKEN` in the environment before starting pi.
 2. Or authenticate the GitHub CLI so `gh auth token` returns a token:
 
-The token is loaded once per pi session and passed to GitHub REST calls used by `search_repos`, `search_github_code`, `checkout_repo`, and `read_github_file`. For private repositories, use a token with read access to the target repos.
-
-## Usage
-
-- Ask pi a question involving other repos; it delegates to the `librarian` tool.
-- Ask follow-up questions to earlier librarian runs.
-- `/librarian` attaches the research tools directly to your session for manual lookups.
+The token is loaded once per pi session and used for github access in `search_repos`, `search_github_code`, `checkout_repo`, and `read_github_file`. For private repositories, use a token with read access to the target repos.
 
 ## Configuration
 
@@ -40,7 +41,7 @@ In pi's global `settings.json`:
   "librarian": {
     "model": "openai-codex/gpt-5.5",
     "thinkingLevel": "off",
-    "tools": ["search_web", "fetch_web"],
+    "tools": ["web_search", "fetch_content", "get_search_content"],
     "extensions": ["~/.pi/agent/extensions/parallel-web-tools"],
     "cacheDir": "/tmp/pi-librarian",
     "debug": { "persistRuns": false },
@@ -48,16 +49,16 @@ In pi's global `settings.json`:
 }
 ```
 
-| Setting             | Recommended                                     | Default                        |
-| ------------------- | ----------------------------------------------- | ------------------------------ |
-| `model`             | `openai-codex/gpt-5.5`                          | current session model          |
-| `thinkingLevel`     | `off`                                           | current session thinking level |
-| `tools`             | names of extra tools to activate, when needed   | `[]`                           |
-| `extensions`        | escape hatch paths for tools not loaded in pi   | `[]`                           |
-| `cacheDir`          | `/tmp/pi-librarian`                             | `/tmp/pi-librarian`            |
-| `debug.persistRuns` | persist nested session file paths for debugging | `false`                        |
+| Setting             | Recommended                                      | Default                        |
+| ------------------- | ------------------------------------------------ | ------------------------------ |
+| `model`             | `openai-codex/gpt-5.5`                           | current session model          |
+| `thinkingLevel`     | `off`                                            | current session thinking level |
+| `tools`             | names of extra tools to provide the librarian    | `[]`                           |
+| `extensions`        | extra paths to load extensions for the librarian | `[]`                           |
+| `cacheDir`          | `/tmp/pi-librarian`                              | `/tmp/pi-librarian`            |
+| `debug.persistRuns` | persist nested session file paths for debugging  | `false`                        |
 
-`librarian.tools` is the activation gate for extra tools. `librarian.extensions` only adds extension paths to the search space when a named tool is not already loaded in the main pi session; listing an extension path does not activate every tool in that bundle. Librarian runs exclude `write` and `edit`.
+`librarian.extensions` dynamically loads extra extensions just for the librarian. Add any tools from that extension to `librarian.tools` for the librarian to actually be able to use them. Librarian excludes `write` and `edit`.
 
 ## Development
 

package/RELEASE.md

@@ -2,6 +2,12 @@
 
 # Release notes
 
+## 0.3.1
+
+### Changed
+
+- Sharpened the research tools' prompt snippets, guidelines, and descriptions so the librarian names each tool explicitly and reads its guidance as directive instructions.
+
 ## 0.3.0
 
 Hardens librarian research tools and aligns GitHub file reads with pi's native `read` tool.

package/extensions/librarian/tools/checkout-repo.ts

@@ -29,10 +29,10 @@ export function createCheckoutRepoTool(cacheDir: string) {
     name: LIBRARIAN_TOOL_NAMES.checkoutRepo,
     label: "Checkout repo",
     description: "Clone a repo (blob-less partial clone, cached locally).",
-    promptSnippet: "Clone a repo",
+    promptSnippet: "Clone a repo locally",
     promptGuidelines: [
-      "Use when you want to deep dive on a specific repo. Follow up using grep/read/find/ls on the returned path, and `git -C <path> log/blame/diff` for history.",
-      "Do not checkout repos directly using `git`. Always use this tool instead.",
+      "Use checkout_repo to deep dive on a specific repo, then grep/read/find/ls on the returned path and `git -C <path> log/blame/diff` for history.",
+      "Do not clone repos directly with `git`; always use checkout_repo.",
     ],
     parameters: CheckoutRepoParams,
 

package/extensions/librarian/tools/provide-results.ts

@@ -46,10 +46,9 @@ export function createProvideResultsTool(onFindings: (findings: Findings) => voi
     name: LIBRARIAN_TOOL_NAMES.provideResults,
     label: "Provide results",
     description: "Report your findings in structured form.",
-    promptSnippet: "Provide results",
+    promptSnippet: "Report findings",
     promptGuidelines: [
-      "Tool must be called before the turn ends.",
-      "After calling this tool, the turn will end.",
+      "provide_results ends the turn; call it once, after you've gathered your findings.",
     ],
     parameters: FindingsSchema,
 

package/extensions/librarian/tools/read-github-file.ts

@@ -47,11 +47,11 @@ export function createReadGitHubFileTool(githubClient: GitHubClientProvider) {
     name: LIBRARIAN_TOOL_NAMES.readGitHubFile,
     label: "Read GitHub file",
     description: `Read a single file (or list a directory) from a GitHub repo via the API, without cloning.`,
-    promptSnippet: "Read Github file",
+    promptSnippet: "Read a file/directory from GitHub",
     promptGuidelines: [
-      "For quick peeks — package.json, a README, one source file.",
-      "For multi-file exploration prefer checkout_repo.",
-      "Use offset/limit for larger files.",
+      "Use read_github_file for quick peeks — package.json, a README, one source file.",
+      "For multi-file exploration, prefer checkout_repo over read_github_file.",
+      "Use read_github_file's offset/limit for larger files.",
     ],
     parameters: ReadGitHubFileParams,
 

package/extensions/librarian/tools/search-code.ts

@@ -18,7 +18,8 @@ const SearchCodeParams = Type.Object({
   }),
   regex: Type.Optional(
     Type.Boolean({
-      description: "Treat `pattern` as a regular expression instead of literals.",
+      description:
+        "Treat `pattern` as a regular expression instead of literals. Supports `(?s)` for multi-line patterns.",
     }),
   ),
   repo: Type.Optional(
@@ -59,11 +60,10 @@ export const searchCodeTool = defineTool<typeof SearchCodeParams, SearchCodeDeta
   name: LIBRARIAN_TOOL_NAMES.searchCode,
   label: "Search code across repos",
   description: "Cross-repo code search over public source code.",
-  promptSnippet: "Search code across repos",
+  promptSnippet: "Search public code across repos",
   promptGuidelines: [
-    "When `regex` is true, `pattern` can also use `(?s)` for multi-line patterns.",
-    "Results are CANDIDATES to verify via checkout_repo/read_github_file — never cite them directly.",
-    "This searches public GitHub code only. Use search_github_code when private repository access matters.",
+    "search_code results are candidates to verify via checkout_repo/read_github_file — never cite them directly.",
+    "search_code covers public GitHub code only; use search_github_code when private repository access is required.",
   ],
   parameters: SearchCodeParams,
 

package/extensions/librarian/tools/search-github-code.ts

@@ -89,10 +89,9 @@ export function createSearchGitHubCodeTool(githubClient: GitHubClientProvider) {
     label: "Search GitHub code",
     description:
       "GitHub REST code search over public code and private repositories your configured GitHub auth can access.",
-    promptSnippet: "Search GitHub code",
+    promptSnippet: "Search GitHub code (incl. private repos)",
     promptGuidelines: [
-      "Results are CANDIDATES to verify via checkout_repo/read_github_file — never cite them directly.",
-      "GitHub REST code search is literal/tokenized and does not support regex; use search_code for public regex/global code search.",
+      "search_github_code is literal/tokenized and does not support regex; use search_code for public regex/global search.",
     ],
     parameters: SearchGitHubCodeParams,
 

package/extensions/librarian/tools/search-repos.ts

@@ -34,8 +34,8 @@ export function createSearchReposTool(githubClient: GitHubClientProvider) {
     name: LIBRARIAN_TOOL_NAMES.searchRepos,
     label: "Search repos metadata",
     description: "Discover GitHub repositories.",
-    promptSnippet: "Search repos metadata",
-    promptGuidelines: ["Use for questions like 'what are the popular X libraries'."],
+    promptSnippet: "Search GitHub repos by metadata",
+    promptGuidelines: ['Use search_repos for questions like "what are the popular X libraries".'],
     parameters: SearchReposParams,
 
     async execute(_toolCallId, params) {

package/extensions/librarian.ts

@@ -61,7 +61,6 @@ export default function librarianExtension(pi: ExtensionAPI): void {
   for (const tool of attachableTools) {
     pi.registerTool({
       ...tool,
-      description: `${tool.description} (Librarian tool, attached via /librarian: use for quick single lookups; delegate multi-step research to the librarian tool.)`,
       renderCall(args, theme) {
         const { verb, subject } = formatTraceLine(
           { name: tool.name, args, id: "", startedAt: 0 } satisfies TraceCall,
@@ -81,10 +80,9 @@ export default function librarianExtension(pi: ExtensionAPI): void {
     label: "Librarian",
     description:
       "Understand complex, multi-repo codebases, exploring cross-repo relationships, analyzing architectural patterns, finding implementations across codebases, understanding code evolution/commit history, diving deep on specific code bases, getting comprehensive feature explanations, and exploring end-to-end system design across within or across repositories.",
-    promptSnippet:
-      "librarian: research GitHub repos (implementation questions, ecosystem comparisons, usage examples) and return cited findings",
+    promptSnippet: "Research GitHub repos and codebases, returning cited findings",
     promptGuidelines: [
-      "If a single file or reference must be located, you may use other means (search for downloaded dependencies, web search, etc), but for deeper queries that will take multiple steps to resolve, prefer the librarian.",
+      "Use librarian for deep, multi-step research across repos; for a single file or reference, prefer cheaper means (downloaded dependencies, web search or fetch).",
     ],
     parameters: LibrarianParams,
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thurstonsand/pi-librarian",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "description": "GitHub research subagent for pi: deep-dive specific repos, discover across the ecosystem",
   "license": "MIT",