shim Guard

Local traffic visibility and privacy controls for coding agents.
getshim.tech

shim Guard shows you what your coding agent actually sends to the model — how
many tokens went where, what the turn cost, and which secrets and personal data
were in it — and masks what it can before the model sees it. The hook and
detector add no network destination, account, API key, or telemetry. The opt-in
shim watch proxy forwards only to the provider the client already uses.

Two commands, two different questions:

[!WARNING]
shim Guard is alpha software and a best-effort guard, not a data-loss
prevention boundary. Read the privacy limitations before
using it with sensitive data.

Measure a session

Nobody can tell you where their agent's context window actually goes. shim watch puts a local proxy in front of the client for one command, forwards
every byte unchanged, and reports what went past:

shim watch -- claude
shim watch -- claude -p "explain this repo"

shim watch — 8s, 1 requests
  input     109,678 tokens  (exact)
    cache read   91,562   83%
    cache write  18,114
  output    157 tokens  (exact)
  where the input went  (approximate — split by byte share)
    tools     ~      90,001   82%
    system    ~      10,361    9%
    messages  ~       9,185    8%
  @ files   1 inlined, 354 bytes (invisible to hooks)
  found     2 EMAIL in traffic
  spend     ~$0.10  (approximate, 2026-08-30 prices)

On the session above, the tools array was 82% of the input tokens — before
a single line of the user's own code. That is one session on one repository,
not a universal figure, which is the point: it is your number and you have no
other way to get it.

Token counts come from the provider's own usage block and are exact. How
they divide between sections has no ground truth on the wire, so it is
inferred from byte share, marked ~, and always sums to the exact total.
Exact and inferred figures never share a column.

It also covers what hooks structurally cannot see: files pulled in with @ are
inlined by the client while it builds the prompt, so no hook fires for them,
and the system prompt, the tools array and the token counts are never handed to
a hook at all.

It forwards and measures. It does not modify. Not one byte of a request is
changed, no request body is ever written to disk, and nothing is transmitted
anywhere except to the provider the client was already talking to. The proxy
binds to loopback, exists for the length of the command, and nothing is left
behind — no shell profile is edited and no setting is changed.

Overhead measured against a live session: about 6 ms of proxy plumbing plus a
23 ms TLS handshake per request. Scanning the body costs more than that, but it
runs after the request has been sent, inside the window where the provider is
already thinking, so it does not delay anything.

Claude Code is verified. Codex runs with a warning — a ChatGPT sign-in behind a
third-party proxy is documented but untested. Copilot is out of scope: it
accepts a custom endpoint only through bring-your-own-key, which removes GitHub
authentication altogether, so there is nothing to watch.

Supported clients

Tool coverage is verified against a running client, not derived from
documentation. shim doctor <client> prints exactly which events are installed
and what shim can and cannot change at each one.

shim Guard detects email addresses, phone numbers, credit cards, IBANs, IP and
MAC addresses, US SSNs, Turkish national and tax IDs, secrets, and database
URIs. Checksums are verified where they exist, so a mistyped IBAN or national
ID is not reported.

