Install

Install

pip install key-amnesia

Or from source: pip install git+https://github.com/fujitoid/key-amnesia, or from a local clone: pip install .. You get both key-amnesia and the ka alias.

Windows and Linux are supported. macOS isolated-console spawn is experimental (PID-file wrapper around Terminal.app / osascript; visible window path unconfirmed by a real Mac user) — see macOS.

Kernel peer-identity admission on macOS is not supported: lookup fails closed, so a macOS guard cannot admit clients the way Windows/Linux do. Experimental console spawn does not change that.

Agent setup

ka setup

Copies bundled skills (key-amnesia-usage, key-amnesia-hygiene, key-amnesia-migrate) into ~/.claude/skills/, ~/.cursor/skills/, ~/.agents/skills/ (current Codex user path), and ~/.codex/skills/ (legacy / $CODEX_HOME), merges a PreToolUse / preToolUse hook that denies forbidden ka verbs (and inline credential-shaped tokens), and best-effort allow rules so the harness will let unattended ka run / ka list through. Files try to let the agent run ka; the hook is the load-bearing deny (ka set, ka reveal, ka scan --yes, and other mutating verbs). Restart or reload the host afterward. On Codex, review and trust the new hook via /hooks before it will run.

Codex also reads project AGENTS.md for instructions; that is separate from skills installed by ka setup. Cursor: ka setup never creates ~/.cursor/permissions.json (that file replaces the in-app terminal allowlist).

Flags: --skills-only, --hook-only, --permissions-only, --permissions-remove, --yes (do not prompt before writing permission files; never deletes user allows).

Agent bootstrap prompt

Paste into a coding agent:

Install key-amnesia and set yourself up to use it correctly for secrets in
this project:
1. pip install key-amnesia
2. Verify `ka --version` works in a fresh terminal (if not found, fix PATH
   as instructed).
3. Run `ka setup` (installs its skills + safety hook globally).
4. Tell me to restart this session so the skill loads, then tell me exactly
   what to do in my OWN terminal to finish setup (master password etc.) —
   you cannot do that step yourself.

Open these docs

ka docs          # print URL + best-effort browser open
ka docs --print  # URL only

Environment notes

Variable	Effect
KEY_AMNESIA_HOME	Override data dir (default ~/.key-amnesia)
KEY_AMNESIA_VAULT_PATH	Override vault file path
KEY_AMNESIA_NONINTERACTIVE=1	Force spawned-console auth (never inline getpass), even if both streams claim to be a TTY — use in agent harnesses
KEY_AMNESIA_CLIENT_NAME	Display-only label on guard IPC (not a credential)
KEY_AMNESIA_HOOK_DISABLE=1	Disable the secret-guard hook

Auth routing requires both stdin and stdout to look like a TTY before prompting inline; otherwise ka opens an isolated console the human can see.