pi-zsh

Allowlist-only zsh script runner extension for pi coding agents.

pi-zsh does one job: run explicitly allowlisted .zsh scripts through one tool, zsh_script_run. It does not provide arbitrary shell execution, scheduling, or orchestration.

Project Docs

• README
• Code of Conduct
• Contributing
• Security
• Changelog
• MIT License

Why This Exists

Most shell integrations start tight and then drift into "run anything." pi-zsh keeps a stricter boundary:

• only allowlisted script_id values can execute
• each script path must be absolute, executable, and .zsh
• environment variables are allowlisted
• output is truncated for context safety, with optional full-output file pointer
• non-zero exit, timeout, and abort are surfaced as isError: true

Install

npm install @4meta5/pi-zsh

This package includes the pi-package keyword so it is discoverable by pi package indexing flows.

Quick Start

1. Create an allowlist file:

{
  "allowlist": {
    "cron_review": {
      "path": "/absolute/path/to/cron-review.zsh",
      "defaultArgs": [],
      "defaultCwdMode": "script_root"
    }
  },
  "envAllowlist": ["PATH", "HOME", "SHELL", "LANG", "LC_ALL"],
  "defaultTimeoutMs": 120000,
  "maxTimeoutMs": 900000
}

2. Set required config:

export PI_ZSH_ALLOWLIST_FILE=/absolute/path/to/pi-zsh-allowlist.json

3. Load as a pi extension:

pi -e /absolute/path/to/pi-zsh/src/index.ts

Tool Contract

zsh_script_run

Parameters:

• script_id (required): allowlisted script identifier
• args (optional): extra args appended after allowlist defaults
• cwd_mode (optional): script_root or caller_cwd
• timeout_ms (optional): per-call timeout clamped by config max

Returns:

• text summary plus truncated output preview
• structured details including path, argv, duration, and truncation metadata
• isError: true for non-zero exit, timeout, or abort

Config

Required:

• PI_ZSH_ALLOWLIST_FILE: absolute path to JSON config

Optional env overrides:

• PI_ZSH_ENV_ALLOWLIST
• PI_ZSH_DEFAULT_TIMEOUT_MS
• PI_ZSH_MAX_TIMEOUT_MS

Empty envAllowlist behavior:

• if config sets "envAllowlist": [], pi-zsh requires an interactive decision at runtime
• in non-UI mode, execution returns an error with remediation guidance

Author-convenience default env allowlist:

• AGENT_DISPATCH_DIR
• AGENT_DISPATCH_CMD
• CLONES_DIR
• GITHUB_TOKEN
• PATH
• HOME
• SHELL
• LANG
• LC_ALL

Scope Boundaries

In scope:

• one extension package
• one tool (zsh_script_run)
• allowlist-only script execution
• explicit failure semantics and output truncation

Out of scope:

• arbitrary command execution
• script discovery frameworks
• schedulers and orchestrators
• auth plugin orchestration
• update and migration surfaces

Development

npm run check
npm test
npm run build

License

MIT