languette 0.0.2

Languette: sharp hooks need strong guards.

A deterministic check against risky actions by coding agents.

Before a coding agent runs a shell command, a languette guard reads it and answers: allow, ask, or deny.

Nothing external decides: no web services, nothing cloud-based, and no ML or AI models. The critical execution path is deterministic, and uses "pure functions" where possible.

Who is this for?

You! ...assuming you are a real human being. A big AI vendor's safeguards are its product decision, changed on a whim. We don't have to trust them blindly. Languette is a guard you can read, test, and understand for yourself: trust, but verify. Any vendor that wants to adopt it is welcome to, under the terms of the AGPL.

What's with the name?

Languette is French for "little tongue". On a halberd the languette (or 'langet') is the strip of iron that runs down the shaft from the head, so a stray blow can't cut through the pole. These guards are that strip: protecting your work, strengthening your tools, and holding back specific agentic hazards that could ruin your day.

It's also a play on words: Shell is a little language, and languette listens for the few words in a shell command that can do damage. When it hears one, it tells the errant agent "hold your tongue!"

"The wise speak only of what they know, Gríma son of Gálmód. A witless worm have you become. Therefore be silent, and keep your forked tongue behind your teeth. I have not passed through fire and death to bandy crooked words with a serving-man till the lightning falls." — Gandalf, in J.R.R. Tolkien's The Two Towers, Book 3, Chapter 6

Install

