aihsm 0.1.0

Blocks secrets typed into Claude Code and stores them in the OS credential vault.

AIHSM - (AI Harness Manager)

AI Harness Secret Manager: keep API keys out of Claude Code and in your OS credential vault.

aihsm stops secrets (API keys, tokens, passwords, connection strings) from being typed into Claude Code.

Pasting a key into a chat window feels harmless in the moment: you need Claude to see a value, so you paste it and move on. The problem is that the value is now sitting in a transcript, a log, maybe a shared session, forever. The habit itself is the risk. This tool makes that habit impossible instead of asking you to remember not to do it.

A UserPromptSubmit hook scans every message before it reaches the model. If the message contains something that looks like a secret, the hook blocks it: the message never reaches Claude at all. You get a message back telling you to rotate the exposed key and store the new one in your operating system's credential vault (Windows Credential Manager, macOS Keychain, or the Linux Secret Service).

aihsm is not the only tool in this space. For an honest look at how it stacks up against the alternatives, with the pros and cons of each, see how aihsm compares.

The core policy

• Secrets get into the system only through aihsm put, from a hidden prompt, never by being pasted into chat.

• Stored values are never printed by any command in this tool. There is no aihsm show or aihsm get. If you need to see a value, open your OS credential manager yourself. Each secret is filed there under the name <yourname>@aihsm, the same on Windows, macOS, and Linux. On macOS, open Keychain Access and look under the Passwords category (or type aihsm in the search box); the entry is easy to miss otherwise. On Windows it is under Credential Manager, Windows Credentials, Generic Credentials.

• When a command needs a secret at runtime, aihsm run injects it and masks the value out of that command's output, so the key does not surface in the chat even if the command tries to print it.

• Anything that has already been typed into a chat message is compromised, whether the hook caught it or not. Rotate it. A key that a human or a model has seen is a key you should treat as burned, and no tool can undo that after the fact.

Install

Python 3 is required. Pick the line for your OS:

# macOS / Linux
bash install.sh

# Windows
.\install.ps1

The installer checks that Python 3 is present, installs the package and the aihsm CLI, registers the UserPromptSubmit hook in your Claude Code settings (backing up the existing settings file first, never overwriting your other hooks), copies the accompanying skill so Claude knows the rules around it, and adds the aihsm command to your PATH. If Python is missing or the install fails, it stops and tells you what to fix rather than half-installing. The same steps run on Windows, macOS, and Linux.

On Linux, the OS vault is the Secret Service, so you need a keyring backend running (GNOME Keyring or KWallet). Most desktop Linux installs already have one. On a headless or minimal box without it, storing a secret will fail with a clear message telling you what to install.

When it finishes, the installer runs a self-check: it feeds a fake secret to the hook and confirms it gets blocked, printing Hook self-check passed. So a clean install has already proven the guard works. The hook takes effect in new Claude Code sessions, so restart Claude Code if it is open, then to see it yourself paste a fake key like ghp_ followed by a run of random letters and numbers into a message: it should be blocked before Claude sees it. From then on, store real secrets with aihsm put <name> and refer to them by name.

To re-check later that the hook is still registered, look in ~/.claude/settings.json for a UserPromptSubmit entry whose command ends in -m aihsm.detect. Every block also appends a line to ~/.claude/aihsm/logs/aihsm.log (the rule name, never the secret), so a fresh blocked prompt line there confirms the hook fired.

Install as a Claude Code plugin

The install script is one way in. The other is the Claude Code plugin, if you would rather enable it from inside Claude Code than run a script. From a Claude Code session:

/plugin marketplace add dtsoden/aihsm
/plugin install aihsm@aihsm

This registers the same UserPromptSubmit guard and copies the same skill, so pasted secrets get blocked the moment the plugin is enabled. The detector is pure Python standard library, so it runs straight from the plugin with nothing else to install. Python 3 still has to be on your PATH, and you restart Claude Code once so the hook takes effect in a new session.

There is one difference from the script install. The plugin gives you the guard and the skill, not the vault commands. aihsm put, aihsm run, and aihsm list come from the Python package, which the plugin does not install. Run the install script above to get them; the guard and the CLI are happy to sit side by side. If you only want the paste guard and you keep your secrets in your OS credential manager by hand, the plugin on its own is enough.

Usage

Store a secret. You give the name on the command line; the value is never passed as an argument (that would leave it in your shell history). You are prompted for the value twice, hidden both times, so a typo can't be saved by mistake. Nothing shows as you type or paste, which is normal; when it saves, it confirms how many characters it stored so you know your paste landed.

aihsm put github-token

Run a command with a secret injected into its environment, without ever printing it:

aihsm run --set GITHUB_TOKEN=github-token -- gh api /user

aihsm run puts the secret into the child command's environment and redacts it from everything that command prints. If the command echoes the value in a debug line, an error, or a full printenv dump, it comes back as ****, so the raw key does not land in the transcript Claude reads. This holds even when several stored secrets overlap each other or a value is split across the output stream. The one thing it cannot catch is a value the command transforms before printing it (base64-encoding it, for example); the accompanying skill still tells the model never to echo a secret, as a second layer.

