op-session
/op-session
Initialize 1Password CLI session for Claude Code. Use when: starting a session that needs 1Password secrets, op CLI keeps prompting biometric auth, setting up OP_SESSION token. Solves: Claude Code's no-TTY subprocess model triggers 1Password biometric auth on every op call. Supports both token-based and App Integration auth modes — auto-detects which mode to use.
- Author
- sd0xdev ↗
- Repository
- sd0x-harness ↗
- Licence
- MIT
- Last repository change
- 08.10.2026
Assessment and security
- Files in this package
- 3
- Scripts
- 2
- HTML comments
- 0
- URLs in SKILL.md
- 1
No signals detected. Repository changed on 08.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 2 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/op-session-init.sh, scripts/op-with-session.sh
What it does and when to use it
Initialize 1Password CLI session for Claude Code. Use when: starting a session that needs 1Password secrets, op CLI keeps prompting biometric auth, setting up OP_SESSION token. Solves: Claude Code's no-TTY subprocess model triggers 1Password biometric auth on every op call. Supports both token-based and App Integration auth modes — auto-detects which mode to use.
Original author description
Initialize 1Password CLI session for Claude Code. Use when: starting a session that needs 1Password secrets, op CLI keeps prompting biometric auth, setting up OP_SESSION token. Solves: Claude Code's no-TTY subprocess model triggers 1Password biometric auth on every op call. Supports both token-based and App Integration auth modes — auto-detects which mode to use.
How it works
- Problem
- Solution
- Workflow
- Usage
- Session Lifecycle
- Session File Format
- Security
- Known Limitations
- Prerequisites
SKILL.md preview
---
name: op-session
description: "Initialize 1Password CLI session for Claude Code. Use when: starting a session that needs 1Password secrets, op CLI keeps prompting biometric auth, setting up OP_SESSION token. Solves: Claude Code's no-TTY subprocess model triggers 1Password biometric auth on every op call. Supports both token-based and App Integration auth modes — auto-detects which mode to use."
allowed-tools: Bash(bash:*)
---
# 1Password Session for Claude Code
## Problem
Claude Code executes each Bash tool call in a new subprocess without TTY. 1Password CLI's app integration binds auth to the terminal session, so every `op` call triggers a biometric prompt.
## Solution
Auto-detect the auth mode and configure accordingly:
| Mode | Condition | Behavior |
|------|-----------|----------|
| **Token** | `op signin --raw` returns a token | Cache token in `~/.op-claude-session`; wrapper passes `--session` flag |
| **App Integration** | `op signin --raw` returns empty + `op whoami` succeeds | Record mode in session file; wrapper calls `op` directly (IPC with desktop app) |
## Workflow
```
/op-session [--account <name>]
│
▼
op signin --raw
│
├─ token non-empty ──► Token mode
│ Verify → write session file → done
│
└─ token empty ──► op whoami succeeds?
├─ YES → App Integration mode
│ Write session file (no token) → done
└─ NO → ERROR: signin failed
```
## Usage
### Initialize Session
```bash
bash skills/op-session/scripts/op-session-init.sh
# or with specific account
bash skills/op-session/scripts/op-session-init.sh --account my-team
```
### List Available Accounts
```bash
bash skills/op-session/scripts/op-session-init.sh --list
```
### Check Session Status
```bash
bash skills/op-session/scripts/op-session-init.sh --check
```
### Clear Session
```bash
bash skills/op-session/scripts/op-session-init.sh --clear
```
### Subsequent `op` Calls (Recommended)
Use the secure helper script — it handles mode detection, token loading, validation, and expiry:
```bash
bash skills/op-session/scripts/op-with-session.sh read "op://vault/item/field"
bash skills/op-session/scripts/op-with-session.sh item list --vault Production
bash skills/op-session/scripts/op-with-session.sh whoami
```
The helper:
- Auto-detects auth mode from session file (`OP_AUTH_MODE`)
- Token mode: passes `--session` and `--account` flags
- App mode: passes only `--account` flag (auth via desktop app IPC)
- Validates session before each call
- Returns clear error if session is missing, expired, or app is locked
## Session Lifecycle
| Event | Token Mode | App Integration Mode |
|-------|-----------|---------------------|
| Idle timeout | 30 min → expires | 10 min → expires (auto-refresh on use) |
| Each `op` call | Resets idle timer | Resets idle timer |
| Hard limit | 12hr | 12hr |
| 1Password app locks | Does NOT revoke token | Next `op` call fails until unlocked |
| `/op-session --clear` | Removes session file | Removes session file |
## Session File Format
```bash
# Token mode
export OP_AUTH_MODE='token'
export OP_SESSION='<session-token>'
export OP_ACCOUNT='<account-id>'
# App Integration mode
export OP_AUTH_MODE='app'
export OP_SESSION=''
export OP_ACCOUNT='<account-id>'
```
Legacy session files (without `OP_AUTH_MODE`) are auto-detected as token mode if `OP_SESSION` is non-empty.
## Security
| Aspect | Token Mode | App Integration Mode |
|--------|-----------|---------------------|
| Token at rest | `~/.op-claude-session` (owner-only via `umask 077`) | No token stored |
| Process args | `--session $TOKEN` visible to same-user processes | No `--session` flag |
| Auth control | Token possession = access | Desktop app biometric |
| Scope | All vaults you can access | All vaults you can access |
| Risk level | Moderate (token on disk) | Lower (no token on disk) |
| Mitigation | Short-lived token, `--clear` when done | App auto-manages session |
## Known Limitations
| Limitation | Cause | Workaround |
|-----------|-------|------------|
| `ls` on home-dir paths blocked in `!` context checks | Claude Code sandbox may restrict `ls`/`find` to working directory in command template expansion | Use `test -f` via `bash -c` wrapper; see `skills/op-session/SKILL.md` |
| `allowed-tools` cannot be narrowed to specific script paths | `${CLAUDE_PLUGIN_ROOT}` unavailable in command markdown ([#9354](https://github.com/anthropics/claude-code/issues/9354)) | Keep `Bash(bash:*)` until upstream fix |
| Context check is best-effort UI | Sandbox policy may tighten | Authoritative status via `bash skills/op-session/scripts/op-session-init.sh --check` |
| App mode fails when desktop app is locked | CLI cannot IPC with locked app | Unlock 1Password app, or run `/op-session` to reinitialize |
## Prerequisites
- 1Password CLI (`op`) installed and configured
- 1Password desktop app running (for initial biometric auth)
- Account signed in to 1Password app
Files in this package (3)
- SKILL.md 5 KB
- scripts/op-session-init.sh 6 KB
- scripts/op-with-session.sh 2 KB
Versions
The database has no other skills named op-session.
Database snapshot: 13.11.2026 · package version 1a4f65647e67 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100mobile-biometric-auth-faceid-fingerprint
Use this skill when implementing secure biometric authentication using iOS LocalAuthentication and Android BiometricPrompt. - 100jwt
JSON Web Tokens for authentication. Covers token structure, signing, and validation. Use for stateless authentication. USE WHEN: user mentions "JWT", "token authentication", "access token", "refresh token", asks about "stateless auth", "token signing", "token validation" DO NOT… - 90flutter-security
Use when securing local storage with flutter_secure_storage, enforcing AES-256-GCM encryption, or adding biometric authentication gates. - 100agentwhy-session-audit
Checks which private files (.env, keys, secrets) Claude Code and its subagents reached in this project, whether a value came into an agent's context, and which key to change, by running the open source agentwhy CLI over the session records Claude Code already keeps on disk. Use… - 100mobile-session-security
KMP + iOS/Android session hardening for a fintech app — inactivity auto-lock (track last-interaction, idle timeout, biometric/passcode re-auth), biometric re-lock on background/foreground with a grace period, and screen-capture/snapshot protection. Android: WindowManager… - 100op-secrets
Use 1Password with Claude Code without secrets ever entering the chat, the transcript, the command line or shell history. Use when the user wants to store an API key, token, password or credential; when a tool, MCP server, hook or script needs a secret; when the user mentions…