The guards run as PreToolUse hooks in Claude Code today, on shell commands, gh and GitHub MCP calls, and messages to other sessions; other agent hosts are planned (#5).

Claude Code

/plugin marketplace add mark-brannan/languette#release
/plugin install languette@languette

It needs python3, standard library only. shfmt (the parser it trusts most) and gh (for the two guards that ask GitHub) are optional.

macOS (planned: #102)

brew install mark-brannan/tap/languette
languette install && languette doctor

Linux and WSL (planned: #102)

sudo apt install python3 pipx shfmt gh
pipx install languette
languette install && languette doctor

Windows without WSL

Languette protects Claude Code inside WSL: run wsl --install, then the Claude Code block above. An agent running natively in PowerShell is not protected.

Devcontainer, Codespace and CI (planned: #102)

One line in devcontainer.json installs languette before the agent starts:

"postCreateCommand": "pipx install languette"

Without the plugin system or the installer, see Installing by hand.

The guards

Each guard checks for one kind of hazard:

• ask-first: a command the repo lists as costly, until you approve that one run
• require-well-formed: a Bash command that doesn't parse; the other guards skip it
• guard-disks: dd, mkfs, wipefs, shred onto disks
• guard-github-issues: a second GitHub issue create, transfer or delete in one human turn, or any inside a loop
• guard-host-availability: shutdown, reboot, fork bomb, systemctl stop sshd
• guard-infra: terraform destroy, kubectl delete and other infrastructure destroys, until you approve that one run
• guard-permissions: recursive chmod, chown, chgrp or chmod 777 outside agent-owned or LANGUETTE_PERM_ALLOW directories
• guard-pipe-to-shell: curl u | sh, sh <(curl ..), eval "$(wget ..)"
• guard-private-terms: a term from your private list, posted to a public repo (off until given the list)
• guard-recursive-delete: a recursive rm or find -delete outside a generated or agent-owned directory
• guard-scheduled-jobs: crontab -r
• guard-secrets: a pasted credential
• guard-worktrees: opt-in; a branch switch in a $HOME that is a worktree, or a reach into another session's worktree
• guard-bypass-hooks: --no-verify on commit, push, merge, pull, rebase or am, and git -c core.hooksPath=, until you approve that one run
• guard-bypass-labels: a session applying a label that waives a CI gate, such as churn-ok
• guard-bypass-ruleset: a push direct to main where pull requests are normally required (agents could potentially bypass using your credentials)
• guard-cross-session-send: prevents sending messages to another session with the option to ask first or deny outright
• guard-git-stacked-base: deleting a remote branch an open PR is based on (GitHub silently closes the PR)
• guard-git-work-loss: add -A, commit -a, stash pop, force-push, reset --hard and other moves that throw work away
• guard-protected-services: systemctl stop postgresql, for the services you list
• prose-budget-commit: a git commit whose staged prose runs over the repo's word budgets
• guard-databases (planned)
• guard-protected-paths (planned)

The promise

When a guard can't tell what a command it covers will do, it denies and says why. When no rule covers a command, it says nothing.

A variable where a path should be, a brace expansion, a quote it can't resolve: each is a deny that names what the guard saw. The second half is a limit, not a bug. A guard reads shell text; it does not open scripts or read other languages. These are real verdicts, generated from the guards' scenarios for a command run in ~/project, and CI fails if the table drifts:

With shfmt 3.6 or later on PATH, the require-well-formed guard denies a command that doesn't parse. Without shfmt, it falls back to bash -n, then to its own lexer. In a replay of 101,671 agent commands, about 1 in 3,000 didn't parse, and each would have broken. Bash runs a broken command in part, the lines before the error or prose in backticks as a command; the deny stops all of it, so the agent looks again. A command over 64 KB, or nested too deeply to parse quickly, is denied unread.

Ask first

A repo lists its expensive commands in .languette/ask-first.json:

{"commands": [{"id": "e2e",
  "match": [{"cmd": "npm", "args": ["run", "e2e"]},
            {"cmd": "node", "script": "scripts/e2e.mjs"}],
  "cost": "> 40 minutes, using all CPU cores on a typical desktop",
  "approve_label": "Run e2e"}]}

When the agent tries a matching command, the guard denies it and tells the agent to ask you first: the exact command, why now, the cost, any cheaper form the entry lists under "cheaper", and a button labelled with approve_label. Click it and the next matching command runs. One click is one run: a command that runs it twice needs two, and one in a loop or xargs is denied whatever you approved. Only your click counts, never what the agent wrote in the question.

Matching sees through wrappers: timeout 3h npm run e2e, sh -c "...", pnpm exec node ./scripts/e2e.mjs and yarn e2e all count, while grep, git commit -m, cat and pkill -f that merely name the script do not. A run hidden inside a script (./ci.sh) or behind a variable ($CMD) is not seen.

The guard reads the nearest .languette/ask-first.json at or above the command's working directory, stopping at the repo root, else the one in $CLAUDE_PROJECT_DIR. With no file, it stays silent. A file that doesn't parse, or that gives two commands the same approve_label, denies every command until it is fixed, because the guard can no longer tell what the repo meant. Spent approvals are kept beside the session transcript, in <transcript>.languette-ask.

Configuration

Every guard is on by default except guard-worktrees, which is opt-in. Turn one off (or that one on) with /plugin configure languette@languette, or at install, by its name with underscores:

claude plugin install languette@languette --config guard_recursive_delete=false

A guard is skipped only when its setting is exactly false. Unset, empty or anything else runs it, so a misconfiguration cannot open the gate. guard_worktrees is the reverse: it runs only when its setting is exactly true, so a misconfiguration leaves it off. Its two controls, guard_worktrees_checkout_home and guard_worktrees_foreign, are each on unless set to false.

One setting per guard-git-work-loss rule

guard_git_work_loss=false skips all five rules. To keep four, turn off one:

Allowing more for guard-recursive-delete

Built in: the generated directories node_modules, dist, coverage and .pio, and the agent's own places, /tmp, ~/.local/state/claude-tmpdir and ~/.claude/worktrees. To allow more, set LANGUETTE_RM_ALLOW to a colon-separated list. It adds to the built-in lists and never replaces them; unset or empty changes nothing.

export LANGUETTE_RM_ALLOW=build:.next:/srv/agent-area

• A bare name (build) is treated like dist: a directory with that name, anywhere below the top level of $HOME or /.
• An absolute path (/srv/agent-area) is treated like the scratchpad: a place the agent owns.
• Entries use letters, digits and . _ @ + - only. A path may not contain a . or .. segment, and may not be / or $HOME.
• If the value doesn't parse (an empty entry, a glob, a space, a relative path with a slash), every Bash call carries a warning, and only a recursive rm or find -delete is denied. A typo can't stop unrelated work, and it can't open the gate either.

Settings for guard-private-terms

Without a terms file the guard is off.

bypass_labels lists the labels guard-bypass-labels keeps for humans, comma-separated; empty means churn-ok,mixed-loops-ok.

record_decisions, off by default, keeps every verdict, with its command and secrets masked, in $XDG_STATE_HOME/languette/decisions.jsonl, readable only by you.

Strong guards

A guard is a pure function of the command and the facts it asked for; it asks no model and runs nothing, and the runner fetches the facts (the design). The verdict is deny with the reason, ask, a warning, or nothing (allow). What a guard asks for beyond the command, it declares:

A guard that cannot decide denies and says what it saw. A guard that crashes is a deny naming the guard; the runner holds that rule, so no guard has to.

The contract is written as "gherkin" scenarios, in the words a person uses to state the rule. They're still completely deterministic tests, just easy for non-technical folks to read.

Scenario: a target the guard cannot resolve is denied on sight
  Given the working directory is "$HOME/project"
  When the agent runs `rm -rf "$DIR"`
  Then the guard denies, naming "variable or command substitution"

Installing by hand

Clone the repo and add one entry per guard in hooks/hooks.json to settings.json, shaped like the one below. Replace ${CLAUDE_PLUGIN_ROOT} with the path to your clone, since it is unset outside the plugin, and keep the wrapper. The wrapper is what makes a missing or crashing guard a deny: without it, a missing script is a non-blocking error to Claude Code, and every command goes through. One entry:

{"hooks": {"PreToolUse": [{"matcher": "Bash", "hooks": [{"type": "command",
  "command": "h=\"$HOME/languette/languette/run.py\"; { [ -f \"$h\" ] && python3 -I \"$h\" --guard guard-recursive-delete; } || printf '%s\\n' '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"languette/run.py (guard-recursive-delete) is missing or crashed, or python3 is not on PATH. This is a gate and fails closed.\"}}'"}]}]}}

Working on it

git clone https://github.com/mark-brannan/languette && cd languette
sudo apt install shfmt shellcheck
python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements-dev.txt
python3 -m pytest                       # every scenario
python3 tests/readme_table.py           # regenerate the table
shellcheck --severity=warning tests/stubs/* tests/*.test.sh   # as CI runs it

Running the tests needs pytest, pytest-bdd and PyHamcrest; the hooks do not.

The same run checks the shape of hooks/hooks.json, because claude plugin validate --strict passes a malformed one. The headless smoke test, which installs the plugin in a scratch project and confirms a recursive rm is really blocked, stays manual: it needs a model call and a login.

features/ holds the contract as scenarios: a command in, tokens or a verdict out. The guards began as shell scripts copied from mark-brannan/dotfiles; they run in Python now, and this repo is where they are maintained.

License

Markdown files are CC BY-SA 4.0; everything else is AGPL-3.0-or-later, except where a file carries its own notice. Copyright 2026 Mark Brannan. Credit "Mark Brannan" and link this repository.