pi-script-tools

Auto-discovers .sh scripts and registers them as Pi tools, so the LLM can call them alongside built-in tools like read, write, and bash.

How It Works

At each session start, the extension scans two directories for .sh files:

Scope	Path
Global	~/.pi/agent/scripts/*.sh
Project-local	./.pi/scripts/*.sh

Each script is parsed for metadata in its comment header, then registered as a Pi tool via pi.registerTool(). Project-local scripts override global scripts if they share the same tool name.

Metadata Comments

Scripts declare their metadata with comment headers at the top:

#!/bin/bash
# Name: gather_logs
# Description: Retrieves recent system logs from journalctl or syslog fallback
# Usage: gather_logs [entry_count]
# Timeout: 60000

entry_count="${1:-20}"
journalctl -n "$entry_count" --no-pager 2>/dev/null || tail -n "$entry_count" /var/log/syslog

Comment	Purpose	Default if omitted
# Name: <name>	Tool name base (<name>_sh)	Filename, hyphens → underscores, _sh appended
# Description: <text>	Shown to the LLM	(no description)
# Usage: <text>	Appended to description	Omitted
# Timeout: <ms>	Max execution time	30000 (30s)

The # Name: value must match ^[a-z0-9_]+$ or the filename is used as fallback.

Tool Parameters

Every registered tool accepts a single optional parameter:

{ "args": "value1 value2" }

Space-separated values are passed to the script as $1, $2, etc. Scripts are executed via execFile("bash", [scriptPath, ...args], { cwd, timeout }) — no shell is spawned, so arguments cannot contain shell metacharacters.

Getting Started

1. Install the extension

Place this directory (or a clone) under your Pi extensions folder:

~/.pi/agent/extensions/pi-script-tools/

Restart Pi to load the extension.

2. Create your scripts

Drop .sh files into either directory:

Global (available in every project):

mkdir -p ~/.pi/agent/scripts

Project-local (overrides global, scoped to a project):

mkdir -p ./.pi/scripts

3. Write a script

Example — ~/.pi/agent/scripts/check-disk.sh:

#!/bin/bash
# Name: check_disk
# Description: Reports disk usage for the current project directory
# Usage: check_disk [path]
# Timeout: 15000

target="${1:-.}"
du -sh "$target" 2>/dev/null || echo "Could not read disk usage for $target"

This registers as the tool check_disk_sh. The LLM can call it with:

{ "args": "/home/user/my-project" }

4. Use in a persona

Script tools appear in pi.getAllTools() automatically, so they show up in the persona wizard's tool selector alongside built-in tools. Select which script tools a persona is allowed to use during creation or editing.

Lifecycle

• session_start — Scripts are discovered and tools are registered
• /reload — Pi reloads the extension, re-scans directories, re-registers tools
• session_shutdown — No cleanup needed; tools are unregistered when the extension tears down

Error Handling

Scenario	Behavior
Missing script directory	Silently skipped
Unreadable .sh file	Skipped
Invalid # Name:	Falls back to filename-derived name
Invalid # Timeout:	Uses default 30000ms
Script exits with non-zero code	Returns stderr as the tool result

Project Structure

pi-script-tools/
├── index.ts              # Extension entry point
├── metadata.ts           # Comment-header parsing
├── discovery.ts          # Directory scanning & merge logic
├── scripts/              # Example scripts
│   └── gather-logs.sh
├── test/                 # Test suite (30 tests)
│   ├── metadata.test.ts
│   ├── discovery.test.ts
│   └── index.test.ts
├── package.json
├── tsconfig.json
└── jest.config.js

Running Tests

npm install
npm test