reyamira · arimxyer · Jul 2, 2026 · Jul 2, 2026
diff --git a/README.md b/README.md
@@ -24,6 +24,7 @@ Pass-CLI is a fast, secure password and API key manager that stores credentials
 - **Health Checks**: Built-in `doctor` command for vault verification and troubleshooting
 - **Cross-Platform**: Single binary for Windows, macOS (Intel/ARM), and Linux (amd64/arm64)
 - **Script-Friendly**: Clean output modes (`--quiet`, `--field`, `--masked`) for shell integration
+- **AI Agent Ready**: Purpose-built for AI coding agents — inject secrets into a command's environment with `exec` so they never reach the chat transcript, logs, or files; plus a background agent for promptless access and self-served, version-matched agent skills (`pass-cli skills`)
 - **Usage Tracking**: Automatic tracking of where credentials are used across projects
 - **Local-First**: Works offline by default, optional cloud sync via rclone
 - **Cloud Sync**: Sync vault across devices with rclone (Google Drive, Dropbox, OneDrive, S3, etc.)
@@ -161,6 +162,30 @@ pass-cli doctor
 
 For complete command reference, flags, and examples, see [docs/03-reference/command-reference.md](docs/03-reference/command-reference.md).
 
+## AI Agent Integration
+
+Pass-CLI is built to be driven safely by **AI coding agents** (Claude Code, Cursor, Codex, and similar) — not just humans at a keyboard. An agent can use your real credentials to run real commands **without the secret ever landing in the chat transcript, a log, or a file the agent's harness watches** — the leak path that plagues copy-pasting or `echo`-ing secrets.
+
+```bash
+# Hand a secret to a command — injected into the child's environment only,
+# never on stdout, the clipboard, or shell history
+pass-cli exec --set GITHUB_TOKEN=github -- gh repo list
+
+# Materialize a composite secret (a config file or connection string)
+echo 'postgres://app:${pass:db/password}@localhost/app' | pass-cli inject
+
+# Unlock once, then resolve promptlessly for the rest of the session (POSIX)
+pass-cli agent start
+
+# The CLI serves its own version-matched agent guide — agents read this first
+pass-cli skills get core
+pass-cli skills install   # drop a discovery stub into ~/.claude/skills or ~/.agents/skills
+```
+
+The agent story combines **env injection** (`exec` / `export` / `inject`, with `base64`/`basicauth` value filters), an optional **background agent** that holds the unlocked vault for promptless access, and a **`skills`** command that ships the agent usage guide *inside the binary* so the guidance never drifts from the installed version.
+
+For the full workflow and the safety model, see the [AI Agent Integration guide](docs/02-guides/ai-agents.md).
+
 ## Security
 
 **Encryption**:
