clowk

Catches credentials you paste into Claude Code and swaps them for a name before the model sees them.

Paste a database URL, an API key or a token into Claude Code and press Enter. clowk swaps the value for a $NAME before the message is sent, files the value in a local vault, and lets the message go on. The model only ever gets the name, and your agent uses the credential by reference: psql "$(clowk get DATABASE_URL)". You don't repaste anything and nothing is blocked.

❯ check this connects and tell me how many orders we have: $DATABASE_URL
  🔒 clowk  $DATABASE_URL stayed on this machine · the model gets the name, never the value
⏺ Bash(psql "$(clowk get DATABASE_URL)" -Atc "select count(*) from orders;")
  ⎿  1284
⏺ The production database connected, and it has 1,284 orders.

▶ Watch the 3-minute demo

Claude Code 2.1.287+, through a Claude Code plugin. Python 3.8+, standard library only. No daemon, nothing to sign up for, and nothing in the guard touches the network.

Codex and Gemini CLI are supported in classic mode: their hooks can only block a prompt, not rewrite it, so the turn is blocked and your message comes back on your clipboard with the $NAME in it.

Why it exists: 113 of my Claude Code transcripts had an API key in them — what I found when I went looking through my own, and what clowk was built to stop.

Contents

Quick start

uv tool install clowk        # or: pipx install clowk
clowk setup

That's it. clowk setup:

1. finds the agent CLIs on your machine and registers clowk's hooks in each,
2. installs the skill that tells the agent what a $NAME is,
3. on Claude Code 2.1.287+, installs the clowk plugin through claude plugin,
4. fires a test credential through the hook it just registered, to prove the guard really blocks.

Restart Claude Code afterwards so it loads the plugin.

pip install clowk will not work on most machines, and that is not clowk's doing: Homebrew, Debian, Ubuntu and Fedora Pythons refuse to install into themselves (PEP 668). No uv or pipx? A clone needs no installer at all: git clone https://github.com/Aniumbott/clowk.git && cd clowk && python3 clowk/cli.py setup.

For dotfiles, a Dockerfile or CI, it runs unattended:

clowk setup --hosts claude-code --yes
clowk setup --dry-run                     # print the plan, write nothing

To add the plugin by hand instead, in Claude Code:

/plugin marketplace add Aniumbott/clowk
/plugin install clowk@clowk

In Claude Code

The clowk plugin is a Claude Code mod: code that runs inside Claude Code and can change a prompt on its way out, which a settings hook cannot do. On each prompt it runs clowk rewrite (about 85 ms), so the clowk package has to be installed and on your PATH.

Read output is left alone on purpose. An agent edits what it reads, and a file written back with $NAME in place of the value would lose the value. cat file followed by a whole-file write has the same risk; it is rare.

It fails closed. If clowk can't run (missing, an error, a timeout), the message is not sent, and the reason on screen says why. Starting a message with unclowk sends it unchecked.

• A clowk older than the plugin: the plugin steps aside, the package's own hooks block as before, and a status line under the prompt says to run clowk update.
• The plugin not running at all (--bare, --safe-mode, a policy that refuses user mods): the hooks clowk setup registered are the backstop. They run beneath the plugin, see only the rewritten text, and pass it. With the plugin off, they block, as in classic mode.

Classic mode: Codex, Gemini CLI, and older Claude Code

Agent CLIs whose hooks can only allow or block a prompt get the original flow. So do Claude Code before 2.1.287 and Claude Code without the plugin. The turn is blocked before anything is sent, the value is filed, and your message comes back on your clipboard with the $NAME in it, ready to repaste:

👀 clowk caught a credential before it reached the model.

   💾  $STRIPE_SECRET_KEY

📋 Paste this — already on your clipboard:

   rotate this key for me: $STRIPE_SECRET_KEY

🤔 Not a credential? Resend starting with  unclowk

The message shows only the lines the credential was on, cut to 40 characters either side, with the name highlighted where the terminal can show it. $(clowk get NAME), the tool-deny hook and the vault work the same as in Claude Code.

What it is good for

Catching a paste is how most people meet clowk, but it is the smaller half. The same three primitives — a local store, a $NAME reference that is worthless on its own, and a guard that only permits command substitution — make clowk a credential supply route for agents rather than only a net under your mistakes.

Nothing here needs a credential to have been leaked first. clowk add NAME takes a value at the terminal, so it never enters a chat at all.

What it is not good for. Screen sharing and recordings: what you paste is on screen until you press Enter — and for a moment after, while Claude Code draws the message before the plugin's rewrite lands. In classic mode Claude Code prints the raw prompt back under clowk's message. The model never gets the value either way, but the screen does. It is also not a CI or deployment secret manager — there is no daemon, nothing on the network in the capture path, and the vault is a local file belonging to one user.

