travsr guard
A Claude Code PreToolUse hook handler that intercepts Grep, Glob, Read, and shell grep/rg/find/ag/ack/ls -R calls, and either points the agent at the Travsr call that answers the same question, or refuses the read and names it.
Not meant to be run by hand: travsr init --guard or travsr connect --guard registers it in .claude/settings.json, and Claude Code invokes it itself on every matching tool call.
Modes
| Mode | Behavior |
|---|---|
off (default) | Installed but inert. Also what TRAVSR_GUARD=off selects |
advisory | Never blocks. Attaches the Travsr call that would answer the same question as context alongside the original tool call. A bare --guard selects this |
strict | Denies a read the graph can answer, naming the replacement call. Allows everything else |
Off unless asked for.
Turning it on
travsr init --guard # advisory, on a fresh index
travsr init --guard=strict # strict, on a fresh index
travsr connect --guard # advisory, on an already-indexed repo
travsr connect --guard=strict # strict, on an already-indexed repo
travsr connect --remove # take the hook back out
The level is stored in .travsr/config.toml, so the installed hook and travsr guard itself always agree on it. TRAVSR_GUARD=off disables it for one command without touching the stored config.
--guard requires = before the level (--guard=strict, or a bare --guard for advisory), so travsr connect --guard --print still reads --print as its own flag rather than as the guard level.
Options
| Flag | Meaning |
|---|---|
--explain | Print, on stderr, the one-line reason behind the decision. stdout (the permission decision Claude Code reads) is unchanged, so it's safe to leave on inside the hook |
"the guard is installed and nothing is blocked" has several causes that look identical from outside: the mode is off, the index is stale, the symbol is unknown, the command wasn't recognised. --explain says which.
Fail-open by construction
The guard never blocks a call it can't confidently replace:
- A missing, stale or unreadable index, or an unreadable payload.
- A command it doesn't recognise.
- A missed deadline.
- Its own internal failure.
All of these let the original read through rather than blocking the agent.
When to use it
- You've connected an AI coding tool to Travsr and want it nudged toward the graph instead of falling back to grep out of habit.
strictmode, once you trust the index is fresh, to stop an agent from re-deriving structure the graph already has.
Claude Code only: no other supported host currently has a pre-tool-call contract to hook.