AgentGlass

English · 简体中文

A beginner-first file approval extension for the Pi Agent.

AgentGlass is for beginners who are not familiar with shell commands, Git diffs, or file risks. It explains the file result Pi is about to produce in plain language, so the user can confirm it before the file actually changes.

0.8.1 · Windows only

Why AgentGlass?

An AI assistant may propose a technically valid file operation without making its practical impact clear to a beginner. AgentGlass keeps these questions visible:

Which file will change, what will it become, and can it be recovered if something goes wrong?

The user approves the expected outcome and impact—not a command, a tool name, or hidden model reasoning.

What a beginner sees

1. Ask Pi to read, create, or edit an ordinary project file.
2. For a change, AgentGlass shows an outcome card with the target file, expected result, risks, and recovery information.
3. The card starts on Stop. Reading details does not approve anything.
4. The user chooses Continue only when the expected result is clear.
5. AgentGlass checks the approved action again before using the one-time approval.
6. After execution, it checks only the files named in the card.

Ordinary reads do not require an approval card after the required safety checks pass.

The /agentglass menu also offers beginner task starters for creating an explanation, polishing copy, and organizing text. A starter fills the Pi editor only: you can edit the draft and must send it yourself. Any resulting file change still needs explicit approval, is checked against the files named in the card, and exposes recovery only when the evidence supports it.

After a blocked request, the same menu offers a safe next step, such as filling a smaller file-oriented request. After a supported file result, Continue with this file offers a read-only view or a new adjustment request. These actions never replay the old tool call or send a new request automatically; each new file change is checked and approved again.

Features

• Beginner-friendly explanations: focus on file results and impact instead of shell syntax or hidden reasoning.
• Safe defaults: unknown, unsupported, sensitive, linked, and out-of-scope targets are blocked.
• Small supported surface: verified Pi built-in read, write, and edit actions.
• Task starters: create an explanation, polish copy, or organize text with a short form and a draft placed in Pi's editor.
• Result follow-up: view the current file or continue adjusting it after a supported, independently checked result.
• Blocked-task guidance: get a concrete file-oriented next step when the previous request was unsupported or could not be safely confirmed.
• Editor protection: existing editor text is preserved; starters do not overwrite it, send it, or grant approval.
• Separate recovery approval: /agentglass restore requires its own approval and only uses evidence-backed recovery capability.
• Separate cleanup approval: /agentglass cleanup handles validated private AgentGlass data and cannot delete project files.
• Safe example: /agentglass example provides a fixed, no-secret file workflow.

Requirements

The currently verified environment is:

• Windows x64
• Node.js >=22.19.0
• Pi >=0.84.3 <=0.85.1

macOS and Linux are not supported by this version.

Pi must be installed first and started in an interactive terminal.

Known Pi limitation

Pi 0.85.1 may exit with RangeError: Maximum call stack size exceeded while rendering a very large built-in edit preview (reproduced at approximately 8 MiB). This happens before AgentGlass receives the tool call, so AgentGlass cannot show an approval card or verify the result. Do not treat the crash as a safe block. Until an official Pi fix is available, split very large edits into smaller steps. See Pi issue #8036.

Quick start

Install the published package

The published package is 0.8.1.

Run this in the project where you use Pi:

pi install npm:@hugo-ddt/agentglass@0.8.1

Start Pi in the project you want to protect:

pi

Then run:

/agentglass help
/agentglass example

Use /agentglass to open the menu. It contains welcome/help, task starters, blocked-task guidance, the current file result, the safe example, recovery, and cleanup when those entries are applicable.

Unsupported operations

AgentGlass does not approve or run shell commands, dependency installation, project startup, deployment, bulk deletion, process management, or unknown/custom/overridden tools. It does not claim OS-level sandboxing or protection from a malicious co-resident Pi extension modifying tool input.

If a task is blocked, ask Pi to make the request smaller or file-oriented. Do not disable AgentGlass as a way to continue a blocked task.

Recovery and private data

When complete evidence exists, the current session may offer a separately approved restore for the most recent supported single-file change. A conflict preserves later file contents.

On Windows, private recovery copies are stored under:

%PI_CODING_AGENT_DIR%\.agentglass\snapshots

These copies may contain original file bytes required for recovery and are not guaranteed to be secret-free. Uninstalling does not silently delete them or project files. Reinstalling does not restore old approval authorization.

Disable or uninstall

pi config
pi list
pi remove <installed-source>

Disabling removes AgentGlass protection from later Pi calls; it is not a bypass for a blocked action. Removing the package source is separate from approving cleanup of private recovery data.

License

MIT