clowk

<img src="https://raw.githubusercontent.com/Aniumbott/clowk/main/assets/logo.svg" alt="" width="96" height="96">

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

A package install already provides clowk on your PATH through an entry point, so nothing extra is written. From a clone there is no entry point, so install writes ~/.local/bin/clowk — and if that directory is not on your PATH it says so and prints the line to add. Either way clowk has to be a real command, because the callers that matter are the plugin and the non-interactive shell your agent runs.

Do not substitute a shell alias. Aliases exist only in interactive shells, and the caller that matters is the non-interactive Bash your agent runs. There $(clowk get NAME) expands to nothing, your command runs without the credential, and the error looks like a bad key rather than a missing tool.

install merges into your existing settings, backs them up first, and refuses a settings file that is not valid UTF-8 JSON. uninstall removes only what clowk wrote, byte for byte. Hooks and launcher hold absolute paths to this clone and to the interpreter you ran install with, so nothing depends on PATH — but move the clone and you re-run install.

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.

clowk install writes ~/.claude/commands/clowk.md, so /clowk works with no further steps, and gives the agent the skill that tells it what a $NAME is. Without that skill an agent reads $DATABASE_URL as an ordinary empty variable and asks you to paste the real one again. With the plugin installed the skill comes from the plugin, along with /clowk:clowk; otherwise it is copied to ~/.claude/skills/clowk/. Never both, so it isn't listed twice; clowk update removes a copy an older install left behind.

How it works

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

flowchart TD
    A["you paste<br/><b>postgresql://…:REDACTED@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 a