ProtectMe is a Pi extension for coding agents. It guards supported shell-network requests made by Pi agents or direct !/!! user bash commands, checks destinations against global and project allow lists, and blocks disallowed hosts before execution.

• Network guard boundary: covers supported curl, wget, http, and https invocations from Pi agent bash calls and Pi user bash commands.
• Allow-list policy: default block mode permits a small developer starter list and denies other unknown hosts; allow mode is available as an explicit temporary bypass.
• Project-aware configuration: trusted project config can extend global allow lists and override mode.
• Prompted approvals: repeated blocked hosts can be allowed once or added to a user-selected project/global config when Pi UI confirmation is available.
• Secret-aware logging: blocked-attempt logs are local, bounded, and redact common credential-bearing command fragments.

Security: pi packages run with your full system permissions. ProtectMe is a guardrail for supported Pi command flows, not a sandbox, firewall, or proxy. Read SECURITY.md.

Table of Contents

• Quick Start
• Installation
• Configuration
• Commands and Tools
• Troubleshooting
• Development and Validation
• Update and Uninstall
• Publishing
• License

Quick Start

pi install npm:@senad-d/protectme

Review the built-in starter allow list and add any narrow project-specific hosts as shown in Configuration, then start pi:

pi

Open the ProtectMe panel:

/protectme

Try a guarded request through Pi:

Ask the agent to run curl https://example.com only if ProtectMe allows the host; otherwise explain the block.

ProtectMe guards supported request-making shell commands. It does not run scanners, make network calls itself, or require API credentials.

Installation

| Scope | Command | Notes | | --- | --- | --- | | Global | pi install npm:@senad-d/protectme | Loads in every trusted pi project. | | Project-local | pi install npm:@senad-d/protectme -l | Writes to .pi/settings.json in the current project. | | One run | pi -e npm:@senad-d/protectme | Try without changing settings. | | Git | pi install git:github.com/senad-d/ProtectMe@<tag> | Pin a tag or commit. | | Local checkout | pi --no-extensions -e . | Develop or smoke-test this repository in isolation. |

Source checkout:

git clone https://github.com/senad-d/ProtectMe.git
cd ProtectMe
npm ci
npm run validate
pi --no-extensions -e .

Configuration

ProtectMe reads JSON config from global and project-local files. It does not require secrets. On runtime load, it creates a missing global config at ~/.pi/agent/protectme.json with the built-in defaults; project config is still only written when you explicitly confirm a /protectme edit or repeated-block prompt.

| Scope | Path | Notes | | --- | --- | --- | | Global | ~/.pi/agent/protectme.json | Applies across projects. PI_CODING_AGENT_DIR moves this path in standard Pi installations. | | Project | .pi/protectme.json | Applies only when Pi reports the project as trusted. | | Block log | .pi/agent/protectme_log.jsonl | Append-only local log for blocked attempts. Allowed requests are not logged. |

Schema:

{
  "mode": "block",
  "allowList": ["example.com", "api.example2.com"]
}

Fields:

| Field | Required | Meaning | | --- | --- | --- | | mode | No | "block" blocks disallowed hosts. "allow" permits detected requests without prompts or blocked-attempt logs. | | allowList | No | Host entries allowed in block mode. Entries are normalized and deduplicated. |

A missing global config is initialized automatically with mode: "block" and this built-in starter allow list:

{
  "mode": "block",
  "allowList": [
    "localhost",
    "127.0.0.1",
    "::1",
    "pi.dev",
    "github.com",
    "npmjs.com",
    "registry.npmjs.org",
    "nodejs.org"
  ]
}

Resolution order:

• Built-in starter entries load first.
• Global config appends additional allowList entries.
• Trusted project config appends additional allowList entries.
• Trusted project mode overrides global mode when present.
• Untrusted project config is ignored without reading project-local contents.
• Invalid or unreadable loaded config fails closed with mode: "block" and an empty effective allow list.

Host matching rules:

