@4meta5/pi-zsh
Allowlist-based secure Zsh script runner
Install & Use
Copy this prompt and send it to your AI assistant (Claude / Cursor / TRAE / Codex / WorkBuddy etc.) to auto-install:
Help me install this AI Skill: @4meta5/pi-zsh. It is used for: Allowlist-based secure Zsh script runner Full Skill content: https://321skill.com/skills/4meta5-pi-zsh/raw/index.md Read that page and install it.
The prompt includes a link to the full Skill content. You can also view the full content.
This Skill addresses the security risks when AI coding agents execute shell scripts. In real-world development, developers often need AI agents to run custom scripts, but directly exposing shell permissions can lead to security vulnerabilities such as arbitrary command execution and data leaks. pi-zsh enforces an allowlist mechanism, permitting only pre-authorized .zsh scripts to run while restricting the scope of environment variables, thereby preventing unauthorized operations at the source.
Usage is straightforward: first install the npm package, then create a JSON-formatted allowlist file that defines each script's path, default arguments, and working directory mode. Next, set the environment variable PI_ZSH_ALLOWLIST_FILE to point to this file, and finally load pi-zsh as a pi extension. After setup, you can invoke the zsh_script_run tool via natural language instructions, specifying a script_id to execute the corresponding script. All output is automatically truncated to protect context safety.
It is well-suited for teams or individuals who need to add secure shell execution capabilities to AI coding agents (such as pi). This is especially relevant for DevOps engineers, agent developers, and backend developers who already use pi as a development assistant but are concerned about agents executing dangerous commands beyond their authority. For scenarios requiring strict control over script execution scope to prevent agent behavior from becoming unmanageable, this Skill is an ideal choice.
When configuring the allowlist, it is recommended to only add scripts that have undergone rigorous review and to keep the environment variable allowlist as minimal as possible. Note that it focuses on a single responsibility—running allowlisted scripts—and does not support arbitrary command execution, scheduling, or orchestration. If an agent requires more complex shell interactions, it may need to be used in conjunction with other tools.
Key Features
Unlike tools that directly execute bash commands, pi-zsh enforces a mandatory allowlist mechanism: only scripts pre-registered in the JSON configuration can run, and environment variables also require explicit allowlisting, providing a stricter security boundary. In contrast, typical shell tools generally allow arbitrary command execution, relying on external constraints for security.
Limitations
Supports only .zsh scripts, requires a Node.js environment, depends on the pi coding agent framework, does not support Windows platforms, and output is truncated (maximum length determined by configuration).
FAQ
How do I add a new executable script?
Add a new script_id entry in the allowlist object of the JSON allowlist file, specifying the absolute path, default arguments, and cwd_mode, then reload the extension.
What happens if the environment variable allowlist is empty?
If envAllowlist is set to an empty array, pi-zsh will require interactive decision-making at runtime; in non-UI mode, it will return an error and prompt the user to supplement the allowlist.
Installation guide for AI assistants
If your AI coding assistant (Claude Code, Cursor, TRAE etc.) can see this page, send it this message to auto-install:
Visit https://321skill.com/skills/4meta5-pi-zsh/raw/index.md to read the original Skill definition (Markdown format) for @4meta5/pi-zsh, and install it according to the instructions.
Raw Markdown URL for AI: /skills/4meta5-pi-zsh/raw/index.md