If aihsm is not found right after install, open a new terminal window: the PATH change only takes effect in new shells. The installer prints the full path to the command at the end if you ever need to run it directly.

List what is stored, by name only. This checks your OS vault directly, so if you remove an entry in your OS credential manager, aihsm list stops showing it:

aihsm list

Remove an entry:

aihsm rm github-token

Using a stored secret in a Claude Code prompt

This is the part that changes your habit. You never paste the key into the chat. You refer to it by the name you gave it, and let Claude pull it from the vault for you.

Say you stored a token with aihsm put github-token. In a prompt, you just name it:

Use my github-token from the vault to list my GitHub repositories.

Claude runs the command through aihsm run, which reads the secret from the OS vault, puts it into that command's environment, and masks it out of the output:

aihsm run --set GITHUB_TOKEN=github-token -- gh api /user/repos

GITHUB_TOKEN is the environment variable the command expects; github-token is the name you stored it under. The value never appears in your message, in Claude's reply, or in the command's output. The accompanying skill teaches Claude these rules, so it reaches for aihsm run and refers to secrets by name on its own. If you forget and paste the raw key, the hook blocks the message before it reaches Claude.

How detection works

Every prompt is checked against a set of known secret shapes before it leaves your machine: Anthropic and OpenAI keys, GitHub tokens, AWS access keys, Slack tokens, Google API keys, Stripe live keys, JWTs, PEM private key blocks, and connection strings with an embedded password. Anything that does not match a known shape is still checked against a high-entropy catch-all, so an unfamiliar-looking token gets flagged too.

Sometimes the match is wrong: a long build hash, a random test fixture, something that just happens to look like a secret. If that happens, re-send the exact same message but start it with !secret-ok. That one message goes through, and the tool remembers the flagged string (as a salted hash, not the raw value) so it will not nag you about that same string again.

The log

The tool keeps a small log at ~/.claude/aihsm/logs/ so you can see what happened when something goes wrong: a blocked key (by type, never the value), a stored or used entry (by name), an error. It never records a secret value, the prompt text, or a matched string. The log cleans up after itself: it rolls over at about 1 MB and keeps four old files, so it stays around 5 MB at most and can never grow into the hundreds of megabytes. To turn it off, set the environment variable AIHSM_NO_LOG to any value.

Uninstall

# macOS / Linux
bash uninstall.sh

# Windows
.\uninstall.ps1

This removes the hook and the skill and uninstalls the package. It does not touch your OS credential vault: anything you stored with aihsm put stays there until you remove it yourself with aihsm rm or your OS credential manager.

What this does not do

aihsm protects future use. It cannot undo exposure that already happened. If a key was typed into a chat before this tool was installed, or before a detection rule existed to catch its shape, that key is still compromised and still needs to be rotated at the provider. The hook is a guard against the next mistake, not a cleanup crew for the last one.

How aihsm compares

Plenty of tools touch this problem, and each is good at what it was built for. Here is an honest snapshot of where aihsm sits next to the main alternatives, as of July 2026.

Capability	sensitive-canary	vaultry / claude-secrets	1Password op run	Doppler	aihsm
Blocks keys pasted into chat	Yes	No	No	No	Yes
Blocks the assistant reading keys from files	Yes	Partial	No	No	No
Stores keys in the OS-native vault	No	Yes	Yes	No	Yes
Masks keys in command output	n/a	Partial	Partial	No	Yes
Cross-platform (Windows / macOS / Linux)	Yes	No	Yes	Yes	Yes
Fully open source (MIT)	Yes	No	No	No	Yes
Local, no cloud account	Yes	Yes	Partial	No	Yes

The tools, so you can judge for yourself:

• sensitive-canary - Claude Code hooks with strong detection (31 rules from gitleaks and TruffleHog) and a second hook that blocks the assistant from reading .env files. Detection only; there is no vault behind it.
• vaultry / claude-secrets - an encrypted store with a macOS Keychain master key and per-project allowlists. macOS only, and source-available rather than fully open.
• 1Password op run - mature, cross-platform, strong team features. Needs a paid account, and its usual env injection can still leak the value into a chatty command's output.
• Doppler - a cloud secret manager with runtime injection. Cloud-hosted, account required, aimed at teams and CI.
• HashiCorp Vault - the enterprise standard for secrets at scale. Server software; heavy for one developer on a laptop.
• gitleaks and TruffleHog - the standard for finding secrets already committed to git. A different door: they scan code at rest, not the live chat channel.

aihsm is deliberately the small one: a single free cross-platform MIT tool that keeps keys out of the chat and in your own OS vault, with no account and one command to install. It does not try to be enterprise data-loss prevention, and it does not scan every file the assistant reads. If that file-read path matters to you, sensitive-canary is the better answer there, and the two can run side by side.