@sidshaytay/pi-secret-safe

Keep discovered secret values out of pi model requests, tool output, and session history while letting the agent use them through shell variables.

Quick start

Requires pi 0.85.1 or later (the declared minimum); this repository tests against pi 1.2.0. Current pi requires Node.js 22.19 or later.

1. Install the extension:

   pi install npm:@sidshaytay/pi-secret-safe

2. Put your credentials in a project dotenv file such as .env, or export them in your shell before starting pi. Use variable names such as OPENAI_API_KEY or DATABASE_URL so discovery can recognize them.

3. Start pi, or run /reload in an existing session, then check:

   /secret-safe status

   You should see the current mode, protected-secret count, and redaction counters. Run /secret-safe rescan after changing dotenv values.

4. Ask the agent to use the variable by name, for example: “Use $OPENAI_API_KEY in the authorization header without printing its value.”

To try the extension from this repository's root for one invocation:

pi -e ./packages/pi-secret-safe/extensions/index.ts

Use a protected value

The model sees a placeholder instead of a discovered value:

«Redacted — read as environment variable $NAME via script»

NAME is the original variable name, such as OPENAI_API_KEY, or a generated SECRET_* name for a pattern match. With exportToShell enabled (the default), the extension exports the value so bash can expand $NAME at runtime.

The placeholder avoids quotes, backslashes, colons, and equals signs so it can appear inside JSON, YAML, or TOML string values. Short URL credentials are hidden in URLs without replacing unrelated words containing the same letters.

Choose a mode

/secret-safe strict

Use /secret-safe redact or /secret-safe off to switch again. These changes last for the session; set mode in a config file for a persistent default.

Configure protection

The extension reads these JSON files in order:

1. ~/.pi/agent/secret-safe.json
2. <project>/.pi/secret-safe.json

PI_CODING_AGENT_DIR changes the personal agent directory. Project settings override personal settings, except that patterns, allowPaths, blockPaths, and extraBlockCommands accumulate. dotenvFiles replaces the earlier list. Reload after editing configuration.

For example, put this in your project's .pi/secret-safe.json:

{
  "mode": "strict",
  "dotenvFiles": [".env", ".env.local"],
  "allowPaths": ["docs/fixtures/**"],
  "extraBlockCommands": ["vault\\s+read"]
}

Each custom pattern has name, regex, and optional flags:

{
  "patterns": [
    { "name": "INTERNAL_TOKEN", "regex": "tok_[a-z0-9]{24}" }
  ]
}

Invalid config values fall back to defaults and appear in /secret-safe status.

Update or remove

Run pi update --extensions to update unpinned installations, then /reload. To stop loading this extension:

pi remove npm:@sidshaytay/pi-secret-safe

Run /reload afterward. Configuration and existing logs remain on disk. New requests and tool output will no longer receive this extension's protection.

Troubleshooting

The agent cannot use a secret in bash. Check exportToShell, run /secret-safe rescan, and have the agent reference $NAME instead of inserting the value into its command. Strict mode blocks recognized secret literals.

Strict mode blocks a legitimate operation. Allow the individual operation when prompted, or add a known-safe path to allowPaths and reload. /secret-safe redact keeps redaction while disabling blocking.

Configuration is missing or invalid. Check the paths and errors printed by /secret-safe status. Confirm the file contains valid JSON and the value types match the table.

Understand protection limits

• Detection uses known values and format patterns. Unrecognized secrets can pass through. Images are never redacted.
• Files on disk stay unchanged. The extension does not manage pi debug logs, terminal scrollback, or shell history. Rotate a credential if it has leaked.
• A user-run ! or !! command is stored as typed, even though its output is redacted. Do not type literal secrets into those commands.
• User-command output is line-buffered. Multiline secrets that are not recognized private-key blocks may partially survive in session files.
• Messages injected by another extension through sendMessage reach the session file before this extension can inspect them.
• If a redaction hook throws, pi logs the error and can continue with the original unredacted content.
• Generic assignment rules stop at #, ,, ;, }, and ]. A secret not already discovered from the environment or dotenv may retain text after those characters.

Extension integration reference

Links

Credits and adapted code · Development and tests · MIT license