Uninstalling

clowk uninstall                       # per host you registered

Your credentials are a separate decision, and uninstall makes you take it. The vault is the only copy of every value in it, so removing clowk does not remove ~/.clowk/vault.json unless you say so. Either way it tells you the file is still there, how many credentials it holds, and that nothing else on your machine reads it — a plaintext file of live keys should not be left behind by accident, and it should not be destroyed by accident either.

Interactively you get three options: back it up first, delete it, or keep it. Deleting asks you to type DELETE rather than pressing a key, because it cannot be undone. Unattended, it keeps the vault and prints the flags:

clowk uninstall --backup ~/clowk-backup.json   # the vault itself, values and all, mode 0600
clowk uninstall --purge                        # delete the vault, no prompt
clowk uninstall --keep-vault                   # keep it without being asked

The backup is the vault's own JSON rather than a report, so restoring is a file copy — cp ~/clowk-backup.json ~/.clowk/vault.json — not a re-typing of every credential. It carries a _restore key saying so, since JSON cannot hold a comment.

It is plaintext by definition, and clowk's own deny hook does not protect it — that hook knows the vault's real path and nothing else. Move it somewhere safe or delete it once you are done.

Run clowk uninstall before pip uninstall clowk or pipx uninstall clowk. Removing the package first leaves the hooks registered, pointing at a script that no longer exists — and since every host fails open, that is a guard that silently passes every credential from then on.

On Windows use python or py; there is no python3 on a stock install. On Codex, hooks need trust: run /hooks and approve clowk. Trust is hash-based, so every update asks again.

Updating

clowk update           # --check to look without changing anything

Why this is a command and not just git pull. The hooks and launcher hold absolute paths, so they pick up new code immediately — but the skill is copied into each host's skills directory and /clowk is generated into ~/.claude/commands/, so neither moves until install runs again. New code, old skill, and nothing on screen saying so. clowk update does both halves for every host you have registered.

For a clone it runs git pull --ff-only itself, refusing if you have modified tracked files. Untracked files are ignored, since they cannot make the pull fail. For a package install it prints the right command for the manager it can see — pipx upgrade, uv tool upgrade or pip install --upgrade — rather than guessing, because guessing wrong can leave a half-replaced package and on Windows pip install -U against a running package can fail on locked files.

The plugin updates through Claude Code, not through clowk update. Claude Code caches it under ~/.claude/plugins/cache/clowk/clowk/<version>/, keyed by plugin.json's version. A release bumps that version; then /plugin marketplace update clowk and /reload-plugins pick it up. Until then the cached copy keeps running, and if it is older than the package it still works: the package is what it calls.

How it works

In Claude Code, the plugin rewrites the prompt on its way out:

flowchart TD
    A["you paste<br/><b>postgresql://…:Tq7v…@db</b>"]:::secret
    B{"clowk plugin<br/>runs clowk rewrite<br/>as you press Enter"}:::tool
    V[("🗄️ ~/.clowk/vault.json<br/>0600 · your only copy")]:::secret
    R["your message, rewritten<br/><b>$DATABASE_URL</b>"]:::ref
    M["🤖 the model"]:::ref
    C["clowk get DATABASE_URL<br/>inside the command<br/>the value goes to the program"]:::ref

    A --> B
    B -->|"files the value"| V
    B --> R --> M
    M -->|"uses it by reference"| C
    V -.-> C

    classDef secret fill:#fdf1ea,stroke:#c2410c,stroke-width:1.5px,color:#17181c
    classDef ref fill:#eef7f5,stroke:#0f766e,stroke-width:1.5px,color:#17181c
    classDef tool fill:#f2f1ff,stroke:#4338ca,stroke-width:1.5px,color:#17181c

In classic mode, a hook can only allow or block, so it blocks and hands the rewrite back on your clipboard:

flowchart TD
    A["you paste<br/><b>sk_live_51H8xR…</b>"]:::secret
    B{"clowk scans it<br/>before it is sent"}:::tool
    X["🔒 turn blocked<br/>the model gets nothing"]:::blocked
    V[("🗄️ ~/.clowk/vault.json<br/>0600 · your only copy")]:::secret
    P["📋 your message, rewritten<br/><b>$STRIPE_SECRET_KEY</b><br/>on your clipboard"]:::ref
    M["🤖 the model"]:::ref

    A --> B
    B -->|"nothing found"| M
    B -->|"credential found"| X
    X -->|"files the value"| V
    X --> P -->|"you repaste"| M

    classDef secret fill:#fdf1ea,stroke:#c2410c,stroke-width:1.5px,color:#17181c
    classDef ref fill:#eef7f5,stroke:#0f766e,stroke-width:1.5px,color:#17181c
    classDef tool fill:#f2f1ff,stroke:#4338ca,stroke-width:1.5px,color:#17181c
    classDef blocked fill:#fdf0ef,stroke:#b42318,stroke-width:1.5px,color:#17181c

