# Proton Pass Agent

> Runs commands that load pass:// secrets through an isolated Proton Pass agent session, automatically logging in again from a local agent PAT when the two-hour session expires. Use for unattended credentialed tools after logout or reboot.

- Skill: `bgevorkian/proton-pass-agent` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add bgevorkian/proton-pass-agent`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bgevorkian/proton-pass-agent/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: bgevorkian (https://skillmd.com/u/bgevorkian)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bgevorkian/proton-pass-agent

---


# Proton Pass agent

Run commands that may invoke `pass-cli run` through an isolated, automatically restored Proton Pass agent session.

```bash
scripts/run.sh --reason "Resolve credentials for the requested database inspection" -- \
  <credentialed-command>
```

The command itself does not need modification. The helper temporarily places a skill-local `pass-cli` wrapper first in `PATH`, so nested `pass-cli run` calls use the agent session. Other `pass-cli` subcommands delegate unchanged to the original CLI.

## Setup

1. Install and log in to [Proton Pass CLI](https://protonpass.github.io/pass-cli/).
2. Create a Proton Pass agent with the shortest practical expiration and viewer access only to required vaults or items. Agent and access changes are mutations: show the exact name, expiration, resources, and role, then obtain fresh user approval.
3. Save only the raw agent PAT in the token file. Never paste it into chat, logs, command arguments, documentation, or Git.

Default private state:

```text
${XDG_STATE_HOME:-$HOME/.local/state}/proton-pass-agent/
├── agent.pat       # regular user-owned file, mode 0600
└── session/        # isolated filesystem-backed CLI session
```

Override locations when needed:

| Variable | Purpose |
|---|---|
| `PROTON_PASS_AGENT_STATE_DIR` | State directory containing the session and lock |
| `PROTON_PASS_AGENT_TOKEN_FILE` | Raw agent PAT file |
| `PROTON_PASS_CLI` | Real `pass-cli` executable to delegate to |

The state directory is created with mode `0700`. The token file must already exist, must not be a symlink, and must be owned by the current user with mode `0600`.

## Behavior

- Every invocation requires a specific, non-secret audit reason of at most 300 characters.
- `flock` serializes session validation and login; ordinary reads may still run concurrently.
- Failed session validation triggers a forced cleanup, PAT login, and a second validation.
- The PAT is passed only in the login process environment and is never exported to the credentialed child command.
- The owner's normal Proton Pass session is not reused or replaced.
- Agent PATs expire after at most one year; agent CLI sessions last two hours and are recreated while the PAT remains valid.
- Access to newly created vaults is not automatic. Grant it only after fresh approval.

## Tests

```bash
tests/test_wrapper.sh
```