A protocol for secrets and AI agents · macOS
Your agent knows the name.
Never the value.
SecretBar is a command and a menu bar app for the Mac. Passwords, tokens and API keys stay in the Secure Enclave. The agent asks by name, a human confirms, the process gets the value, and the output comes back redacted.
$ brew install secretbar/tap/secretbaragent › I need the database password for the shop.
$ secret ls -l
SHOP_DB_PASSWORD shop: PostgreSQL password1
BILLING_API_TOKEN billing: prod API token
$ secret run --mask SHOP_DB_PASSWORD -- psql -c 'select 1'2
password=k9#Vq2!xR7mW → ***3
- The agent sees names and comments. Never values.
- Touch ID on your Mac. The value goes into the environment of psql, and nowhere else.
- The output comes back masked. Also in base64 and URL encoding.
The protocol
Six rules the value follows.
Every feature of SecretBar enforces one of them. None of them depends on the agent behaving well.
- §1
Input
A human types the value into a hidden macOS dialog:
secret ask NAME. The chat never sees it.secret genmakes a random value that nobody sees. - §2
Storage
Keys in the Secure Enclave seal each value: P-256 and post-quantum ML-KEM-768. The whole file is encrypted again. Nothing goes to a cloud.
- §3
Access
A read needs Touch ID or Apple Watch. The grace time slides for 30 minutes and ends when the screen locks. A lease gives an agent named secrets for up to 24 hours, after one Touch ID.
- §4
Use
secret runputs the value into the environment of one process. Not into argv, a file or the chat. A.envfile holds references:secret:NAME. - §5
Output
Each value in stdout and stderr comes back as
***, also in base64 and URL encoding. A Claude Code hook stopscat .env,secret getandenvbefore they run. - §6
Record
An access log keeps who read which name and when:
agentorhuman. Names only.
The menu bar app
The human side of the protocol.
⌥⌘S from any app, Spotlight, Siri and Shortcuts. A card for each secret with the .env files that use it. The app never reads a value: the helper puts it on the clipboard and clears it after 30 seconds.
- Quick search: ↩ copies the reference, ⇧↩ the value
- + in the menu bar: a new secret, its reference on the clipboard
- Activity: agent runs and Touch ID prompts
- English, Deutsch, Français, Español, Italiano, Português, Polski, Русский
Threat model
What it stops, and what it does not.
| Threat | Stops | Does not stop |
|---|---|---|
| A value in the chat | Dialog input, generation, masked output, the hook. | A value inside a custom encoding, for example base64(user:pass). |
A value in ps | Values go through stdin and file descriptors. | secret set NAME VALUE with the value as an argument. |
| A process reads behind your back | The Secure Enclave key works only after Touch ID or Apple Watch, for any process. | Reads inside the grace time: 30 idle minutes, 8 hours at most. |
| Loss of the Mac | secret export: AES-256, PBKDF2 with 600 000 iterations. | Nobody can recover a forgotten backup password. |
Questions
- Does the AI agent ever see the value of a secret?
- No. The agent works with names. The value goes into the environment of the command that needs it, and the output comes back with
***in place of the value. A Claude Code hook stops commands that would print a value. - Where are the secrets stored?
- In one encrypted file on your Mac. Keys in the Secure Enclave seal each value. A read needs Touch ID, Apple Watch or the Mac password. Nothing goes to a cloud.
- Which AI agents does it work with?
- Any agent that runs shell commands: Claude Code, Codex, Cursor, Aider and others. Claude Code also gets a hook and ready rules for its
CLAUDE.md. - What does it cost?
- Nothing. SecretBar is open source under the MIT license.
- Which macOS version do I need?
- macOS 14 or later on a Mac with a Secure Enclave (Apple silicon or T2). The post-quantum store needs macOS 26. Search by meaning needs macOS 27 with Apple Intelligence.
- Can I move my secrets to a new Mac?
- Yes.
secret exportwrites one file encrypted with AES-256 and your backup password.secret restorereads it on the new Mac.
Install
Three lines, then sign here.
- The command, both helpers and zsh completion
$ brew install secretbar/tap/secretbar - The store, then the first secret, typed in a dialog
$ secret init && secret ask MY_TOKEN - The Claude Code hook, the agent rules and the menu bar app
$ "$(brew --prefix secretbar)/libexec/install.sh" --claude-hook --app
macOS 14 or later. No dependencies beyond the system tools. Free and open source, MIT.