Why two shapes? No settings hook can rewrite a prompt you have already submitted — verified on Claude Code, Codex and Gemini CLI. A hook may block or allow, and that is the entire API. Claude Code 2.1.287 added mods, which can rewrite, so on Claude Code the plugin does. Everywhere else block-and-repaste is the only shape there is, and the clipboard is what keeps it tolerable.

Detection

221 gitleaks rules plus three of clowk's own: one for credential-shaped tokens standing alone, and one for each connection-string dialect.

• Connection strings are captured whole. postgresql://user:pw@host/db files as $DATABASE_URL, so your hostname and database name do not travel either. The key=value; dialect used by Microsoft SDKs and ODBC drivers gets the same treatment — an Azure storage string files as $AZURE_STORAGE_CONNECTION_STRING rather than having its AccountKey swapped while AccountName=prodstore rides along.
• Placeholders are left alone. changeme, <your-account-key>, and values that are already references such as $DB_PASS.
• At most 20 names per message. More hits than that is a pasted log, not a paste of credentials. The rest are still redacted and the turn is still blocked; they are just not filed.

Naming

The $NAME comes from whatever identified the credential:

Using a credential

A captured value is not in your agent's environment — echo $DATABASE_URL prints nothing, by design. Substitute it at the point of use:

psql "$(clowk get DATABASE_URL)"
curl -H "Authorization: Bearer $(clowk get STRIPE_SECRET_KEY)" https://api.stripe.com/v1/charges

flowchart TD
    A["🤖 the agent runs a command<br/>that substitutes <b>clowk get NAME</b>"]:::ref
    S["your shell expands it"]:::tool
    V[("🗄️ vault")]:::secret
    D["🐘 the database gets<br/>the real value"]:::secret
    M["🤖 the model sees only<br/>the command it wrote"]:::ref

    A --> S
    V -->|"the value, never printed"| S
    S --> D
    A -.-> M

    classDef secret fill:#fdf1ea,stroke:#c2410c,stroke-width:1.5px,color:#17181c
    classDef ref fill:#eef7f5,stroke:#0f766e,stroke-width:1.5px,color:#17181c
    classDef tool fill:#f2f1ff,stroke:#4338ca,stroke-width:1.5px,color:#17181c

The shell hands the value to the command as an argument. Nothing wraps your command, so your host's own permission rules still match what you actually ran.

clowk get is the only thing that prints a credential, so it is guarded. A second hook refuses a bare clowk get, a substitution piped into echo/cat/printf, a redirect, and capture into a shell variable — each of those would put the value back in your transcript. The check lives in the hook rather than in clowk get because a process cannot tell whether it was command-substituted.

Your agent learns this from a skill setup installs, pointed at from a session's first block so the rule arrives with the $NAME it governs. What each host gets:

Every clowk get is recorded, so clowk uses tells you where a credential was caught and what has drawn on it since. Re-catches are counted too: clowk list will tell you a key has been caught five times and when the last one was. That number is worth watching — pasting the same credential repeatedly is a habit, and clowk add is how you stop.

Commands

add and set never take the value as an argument — that would put it straight in your shell history.

After a rotation, use set. Paste a replacement for a credential clowk already holds and nothing is overwritten: the new value files as $NAME_2 while $NAME still resolves to the revoked one. The block message says so and prints the clowk set NAME that moves the name across, keeping when and where it was first caught. clowk will not move it for you — an existing $NAME quietly changing meaning is the same accident in the other direction.

The tool-deny hook

Your agent can leak a credential without you touching the keyboard: it cats a .env, or runs git credential fill, and the value is in the transcript. A second hook denies the easy ones.

flowchart LR
    A["🤖 agent runs<br/>Bash or Read"]:::ref
    B{"clowk tool hook"}:::tool
    D["🚫 denied,<br/>with how to allow it"]:::blocked
    K["✅ runs untouched"]:::ref

    A --> B
    B -->|".env · a private key<br/>the vault<br/>git credential fill"| D
    B -->|"anything else"| K

    classDef ref fill:#eef7f5,stroke:#0f766e,stroke-width:1.5px,color:#17181c
    classDef tool fill:#f2f1ff,stroke:#4338ca,stroke-width:1.5px,color:#17181c
    classDef blocked fill:#fdf0ef,stroke:#b42318,stroke-width:1.5px,color:#17181c

