sd0xdev 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 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 skills/op-session/scripts/op-session-init.sh --list
Check Session Status
bash skills/op-session/scripts/op-session-init.sh --check
Clear Session
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 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
--sessionand--accountflags - App mode: passes only
--accountflag (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
# 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) |
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