@@ -205,6 +230,7 @@ For complete security details, best practices, and migration guides, see [docs/0
 **Essential Guides**:
 - [Getting Started](docs/01-getting-started/quick-start.md) - First-time setup and basic workflows
 - [Usage Guide](docs/03-reference/command-reference.md) - Complete command reference, TUI shortcuts, configuration
+- [AI Agent Integration](docs/02-guides/ai-agents.md) - Let AI coding agents use your credentials safely (env injection, background agent, `skills`)
 - [Installation](docs/01-getting-started/quick-install.md) - All installation methods and package managers
 - [Recovery Phrase](docs/02-guides/recovery-phrase.md) - BIP39 recovery phrase setup and vault recovery
 - [Security](docs/03-reference/security-architecture.md) - Encryption details, best practices, migration guides

diff --git a/docs/02-guides/_index.md b/docs/02-guides/_index.md
@@ -7,6 +7,7 @@ Task-oriented guides for common pass-cli workflows and features.
 
 {{< cards >}}
   {{< card link="basic-workflows" title="Basic Workflows" icon="cursor-click" subtitle="Daily operations - list, update, delete, generate credentials" >}}
+  {{< card link="ai-agents" title="AI Agent Integration" icon="sparkles" subtitle="Let AI coding agents use your credentials without leaking them" >}}
   {{< card link="recovery-phrase" title="Recovery Phrase" icon="shield-check" subtitle="BIP39 recovery phrase setup and vault recovery" >}}
   {{< card link="keychain-setup" title="Keychain Setup" icon="key" subtitle="Configure OS keychain integration for password storage" >}}
   {{< card link="usage-tracking" title="Usage Tracking" icon="chart-bar" subtitle="Automatic credential usage tracking by working directory" >}}

diff --git a/docs/02-guides/ai-agents.md b/docs/02-guides/ai-agents.md
@@ -0,0 +1,128 @@
+---
+title: "AI Agent Integration"
+weight: 6
+toc: true
+---
+
+pass-cli is built to be driven safely by **AI coding agents** (Claude Code,
+Cursor, Codex, Continue, and similar) — not just humans at a keyboard. An agent
+can use your real credentials to run real commands **without the secret ever
+landing in the chat transcript, a log, CI output, or a file the agent's harness
+watches**.
+
+This is the differentiator: most ways of handing a secret to an agent — pasting
+it, `echo`-ing it, capturing it into a shell variable — leak it into the
+conversation log the moment they happen. pass-cli exists to move a secret from
+your encrypted vault into the process that needs it through a channel the
+transcript never sees.
+
+## The safety model
+
+> **Never let a secret value reach the transcript, a log, or a watched file.**
+> Once a secret is in the conversation log on disk it is compromised and must be
+> rotated.
+
+Everything below is a way to satisfy that rule. The default — `exec` — passes
+the secret **only** through a child process's environment, so it never touches
+stdout, the clipboard, or shell history.
+
+## Hand a secret to a command — `exec`
+
+The primary tool. Runs a command with credentials injected as environment
+variables; pass-cli writes nothing of its own to stdout, and the child's exit
+code is propagated unchanged.
+
+```bash
+# Explicit mapping: ENV_NAME=service
+pass-cli exec --set GITHUB_TOKEN=github -- gh repo list
+
+# Multiple credentials at once
+pass-cli exec --set AWS_ACCESS_KEY_ID=aws-id --set AWS_SECRET_ACCESS_KEY=aws-secret -- aws s3 ls
+
+# Convenience form: derive the env name from the service (openai-api -> OPENAI_API)
+pass-cli exec openai-api -- python train.py
+```
+
+`exec` is read-only: it records no usage and triggers no sync push, so it is safe
+to call on a hot path.
+
+## Composite and derived secrets — `export` and `inject`
+
+- **`export`** prints shell statements to load credentials into the current
+  shell (`eval "$(pass-cli export --set GITHUB_TOKEN=github)"`). A weaker
+  boundary than `exec` — prefer `exec` when you only need to launch a command.
+- **`inject`** renders a template, replacing `${pass:service/field}` references
+  with values — the tool for a config file or a connection string that *embeds* a
+  secret:
+
+  ```bash
+  echo 'postgres://app:${pass:db/password}@localhost/app' | pass-cli inject
+  ```
+
+  References support value filters — `base64`, `base64url`, and `basicauth`
+  (`base64("user:pass")` for an HTTP `Authorization: Basic` header) — so an agent
+  never has to shell out to `base64` and risk the value on stdout:
+
+  ```bash
+  echo 'Authorization: Basic ${pass:api | basicauth}' | pass-cli inject
+  ```
+
+## Promptless access — the background agent
+
+For a session where an agent resolves many credentials, the optional background
+agent unlocks the vault once and holds it in memory, so `exec`/`export`/`inject`
+need **no master-password prompt and no key derivation** on each call:
+
+```bash
+pass-cli agent start                              # unlock once, then background itself
+pass-cli exec --set GITHUB_TOKEN=github -- gh repo list   # resolves via the agent, no prompt
+pass-cli agent stop                               # zero secrets and stop
+```
+
+It serves resolved field **values only** — the master password and derived key
+never leave the agent process — and auto-locks after inactivity (`--idle`,
+default 15m) and always after `--max-ttl` (default 8h). When no agent is running,
+every command **transparently falls back** to opening the vault directly, so the
+agent is a pure optimization, never a dependency. POSIX only for now; on Windows
+commands fall back to direct-open. See the [Background Agent](../05-operations/agent)
+reference for details.
+
+## Self-describing: `pass-cli skills`
+
+pass-cli ships an **agent usage guide inside the binary**, so an agent can load
+version-matched guidance straight from the CLI — the instructions never drift
+from the installed version:
+
+```bash
+pass-cli skills get core          # safe-usage guide: exec/export/inject/agent/list/get + leak traps
+pass-cli skills get core --full   # also include the full command reference
+pass-cli skills list              # list every skill shipped with this version
+```
+
+To make an agent discover pass-cli automatically, install a small discovery stub
+into its skills directory:
+
+```bash
+pass-cli skills install           # auto-detects ~/.claude/skills or ~/.agents/skills
+```
+
+The stub is intentionally thin — it points the agent at `pass-cli skills get
+core`, and the real, version-matched guidance stays in the binary. See
+[AI Agent Skills](../05-operations/agent-skills) for the full command.
+
+## Quickstart for agents
+
+An agent working on a user's machine can bootstrap in three commands:
+
+```bash
+pass-cli skills get core                          # learn the safe-usage rules
+pass-cli list -q                                  # discover available service names (no secrets)
+pass-cli exec --set API_KEY=some-service -- <cmd> # run a command with the secret injected
+```
+
+## Learn more
+
+- [Command Reference](../03-reference/command-reference) — every command and flag
+- [Background Agent](../05-operations/agent) — the promptless daemon in depth
+- [AI Agent Skills](../05-operations/agent-skills) — the `skills` command
+- [Scripting Guide](scripting-guide) — non-agent automation and output modes
diff --git a/docs/02-guides/scripting-guide.md b/docs/02-guides/scripting-guide.md
@@ -6,6 +6,8 @@ toc: true
 
 Automate pass-cli with scripts using quiet mode, JSON output, and environment variable integration.
 
+> **Using an AI coding agent?** See the [AI Agent Integration](ai-agents) guide for the safe way to hand secrets to agents — injected into a command's environment, never through the chat transcript.
+
 ## Output Modes
 
 Pass-CLI supports multiple output modes for different use cases.

diff --git a/docs/_index.md b/docs/_index.md
@@ -17,6 +17,7 @@ Welcome to the **pass-cli** documentation. A secure, cross-platform, always-free
 - [Quick Start](01-getting-started/quick-start) - First-time setup and initialization (5 minutes)
 - [Quick Install](01-getting-started/quick-install) - Installation instructions for all platforms
 - [Command Reference](03-reference/command-reference) - Complete command reference
+- [AI Agent Integration](02-guides/ai-agents) - Let AI coding agents use your credentials safely
 - [Recovery Phrase](02-guides/recovery-phrase) - BIP39 recovery phrase setup and usage
 - [Backup & Restore Guide](02-guides/backup-restore) - Manual vault backup management
 - [TOTP & 2FA Support](02-guides/totp-guide) - Store and generate 2FA codes
@@ -30,6 +31,7 @@ Welcome to the **pass-cli** documentation. A secure, cross-platform, always-free
 - **Cross-Platform**: Works on Windows, macOS, and Linux
 - **Keychain Integration**: Optional OS keychain support for automatic unlocking
 - **Interactive TUI**: Beautiful terminal UI built with tview
+- **AI Agent Ready**: Hand secrets to AI coding agents via env injection — never through the chat transcript
 - **Clipboard Support**: Secure clipboard integration with auto-clear
 - **Usage Tracking**: Per-credential usage statistics
 - **Audit Logging**: HMAC-signed audit logs for all operations