It denies running those, not mentioning them — a path in a commit message, an echo, or a grep pattern all pass. A path counts as a read only when something that reads files is running it.

Architecture

Everything at once, including the parts with no flow to draw. Click through for full size.

Limitations

clowk is not a security boundary. It runs as the same OS user as your agent, so whatever clowk can read, cat can read. It stops accidents; it will not stop an agent that is genuinely trying. A real boundary needs a separate OS user, a container with clowk outside it, or a code-signed binary holding an OS keychain ACL.

DESIGN.md records why each of these is a deliberate trade; NOTES.md records the per-host findings and marks what is verified against what is assumed.

Configuration

The vault is plaintext, deliberately. Encryption cannot help: clowk runs as the same user as the agent, so any key would have to be reachable by that user, and therefore by the agent. Same posture as ~/.aws/credentials, ~/.npmrc and an unencrypted id_rsa. The upside of plain JSON is that reading the file is your export path — nothing here can lock you out of your own credentials.

Hand-edit it into invalid JSON and clowk refuses rather than guessing: every command prints the path and stops. A capture during that window still blocks and still redacts; it just tells you the value was not saved.

False positives

107 of the 221 rules match on shape rather than a literal vendor prefix, and clowk's standalone-token rule matches on shape alone, so an innocent prompt can be blocked. A rule counts as pinned only when the literal begins the value the rule captures — so curl -u and a Sidekiq hostname do not count, because there the vendor's name sits outside the credential.

Hex of 32 characters or more may also be caught on how many of the 16 digits appear — eight — rather than on entropy alone, because an absolute entropy floor is calibrated for base64's 6.0-bit ceiling while hex tops out at 4.0, which discarded 19% of genuine 128-bit keys.

When it happens, resend starting with unclowk. Shape-only matches are flagged in clowk list, so they are easy to spot and clowk clear NAME away.

Contributing

Contributions are welcome — issues, bug reports and pull requests all help. The project has no dependencies, so there is no setup step beyond cloning.

Three conventions matter more than style here:

1. Standard library only. Every host fails open, so a hook that cannot import is a hook that transmits your secret. CI fails if a third-party import appears.
2. Measure, do not assert. Detection changes are expected to come with before-and-after recall and false-positive numbers against the labelled corpora in tests/test_chat_shapes.py. A test written first, and shown failing, is the norm.
3. Never mark a host verified without running something. NOTES.md separates what has been verified from what is assumed, and that distinction is load-bearing — it is the difference between a guard that works and one that only looks installed.

Useful to know before opening a PR:

• tests/test_docs.py checks this README against the code, so a claim here that stops being true fails the suite. Counts are derived rather than written down.
• Commit messages are type: summary and explain why, including approaches tried and rejected.
• Adding a host takes a hosts.py entry, an install.py target, and verified answers to three questions: what the pre-transmit event is called, whether it can block, and whether it can rewrite the prompt. clowk debug-payload dumps what a host actually sends. Please do not add one on inference.

Development

python3 -m unittest discover -s tests        # 609 tests, ~4s
claude plugin validate . && claude plugin test .   # the Claude Code mod, hooks/register.js

CI runs the same suite on Python 3.8 through 3.13 across Linux, macOS and Windows, plus three checks the suite cannot make itself: that no third-party import has crept in, that the prompt hook run end to end leaks the raw value into neither stream on any host, and that install merges into a settings file it did not write while uninstall restores it byte for byte.

Layout. detect.py scans · vault.py stores · hosts.py adapts each host's payload and block protocol · hook_prompt.py is the pre-transmit guard (and clowk rewrite, the detector behind the Claude Code mod in hooks/register.js) · hook_pretool.py the tool deny, with its rules in deny.py · install.py registers hooks · cli.py is the human surface. DESIGN.md explains why the design is this shape and what was discarded; NOTES.md records per-host platform findings.

Updating the ruleset. clowk/rules.json is generated by build_rules.py from the vendored clowk/gitleaks.toml. Re-running it alone reproduces a byte-identical file; to pick up new patterns, replace the vendored copy with a newer one from gitleaks first. build_rules.py normalises Go's regex dialect to Python's and prints what it translated and what it could not use; a rule it cannot compile is skipped, and a test fails if that ever loses one. Check NOTES.md first — it records, with dates, what upstream's newest config actually is, which is currently the copy already vendored here.

Security

Report anything exploitable privately through GitHub's advisory form, never in a public issue, and never with a real credential in it. SECURITY.md lists what counts — and, just as usefully, which documented limits do not: cat reading the vault, hooks failing open, and the host recording the prompt it blocked are all design trades explained above rather than findings.

License

MIT — see LICENSE. Secret patterns derive from gitleaks (MIT).