From 65b5d938d6adbf2a64d00457692cb685f7cf454c Mon Sep 17 00:00:00 2001
From: Joseph Fung <joseph@josephfung.ca>
Date: Tue, 12 May 2026 12:14:10 -0400
Subject: [PATCH 1/2] fix: strengthen CLAUDE.md guidance for built-in tools and
 --prefix patterns

Add explicit guidance to use Read/Grep/Glob/Edit tools instead of
shell utilities (sed, cat, head, tail, awk, grep, find) for file
operations. Expand the directory command section with explicit
anti-patterns (cd /path && command), wrong/right examples, and pnpm
--prefix coverage.
---
 settings/claude-md.md | 48 ++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 43 insertions(+), 5 deletions(-)

diff --git a/settings/claude-md.md b/settings/claude-md.md
index 6844171..698dcb0 100644
--- a/settings/claude-md.md
+++ b/settings/claude-md.md
@@ -17,18 +17,56 @@ Do this every time — no exceptions.
 TrimKit installs a `no-chaining` hook that blocks `&&`, `||`, and unsafe pipes
 in Bash tool calls. Use the patterns below to avoid triggering it.
 
+## Use built-in tools instead of shell utilities
+
+**Never use `cat`, `head`, `tail`, `sed`, or `awk` to read file contents.**
+Use the `Read` tool instead — it supports `offset` (starting line) and `limit`
+(number of lines) for reading specific ranges:
+
+```
+# Wrong — triggers permission prompts and bypasses built-in tools:
+sed -n '335,340p' /path/to/file.ts
+cat /path/to/file.ts | head -20
+head -50 /path/to/file.ts
+
+# Right — use the Read tool:
+Read(file_path="/path/to/file.ts", offset=335, limit=6)
+```
+
+Similarly, use `Grep` instead of `grep`/`rg`, `Glob` instead of `find`/`ls`,
+and `Edit` instead of `sed`/`awk` for modifications. The built-in tools are
+faster, don't require permission approvals, and give better user visibility.
+
 ## Running commands in a specific directory
 
-Never chain with `&&` — the hook blocks it. Use the built-in flag instead:
+**Never use `cd /path && command`** — the `&&` will be blocked by the hook, and
+`cd` does not persist between Bash tool calls anyway. Use the built-in flag for
+each tool:
 
 ```bash
-# npm — use --prefix:
+# Wrong — blocked by the hook:
+cd /path/to/dir && npm list nylas | head -5
+cd /path/to/dir && git status
+cd /path/to/dir && pnpm test
+
+# Right — use --prefix or -C:
+npm --prefix /path/to/dir list nylas | head -5
+pnpm --prefix /path/to/dir test
+git -C /path/to/dir status
+```
+
+All three package managers support `--prefix`:
+
+```bash
+# npm:
 npm --prefix /path/to/dir install
 npm --prefix /path/to/dir run test
-npm --prefix /path/to/dir run build
 
-# git — use -C:
-git -C /path/to/dir status
+# pnpm:
+pnpm --prefix /path/to/dir install
+pnpm --prefix /path/to/dir run test
+
+# git:
 git -C /path/to/dir add file.ts
 git -C /path/to/dir commit -m "message"
 ```

From e0ec80d67db7b1ad7204a0bb0a5bc68c12920bdf Mon Sep 17 00:00:00 2001
From: Joseph Fung <joseph@josephfung.ca>
Date: Tue, 12 May 2026 12:23:44 -0400
Subject: [PATCH 2/2] fix: clarify direct file ops vs pipe filter distinction,
 add code fence lang

---
 settings/claude-md.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/settings/claude-md.md b/settings/claude-md.md
index 698dcb0..14679fc 100644
--- a/settings/claude-md.md
+++ b/settings/claude-md.md
@@ -19,11 +19,12 @@ in Bash tool calls. Use the patterns below to avoid triggering it.
 
 ## Use built-in tools instead of shell utilities
 
-**Never use `cat`, `head`, `tail`, `sed`, or `awk` to read file contents.**
+**Never use `cat`, `head`, `tail`, `sed`, or `awk` for direct file operations.**
 Use the `Read` tool instead — it supports `offset` (starting line) and `limit`
-(number of lines) for reading specific ranges:
+(number of lines) for reading specific ranges. These utilities are still allowed
+as filters in pipes (see the Pipes section below).
 
-```
+```bash
 # Wrong — triggers permission prompts and bypasses built-in tools:
 sed -n '335,340p' /path/to/file.ts
 cat /path/to/file.ts | head -20