• example.com allows example.com, paths on that host, and child subdomains such as api.example.com.
• api.example2.com allows itself and child subdomains, but not parent domain example2.com.
• Public suffix entries such as com or co.uk are ignored and reported as warnings.
• Single-label non-localhost entries such as internal-service match only that exact host.
• localhost, IPv4, and IPv6 entries match exactly, including ports such as localhost:3000.
• Local subdomains such as app.localhost are not covered by localhost; add app.localhost or another exact local hostname to your project allow list when needed.

Blocked-attempt log retention:

• .pi/agent/protectme_log.jsonl is append-only local state for blocked attempts.
• ProtectMe reads recent entries with a bounded tail window and does not compact, upload, or delete the log.
• Delete or truncate .pi/agent/protectme_log.jsonl if you want to clear local history.

Commands and Tools

| Surface | Name | Use it for | | --- | --- | --- | | Command | /protectme | Inspect effective config, edit project settings, and view recent blocked hosts in Pi TUI mode. | | Event guard | tool_call | Block unsupported destinations in agent bash tool calls before execution. | | Event guard | user_bash | Block unsupported destinations in direct Pi !/!! user bash commands before execution. | | Custom tools | None | ProtectMe is event-based and does not register agent tools. |

Guarded request CLIs:

• curl
• wget
• http
• https

ProtectMe also inspects approved non-network wrappers such as sudo, env, time, timeout, and nice when they launch a supported request CLI. URL-bearing proxy and resolver options are treated as additional destinations. Static option sources that can hide destinations, such as curl --config or wget --input-file, fail closed.

Suggested workflow:

1. Start with /protectme to inspect mode, trust status, and allow-list counts.
2. Keep mode as block and add only the narrow project-specific hosts you need, such as app.localhost for local subdomain testing.
3. Let the agent or direct Pi !/!! commands run supported request CLIs normally.
4. Review repeated-block prompts carefully before allowing once or choosing which config file receives a saved allow-list entry.

Troubleshooting

| Problem | Try | | --- | --- | | Unexpected block | Run /protectme, inspect mode and counts, then add the intended host to project config or global config. | | Config warning | Fix invalid JSON, schema errors, unreadable files, or ignored invalid allow-list entries. | | Project config ignored | Trust the project in Pi or use global config. ProtectMe does not read untrusted .pi/protectme.json. | | Prompt unavailable | Use Pi TUI mode for confirmation prompts, or edit config manually. Repeated attempts fail closed without UI confirmation. | | Direct shell command was not blocked | Run commands through Pi !/!!; commands outside Pi are outside ProtectMe's boundary. | | Unsupported CLI was not blocked | ProtectMe v1 covers curl, wget, http, and https; use OS/container controls for other network tools. | | Need a temporary bypass | Set project config to { "mode": "allow" }, then switch back to block when finished. | | Want a clean smoke test | Run pi --no-extensions -e . from this repository. |

Development and Validation

npm ci
npm run typecheck
npm run lint
npm run format:check
npm run test
npm run test:coverage
npm run check:pack
npm run validate

Isolated interactive smoke test:

pi --no-extensions -e .

npm run validate includes type checking, ESLint, formatting checks, script syntax checks, automated tests, and package dry-run validation. CI runs the same validation chain.

Project docs:

• docs/STRUCTURE.md — repository layout and runtime boundaries.
• docs/manual-smoke-test.md — isolated Pi smoke-test checklist.
• docs/configuration-tui-design-standard.md — /protectme TUI design standard.
• specs/spec-protectme-architecture.md — architecture plan.
• specs/spec-protectme-guidelines.md — implementation guidelines.
• specs/spec-protectme-tasks.md — implementation task list.

Update and Uninstall

pi update --extensions                    # update installed pi packages
pi update npm:@senad-d/protectme          # update ProtectMe only
pi remove npm:@senad-d/protectme          # remove global install
pi remove npm:@senad-d/protectme -l       # remove project-local install

Publishing

ProtectMe publishes to npm as @senad-d/protectme.

npm login
npm whoami
node scripts/publish-npm.mjs

Run the publish script only from a clean working tree after updating CHANGELOG.md.

License

MIT