agent-access

Use this skill when you need to sign into a website, retrieve a login, look up a password, or get a TOTP code. aac fetches credentials (username, password, TOTP, URI, notes) from the user's Bitwarden vault through a trusted paired device.

When to use this

• The user asks you to log into a website or service
• You need a username and/or password for a domain
• You need a TOTP / 2FA code for authentication
• You need an API key or secret stored in the vault
• The user says "get my credentials for X" or "sign into X"

Quick start (agent flow)

Step 1 — Check for an existing session:

aac connections list

Step 2 — Fetch the credential using the website's domain:

aac --domain example.com --output json

If only one session is cached, it auto-selects. With multiple sessions, add --session <HEX> (use a fingerprint or unique prefix from connections list).

Step 3 — Parse the JSON output:

{
  "success": true,
  "domain": "example.com",
  "credential": {
    "username": "user@example.com",
    "password": "s3cret",
    "totp": "123456",
    "uri": "https://example.com/login",
    "notes": "optional notes"
  }
}

Use credential.username and credential.password to sign in. If the site requires 2FA, use credential.totp.

If no session exists

The user must pair with a trusted device first. Ask them to:

1. Run aac listen on their trusted device
2. Give you the pairing token (e.g. ABC-DEF-GHI)

Then connect with:

aac --domain example.com --token <CODE> --output json

Alternatively, for PSK tokens (format: <64-hex-psk>_<64-hex-fingerprint>):

aac --domain example.com --token <PSK_TOKEN> --output json

Sessions are cached in ~/.access-protocol/ for future use — subsequent requests don't need a token.

Domain matching

Use the bare domain of the website you need credentials for:

• github.com (not https://github.com/login)
• accounts.google.com (not https://accounts.google.com/v3/signin)
• aws.amazon.com

All options

Session management

aac connections list                          # List all cached sessions
aac connections clear                         # Clear all sessions and identity keys
aac connections clear sessions                # Clear sessions only, keep identity key

Error handling

On failure, JSON output:

{"success": false, "error": {"message": "...", "code": "connection_failed"}}

Exit codes:

If exit code is 3, try aac connections clear sessions and ask the user for a new token. If exit code is 4, confirm the domain with the user — they may store it under a different name.