clowk

Catches credentials you paste into an agent chat before they reach the model.

A pre-transmit hook for agent CLIs. It scans your prompt before it is sent; if it finds a credential, the turn is blocked, the value is filed locally under a name, and your message is returned on your clipboard with a $NAME reference in place of the secret.

Install

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), and many of them have no bare pip on PATH at all. Use whichever of these you have:

uv tool install clowk        # uv installs clowk into its own isolated environment
pipx install clowk           # what Homebrew and apt themselves recommend; brew install pipx

Neither? A clone needs no installer of any kind:

git clone https://github.com/Aniumbott/clowk.git && cd clowk

Then, whichever route you took, one command — clowk setup (from a clone, python3 clowk/cli.py setup). It finds your agent CLIs, registers the hooks, installs the skill, and then fires a test credential through the hook it just registered to prove the block really happens.

👀 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

   [assistant: $NAME is a credential clowk holds. Never print it.
    Use $(clowk get NAME) — see the clowk skill.]

🤔 Not a credential? Resend starting with  unclowk

Claude Code, Codex and Gemini CLI. Python 3.8+, standard library only. No daemon, nothing to sign up for, and neither hook ever touches the network — the only command that does is clowk update, which runs your package manager or git pull when you ask it to.

Contents

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: Claude Code prints the raw prompt back to your terminal under clowk's message, so the value is on screen even though the model never got it. 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.

Quick start

Pick whichever suits the machine — there is no single command that works everywhere, because pip install --user is refused outright on Homebrew, Debian, Ubuntu and Fedora Pythons (PEP 668):

uv tool install clowk                                          # if you have uv
pipx install clowk                                             # what Homebrew and apt suggest
git clone https://github.com/Aniumbott/clowk.git && cd clowk    # no prerequisites at all

Then, whichever route you took, one command:

clowk setup          # from a clone: python3 clowk/cli.py setup

It finds the agent CLIs on your machine, asks which to set up, registers the hooks, installs the skill — and then fires a test credential through the hook it just registered to confirm the turn is really blocked and the value leaks into neither stream. A host it cannot prove is reported as unproven rather than given a tick.

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

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

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 caller that matters is 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.

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.

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

How it works

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 block instead of swapping the value in silently? No host can rewrite a prompt you have already submitted — verified on all three. A hook may block or allow, and that is the entire API. So block-and-repaste is the only available shape, 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<br/><b>psql &quot;$(clowk get NAME)&quot;</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        # 562 tests, ~4s

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 · 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).