It deliberately stays quiet on values that name nobody: loopback and
unspecified addresses (127.0.0.1, 0.0.0.0, ::1) and connection strings to
them that carry no credentials (redis://localhost:6379/0). Private ranges,
real hosts, and anything with a user:password@ are still detected. Once
0.0.0.0 and 127.0.0.1 both read as <IP_ADDRESS_1>, the model can no
longer tell "listen on every interface" from "loopback only" — detection that
fires where there is nothing to find is how people learn to ignore it.

Detection runs locally without an account, API key, network request, daemon,
telemetry, or prompt history.

Install

shim Guard supports CPython 3.9 through 3.13 on macOS and Linux, including
the system python3 on macOS. Choose one package manager:

uv tool install --compile-bytecode shim
# or
pipx install shim

If you installed the previous shim-guard distribution, uninstall it before
installing shim; both distributions provide the same commands.

Preview and install the hook for your client:

shim install codex --dry-run
shim install codex
shim doctor codex

Replace codex with claude or copilot as needed. Run shim help for all
commands.

Marketplace plugins

Codex and Claude Code users can install the repository's marketplace plugin:

codex plugin marketplace add GetSHIM/shim-cli
codex plugin add shim-guard@shim-guard

/plugin marketplace add GetSHIM/shim-cli
/plugin install shim-guard@shim-guard

The marketplace plugin and shim install are alternative hook-registration
methods. Do not use both for the same client. Release-tag Claude plugins bundle
the hook archive and need only Python 3.9 or newer; the Codex plugin currently
uses shim-guard-hook from the installed CLI package. A development checkout
may not contain the release archive.

Use

Once the hook is installed, use your client normally. To inspect text directly,
pipe it through scan or redact:

printf '%s' 'Contact me at [email protected]' | shim scan
printf '%s' 'Contact me at [email protected]' | shim redact

Both commands read standard input. Do not pass real prompts as command-line
arguments, where they may be recorded in shell history or process listings.

[!IMPORTANT]
With the default configuration, shim Guard does not prevent a secret you
type into a prompt from reaching the model. It tells you afterwards.
Codex and Claude Code offer no field for rewriting a submitted prompt, so the
only way to stop one is to refuse the sentence you just typed — which is
disruptive and rare enough that it is not the default. Set
user-prompt = "enforce" in [mode] to block instead. Copilot's
userPromptTransformed event does support a model-facing replacement. Claude
tool results are masked at the verified installed events.

See what it did

shim says nothing when it works, so it keeps a short record of its own
decisions. Claude's verified Stop hook shows the total at the end of a turn
where something changed:

shim — this session
  masked    60 EMAIL  (Read customers.csv)
            60 IBAN  (Read customers.csv)
            60 PHONE  (Read customers.csv)
            60 TR_NATIONAL_ID  (Read customers.csv)
  flagged   1 INSTRUCTION_OVERRIDE  (Read runbook.md)
            1 HIDDEN_TEXT  (Read runbook.md)
  overhead  62 ms median, 119 ms p95

That is a real session against Claude Code, not an illustration: a 5.5 KB
customer file, every value in it replaced before the model saw it, and a
document in the repository caught trying to give the agent instructions. Run
under shim watch at the same time, the proxy — which reads the actual wire,
independently of the hook — reported two email addresses in the whole session,
both from the client's own system messages. None of the sixty reached the
model.

shim report prints the same summary on demand, and --json makes it
scriptable. It reads the newest temporary spool first; if none remains, it
falls back to the retained ledger, if you turned that on.

Shrink tool results

At Claude's verified PostToolUse event, shim compacts eligible tool results
before the model reads them, so the context window fills more slowly. Nothing
is ever truncated or summarised, and a result that cannot be shrunk safely is
left unchanged by the diet. Two transforms ship; only lossless JSON compaction
is on by default:

It applies to tool results only — never to a tool's arguments, never to
anything written to your disk, and never under mode = "observe".

The diet also never touches a result that shows you a file. Edit matches its
old_string against what is on disk, not against what the model was shown, so
compacting a pretty-printed file on the way in makes the next edit of that file
miss. Reads, notebooks and edit results are unchanged by the diet; sensitive
values can still be masked according to policy. Fetched pages, command output
and tool results are where the saving comes from.

Turn it off with shim config --no-diet, or name individual transforms in the
config file. Trailing-whitespace removal is opt in because it can remove a
Markdown hard line break:

diet = ["json", "whitespace"]   # or false to disable entirely

While reading results shim also flags text that is trying to give the model
orders — "ignore all previous instructions", impersonated system messages,
invisible characters. These are reported and never acted on: rewriting a
tool result because it reads as imperative would corrupt legitimate content.
They appear in the session summary as flagged, naming the file they came
from — which is the only part you can act on:

  flagged   1 INSTRUCTION_OVERRIDE  (Read release-notes.md)
            1 HIDDEN_TEXT  (Read release-notes.md)

The record holds entity names, counts and the file or URL involved — never the
value that was found, and never a shell command. It lives in a private OS
temporary file. Claude's installed SessionEnd hook deletes that session's
file; clients without a verified lifecycle hook leave it to operating-system
temporary cleanup. shim config --ledger opts in to monthly retained copies.
A month becomes eligible for pruning 30 days after its end and is removed on a
later ledger write; shim ledger purge deletes all ledger files immediately.
Nothing is ever transmitted. See
Privacy.

Configure detection

All supported entity types are enabled by default. View or change the local
policy with:

shim config
shim config --only EMAIL --only SECRET
shim config --disable IP_ADDRESS --disable MAC_ADDRESS
shim config --reset
shim config --ledger        # keep the session record past the session
shim config --no-diet       # stop shrinking tool results

shim config with no arguments prints the entity table plus the current
ledger and diet state, so what shim keeps and what it rewrites is answerable
without opening the file.

Detection can also be narrowed for one tool at a time, which the CLI has no
flag for — scan commands for secrets without scanning every file read for
phone numbers:

[entities]
Bash = ["SECRET", "DB_URI"]
Read = ["SECRET"]

Every key in the file is optional. A file holding only [mode] or only
[entities] is valid and everything else keeps its shipped default.

Changes are previewed before they are saved. The CLI, installed hook, scan,
and redact all use the same policy.

Privacy limitations

• The host client receives the raw prompt before its hook runs, and other hooks
  may receive it concurrently.
• Detection is best-effort and may miss sensitive values.
• A disabled, untrusted, crashed, or timed-out hook may fail open according to
  client behavior.
• Clients, providers, and other tools may retain data independently of shim.
• Redacted temporary files may still contain missed sensitive content. Review
  them before resubmission and delete them when finished.

See Privacy for the full trust boundary and
Compatibility for tested versions and evidence.

Uninstall

Remove shim Guard's hook before uninstalling the package:

shim revert codex

Replace codex with the client you installed. shim watch needs no uninstall:
it edits nothing, so there is nothing to undo.

Project documentation

• Architecture
• Compatibility
• Privacy
• 0.2.0 release notes
• Contributing
• Security policy

Development

Run the complete local check from the repository root:

python scripts/check.py

License

Apache-2.0. See LICENSE.