decky-vaultwarden/AGENTS.md

AGENTS.md — decky-vaultwarden

What this is

Decky Loader plugin for Steam Deck. Provides a Bitwarden/Vaultwarden password manager client in the Decky quick access panel.

Two-language architecture:

• Python backend (main.py, bitwarden_client.py, crypto.py, clipboard.py, totp.py) — crypto, API calls, vault decryption. Loaded by Decky Loader.
• TypeScript/React frontend (src/) — UI rendered in Decky panel. Calls Python backend via Decky's call() API.

Build commands

Command	What it does
npm run build	Rollup compiles TS to dist/, then packages everything (dist + Python files + py_modules/ + plugin.json) into out/Vaultwarden.zip
npm run watch	Rollup watch mode (frontend only)
npm run typecheck	tsc --noEmit — type checking, no emit
npm run bundle-deps	Downloads Python wheels into py_modules/ (see below)

No test, lint, or formatter commands exist. No CI workflows.

Python dependency bundling

py_modules/ contains pre-compiled manylinux wheels (x86_64) for Python 3.11. These are checked into git.

To regenerate: npm run bundle-deps (runs scripts/bundle-deps.sh). Downloads wheels from PyPI and extracts them into py_modules/.

The bundled packages include: aiohttp, cryptography, argon2, pyotp, cffi, and transitive deps.

Key entrypoints

• Plugin entry (Python): main.py — Plugin class. All methods here are callable from frontend via call().
• Plugin entry (TS): src/index.tsx — definePlugin(). Renders VaultwardenPlugin component.
• API bridge: src/api/backend.ts — VaultApi class wraps all call() invocations to Python.
• State management: src/hooks/useVault.ts — manages vault state machine (logged_out → loading → unlocked, etc).

Build output

out/Vaultwarden.zip is the installable Decky plugin. Created by npm run build. Contains:

• dist/ (compiled frontend JS)
• All Python files
• py_modules/ (bundled deps)
• plugin.json, defaults/settings.json

Gotchas

• No node_modules rebuild needed for Python changes. The Python files are copied as-is into the zip.
• py_modules/ is checked into git with pre-compiled wheels. If you modify Python deps in requirements.txt, re-run npm run bundle-deps and commit the updated py_modules/.
• Clipboard has two paths: Python clipboard.py (xclip/xsel with auto-clear) and frontend navigator.clipboard. They serve different purposes — don't confuse them.
• Target platform: x86_64 Linux (Steam Deck). Python wheels are platform-specific.
• src/utils/ exists but is empty.