DEV Community: Lily

Auto-Generating an Index of Your Claude Code Custom Agents from Their Frontmatter

Lily — Wed, 29 Jul 2026 00:00:06 +0000

This is a continuation of my "Claude Code environment" series. In the previous post, Automatically thinning conversation logs to prevent bloat, I introduced the basic pattern for scheduled launchd jobs. This time I'm using that same mechanism to automatically maintain a list of the custom agents in ~/.claude/agents/.

Dropping a single .md file into ~/.claude/agents/ adds a custom agent, but before long you lose track of how many you have, what model each one uses, and which tools each is allowed to touch. That's exactly what happened to me with the 27 agents I now have. I tried writing an INDEX.md by hand to manage them, and of course within a few days it had drifted from reality.

The problem: the index rots

Manually updating INDEX.md every time you add a custom agent is not sustainable.

You forget you added one and leave it out
You change a model later and never reflect it in INDEX.md
You typo a name or description and never notice

I concluded there was no sustainable way to manage this other than "generate it automatically," so I wrote agents-index.sh.

The output: a real INDEX.md

Here's how the top of my current ~/.claude/agents/INDEX.md looks.

<!-- AUTO-GENERATED by ~/.claude/scripts/agents-index.sh — DO NOT EDIT MANUALLY -->
# Agents Index (27 agents · 2026-07-28 02:02)

| Name | Model | Description | Tools |
|------|-------|-------------|-------|
| `architect` ([architect.md](./architect.md)) | opus | Software architecture specialist ... | ["Read", "Grep", "Glob"] |
| `build-error-resolver` ([build-error-resolver.md](./build-error-resolver.md)) | sonnet | Build and TypeScript error resolution specialist ... | ["Read", "Write", "Edit", "Bash", "Grep", "Glob"] |
| `doc-updater` ([doc-updater.md](./doc-updater.md)) | haiku | Documentation and codemap specialist ... | ["Read", "Edit", "Bash", "Grep", "Glob"] |

Four columns: Name, Model, Description, and Tools. You can see at a glance how the models break down across opus / sonnet / haiku, and immediately check things like "did this agent have Bash allowed?"

Running it with the --json option also writes the same content to .index.json, so other scripts like a cost-tracker can reuse it.

How the script is designed

~/.claude/scripts/agents-index.sh is a Bash outer shell with an inline Python3 script embedded in it.

#!/usr/bin/env bash
set -uo pipefail

AGENTS_DIR="$HOME/.claude/agents"
INDEX_MD="$AGENTS_DIR/INDEX.md"
INDEX_JSON="$AGENTS_DIR/.index.json"
LOGFILE="$HOME/.claude/logs/agents-index.log"
mkdir -p "$HOME/.claude/logs"

EMIT_JSON=0
[ "${1:-}" = "--json" ] && EMIT_JSON=1

python3 - "$AGENTS_DIR" "$INDEX_MD" "$INDEX_JSON" "$EMIT_JSON" "$LOGFILE" <<'PY'
# ... (Python本体)
PY

The reason for embedding Python as a heredoc is to hand string processing off to Python while avoiding shell PATH problems. Parsing YAML in pure Bash is dangerous, and assuming pip install pyyaml would only add more environment dependencies.

A frontmatter parser with no PyYAML dependency

Agent definitions only ever use single-level key-value pairs, so a regex plus line splitting is enough.

def load_frontmatter(path):
    text = path.read_text(encoding="utf-8", errors="replace")
    m = re.match(r"^---\n(.*?)\n---\n", text, flags=re.DOTALL)
    if not m:
        return None, "missing frontmatter"
    body = m.group(1)
    out = {}
    for line in body.split("\n"):
        if not line.strip() or line.startswith("#"):
            continue
        if ":" not in line:
            continue
        k, _, v = line.partition(":")
        k = k.strip()
        v = v.strip()
        # quoted string 剥がす
        if (v.startswith('"') and v.endswith('"')) or (v.startswith("'") and v.endswith("'")):
            v = v[1:-1]
        out[k] = v
    return out, None

re.DOTALL grabs everything between the --- markers wholesale, then partitioning on : makes everything left of the first : the key. JSON array values like tools are kept as plain strings and truncated at 60 characters for display.

Warnings for missing fields

An agent with an empty name or description is useless even if it shows up in the list. After parsing, the script checks the required fields and appends a warnings section at the end of INDEX.md.

if not name:
    warnings.append(f"{p.name}: missing 'name'")
if not desc:
    warnings.append(f"{p.name}: missing 'description'")

The end of the generated output looks like this.

## ⚠️ Validation warnings
- foo-agent.md: missing 'description'

Note
Files that are missing frontmatter entirely get routed to the warnings as "missing frontmatter" and don't appear in the table. I designed it to record a warning instead of failing with an error so that INDEX.md generation itself still succeeds while keeping it clear which file is broken.

launchd config: automatic run at 6:30 on Sundays

The StartCalendarInterval in ~/Library/LaunchAgents/com.shun.agents-index.plist looks like this.

<key>StartCalendarInterval</key>
<dict>
    <key>Hour</key>
    <integer>6</integer>
    <key>Minute</key>
    <integer>30</integer>
    <key>Weekday</key>
    <integer>0</integer>
</dict>

Weekday: 0 is Sunday. The idea is that an up-to-date list is always waiting for me before I start work at the beginning of the week.

Process priority is lowered three ways: Nice: 10 + LowPriorityIO: true + ProcessType: Background. Index generation involves disk I/O, but lowering the priority of the work keeps it from affecting Claude Code's own responsiveness.

Loading is a one-time launchctl load.

launchctl load ~/Library/LaunchAgents/com.shun.agents-index.plist

If you want to run it right now by hand, just call it directly.

~/.claude/scripts/agents-index.sh --json
# → agents=27 warnings=0 → ~/.claude/agents/INDEX.md

Pitfalls I hit

INDEX.md itself becomes a loop target → you need to exclude it with if p.name == "INDEX.md": continue. Forget it and INDEX ends up reading INDEX and breaking
A | in a description breaks the table → always run .replace("|", "\\|") after parsing. It's in the real code, but I forgot it at first
tools arrives as a JSON array string, so it easily exceeds the 60-character limit → ["Read", "Write", "Edit", "Bash", "Grep", "Glob"] is already close to 50 characters. Mixing in MCP tools overflows immediately, so truncation + ... is essential
Writing both StandardOutPath and a >> redirect in ProgramArguments in the plist gives you duplicate logs → in my actual plist both point at the same file so there's no real harm, but if you're cleaning up you should consolidate to one of them
StartCalendarInterval is skipped while the Mac is asleep → launchd runs it after waking, but if the machine stays asleep through Sunday you won't get an update until Monday morning. A weekly update is good enough for me so I accept this, but if you want strictness, combine it with pmset -a wake 1

Summary

Once ~/.claude/agents/ grows, a manually maintained INDEX.md is guaranteed to rot → automate the generation
Read the frontmatter with a one-line parser that doesn't depend on PyYAML, and generate a Markdown table plus .index.json
Missing fields are appended as a warnings section at the end of INDEX.md, and the script itself doesn't stop
launchd's Weekday: 0 / Hour: 6 / Minute: 30 runs it automatically at 6:30 on Sundays. Nice: 10 + LowPriorityIO keeps it out of your way
You can also update immediately by hand with a single agents-index.sh --json

Next time, I plan to write about a mechanism that uses this agent list to visualize cost trends per model.

Written by **Lily* — I ship iOS apps and automate my content stack with Claude Code.
Follow along: Portfolio · X · GitHub*

Nightly tail-truncation: how I stopped Claude Code's logs from quietly eating my disk

Lily — Tue, 28 Jul 2026 00:00:05 +0000

Log files never announce themselves. They just sit there growing until something breaks. This is part of my "Claude Code environment" series — the previous post, "Trimming agent logs", touched on log bloat in general. This time it's the concrete implementation: a tail-truncation script that runs every night at 3:45 via launchd.

Left alone, ~/.claude/logs/ swells quietly. Recently agentmemory.err.log hit 5.3MB in a single week, and the week before that hook-latency.jsonl and vault-auto-ingest.log both blew past 5MB at the same time, pushing the whole directory to 20M. Because monitoring scripts hold onto files with tail -f, the logrotate approach of creating a new file is off the table. That's exactly why I picked a method that keeps the file path fixed and only shaves the contents.

The problem: logrotate changes the path

logrotate's default behavior is "rename the old file to .1 and create a new file." tail -f and inotifywait, which hold the file descriptor via the inode, keep following it — but scripts that read by path (Claude Code's status line, cron, autopilot) never look at the new file, so the log appears empty.

Rewriting the path settings on the script side after every rotation isn't something you can sustain operationally. So I went with "fixed path, keep only the tail."

The fix: keep the tail with `tail`, overwrite with `mv`

These three lines are the heart of ~/.claude/scripts/log-rotate.sh.

MAX_BYTES=$((5 * 1024 * 1024))  # 5MB超えたら切詰め対象
KEEP_LINES=2000

tail -n "$KEEP_LINES" "$f" > "$f.tmp" && mv "$f.tmp" "$f"

Measure the byte count with stat and target only files over 5MB
Write the last 2000 lines out to a temporary file with tail -n 2000
Overwrite the original file with the temp file via mv → the inode doesn't change, and neither does the path

The reason it's > "$f.tmp" && mv rather than redirecting straight into > "$f" is to prevent the file from ending up empty if the process crashes mid-write.

Note
logrotate -c's copytruncate option can also "copy, then truncate the original," but if a session writes heavily between the copy and the truncation, you lose up to a few seconds' worth of log lines. tail + mv has no such window, which makes it the safer option here.

The full script

#!/bin/bash
# log-rotate.sh — ~/.claude/logs の肥大防止（毎日03:45 launchd）
set -uo pipefail
LOGDIR="$HOME/.claude/logs"
SELF_LOG="$LOGDIR/log-rotate.log"
MAX_BYTES=$((5 * 1024 * 1024))
KEEP_LINES=2000

echo "[$(date '+%F %T')] rotate start" >> "$SELF_LOG"

# 1) 肥大ログの切詰め（.log / .err / .out / .jsonl）
find "$LOGDIR" -maxdepth 1 -type f \( -name '*.log' -o -name '*.err' -o -name '*.out' -o -name '*.jsonl' \) | while read -r f; do
  sz=$(stat -f%z "$f" 2>/dev/null || echo 0)
  if [ "$sz" -gt "$MAX_BYTES" ]; then
    tail -n "$KEEP_LINES" "$f" > "$f.tmp" && mv "$f.tmp" "$f"
    echo "[$(date '+%F %T')] truncated $(basename "$f") ($sz bytes -> $(stat -f%z "$f") bytes)" >> "$SELF_LOG"
  fi
done

# 2) 日付付き成果物・マーカー・バックアップの30日超削除
find "$LOGDIR" -maxdepth 1 -type f \( \
  -name 'daily-brief-2*.md' -o -name 'project-health-2*.md' -o \
  -name '.*-done-*' -o -name '.vault-ingest-*' -o -name '*.plist.bak*' \
  \) -mtime +30 -delete 2>/dev/null

# 3) 自分自身のログも肥大防止
sz=$(stat -f%z "$SELF_LOG" 2>/dev/null || echo 0)
[ "$sz" -gt "$MAX_BYTES" ] && tail -n "$KEEP_LINES" "$SELF_LOG" > "$SELF_LOG.tmp" && mv "$SELF_LOG.tmp" "$SELF_LOG"

echo "[$(date '+%F %T')] rotate done (dir=$(du -sh "$LOGDIR" | cut -f1))" >> "$SELF_LOG"

-maxdepth 1 keeps it from descending into subdirectories, so only files directly under ~/.claude/logs/ are targeted. Subdirectories sometimes hold project data for other purposes, so this is insurance against accidental deletion.

Running quietly at night with launchd

Here's the relevant part of ~/Library/LaunchAgents/com.shun.log-rotate.plist.

<key>LowPriorityIO</key>
<true/>
<key>Nice</key>
<integer>10</integer>
<key>ProcessType</key>
<string>Background</string>
<key>StartCalendarInterval</key>
<array>
  <dict>
    <key>Hour</key>
    <integer>3</integer>
    <key>Minute</key>
    <integer>45</integer>
  </dict>
</array>

Three settings together create the "quiet nighttime run."

Key	Value	Effect
`LowPriorityIO`	`true`	Lowers disk I/O priority so it doesn't cut in on other processes
`Nice`	`10`	Lowers CPU priority (0 is the default; higher positive values mean lower priority)
`ProcessType`	`Background`	macOS manages it under the background quality-of-service class

StartCalendarInterval is set to 3:45 because autopilot starts at 5:00, and the intent is to finish the rollup just before that. Jobs scheduled while the Mac is asleep get skipped, so if the lid is closed overnight it won't run that day. I've accepted that trade-off.

Note
You can set up a wake schedule with pmset -g sched, but waking the machine every morning is bad for the battery even while charging. I chose to tolerate skips during sleep and protect the battery instead.

Deleting dated artifacts older than 30 days

Alongside truncation, the job deletes dated files matching -mtime +30.

find "$LOGDIR" -maxdepth 1 -type f \( \
  -name 'daily-brief-2*.md' -o -name 'project-health-2*.md' -o \
  -name '.*-done-*' -o -name '.vault-ingest-*' -o -name '*.plist.bak*' \
  \) -mtime +30 -delete 2>/dev/null

daily-brief-2*.md and project-health-2*.md are artifacts that Claude Code's automated tasks emit daily. Even at a few KB to a few dozen KB per file, stacking them up every day adds up to several GB a year. Once they're past 30 days, they've served their purpose and get deleted. .*-done-* and .vault-ingest-* are checkpoint files from cron jobs, and those also pile up into the hundreds if left alone.

Actual truncation records

Here are recent results from ~/.claude/logs/log-rotate.log.

[2026-07-19 03:45:05] truncated hook-latency.jsonl (5376787 bytes -> 178061 bytes)
[2026-07-19 03:45:05] truncated vault-auto-ingest.log (5255158 bytes -> 105277 bytes)
[2026-07-19 03:45:05] rotate done (dir=8.1M)

[2026-07-27 03:45:05] truncated agentmemory.err.log (5590723 bytes -> 297105 bytes)
[2026-07-27 03:45:06] rotate done (dir= 16M)

hook-latency.jsonl went from 5.1MB to 174KB, and vault-auto-ingest.log from 5.0MB to 103KB. Those two files alone cut that day's directory in half, from 17M to 8.1M. In the most recent run on 2026-07-27, agentmemory.err.log had reached 5.3MB and was brought down to 290KB.

Pitfalls I hit

Crashed mid-write with a direct > "$f" redirect → switched to mv via a tmp file so it's atomic
find recursed under .claude/ and nearly deleted project data → limited it to the top level with -maxdepth 1
launchd's minimal PATH meant the script couldn't find stat → spelled out /opt/homebrew/bin in the plist's EnvironmentVariables
Jobs got skipped while the Mac slept, leaving logs untouched for days → accepted the skips and kept a one-command manual launchctl kickstart ready for when the machine is awake
Realized my own log-rotate.log bloats too → added self-truncation at the end of the script (already built in as the third section of the script above)

Summary

~/.claude/logs/ accumulates .log / .err / .out / .jsonl files and passes 20M if left alone
Instead of logrotate creating a new file, overwrite with tail -n 2000 > tmp && mv tmp $f → the file path never changes, so monitoring scripts don't break
launchd's LowPriorityIO + Nice=10 + ProcessType=Background makes it run quietly at 3:45 AM
The same job cleans up dated artifacts older than 30 days — daily-brief-*.md and friends — with find -mtime +30 -delete

Next time: how I reuse the session history accumulated in these logs as long-term memory — leading into turning conversation logs into long-term memory.

Written by **Lily* — I ship iOS apps and automate my content stack with Claude Code.
Follow along: Portfolio · X · GitHub*

My Claude Code Logs Ballooned to 22MB — Nightly Auto-Trimming with launchd

Lily — Mon, 27 Jul 2026 05:00:05 +0000

Nobody plans for log files. You wire up a background job, it works, and six weeks later a directory you never look at is quietly eating your disk.

In my previous post on automating self-audits I built the skeleton of a nightly job. This post is about the side effect of that: the logs my resident agents keep spewing grew without bound, and how I designed a trimming script wired into launchd to keep things quiet.

Once you have 20+ agents running as residents, logs pile up by hundreds of KB per day. Measured this morning (right after the 03:45 automated run), ~/.claude/logs/ was 20M, and 21M as of now (10:43). 188 files. It was only a matter of time before it crossed 22MB.

The problem: disk gets heavier every morning at startup

The more launchd jobs there are, the more logs there are. Looking at the representative large files makes it obvious.

5.7M  agentmemory.err.log
3.8M  vault-auto-ingest.log
3.1M  hook-latency.jsonl
2.7M  cost-log.jsonl
 728K dotfiles-snapshot.log

Every one of them just streams errors and progress forever, and I almost never read the old lines. All I need is "what happened recently." And yet the logs keep accumulating, and the number from du -sh ~/.claude/logs/ jumps every day.

Plain deletion is a problem — if the log is empty when I'm chasing down a recent error, I'm stuck. So instead of deleting, I went with keeping only the tail.

The design: don't delete, keep only the last 2000 lines

The policy of log-rotate.sh fits in three lines.

Over 5MB → tail -n 2000 and overwrite (retain the most recent context)
Dated artifacts, markers, and .bak files → delete if older than 30 days
The script's own log gets the same treatment

I use the word "rotate," but it isn't rotation. It just truncates the file. No backups either. The latest 2000 lines are plenty to trace a recent failure.

The log-rotate.sh implementation

Here is the full text of ~/.claude/scripts/log-rotate.sh. It fits in 60 lines.

#!/bin/bash
# log-rotate.sh — ~/.claude/logs の肥大防止（毎日03:45 launchd）
# 方針: 5MB超のログは末尾2000行だけ残して切詰め / 30日超の日付付き成果物・マーカー・bakは削除
set -uo pipefail
LOGDIR="$HOME/.claude/logs"
SELF_LOG="$LOGDIR/log-rotate.log"
MAX_BYTES=$((5 * 1024 * 1024))
KEEP_LINES=2000

echo "[$(date '+%F %T')] rotate start" >> "$SELF_LOG"

# 1) 肥大ログの切詰め（.log / .err / .out / .jsonl）
find "$LOGDIR" -maxdepth 1 -type f \( -name '*.log' -o -name '*.err' -o -name '*.out' -o -name '*.jsonl' \) | while read -r f; do
  sz=$(stat -f%z "$f" 2>/dev/null || echo 0)
  if [ "$sz" -gt "$MAX_BYTES" ]; then
    tail -n "$KEEP_LINES" "$f" > "$f.tmp" && mv "$f.tmp" "$f"
    echo "[$(date '+%F %T')] truncated $(basename "$f") ($sz bytes -> $(stat -f%z "$f") bytes)" >> "$SELF_LOG"
  fi
done

# 2) 日付付き成果物・マーカー・バックアップの30日超削除
find "$LOGDIR" -maxdepth 1 -type f \( \
  -name 'daily-brief-2*.md' -o -name 'project-health-2*.md' -o \
  -name '.*-done-*' -o -name '.vault-ingest-*' -o -name '*.plist.bak*' \
  \) -mtime +30 -delete 2>/dev/null

# 3) 自分自身のログも肥大防止
sz=$(stat -f%z "$SELF_LOG" 2>/dev/null || echo 0)
[ "$sz" -gt "$MAX_BYTES" ] && tail -n "$KEEP_LINES" "$SELF_LOG" > "$SELF_LOG.tmp" && mv "$SELF_LOG.tmp" "$SELF_LOG"

echo "[$(date '+%F %T')] rotate done (dir=$(du -sh "$LOGDIR" | cut -f1))" >> "$SELF_LOG"

Truncation results are recorded in log-rotate.log. Here's actual output.

[2026-07-12 03:45:05] truncated agentmemory.err.log (5449070 bytes -> 331336 bytes)
[2026-07-19 03:45:05] truncated hook-latency.jsonl (5376787 bytes -> 178061 bytes)
[2026-07-19 03:45:05] truncated vault-auto-ingest.log (5255158 bytes -> 105277 bytes)
[2026-07-26 03:45:05] rotate done (dir=20M)

agentmemory.err.log shrank from 5.2MB → 324KB, and hook-latency.jsonl from 5.1MB → 174KB.

Note
The reason for the two-step tail -n 2000 "$f" > "$f.tmp" && mv "$f.tmp" "$f" is to prevent a redirect to the same file from blowing away its contents. Never use a direct > "$f" overwrite.

The launchd configuration

Here is the full text of ~/Library/LaunchAgents/com.shun.log-rotate.plist.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.shun.log-rotate</string>

    <key>ProgramArguments</key>
    <array>
        <string>/bin/bash</string>
        <string>~/.claude/scripts/log-rotate.sh</string>
    </array>

    <key>StartCalendarInterval</key>
    <array>
        <dict>
            <key>Hour</key><integer>3</integer>
            <key>Minute</key><integer>45</integer>
        </dict>
    </array>

    <key>LowPriorityIO</key><true/>
    <key>Nice</key><integer>10</integer>
    <key>ProcessType</key><string>Background</string>

    <key>StandardErrorPath</key>
    <string>~/.claude/logs/log-rotate.err</string>
</dict>
</plist>

Three things matter here.

Key	Value	Purpose
`LowPriorityIO`	true	Drops I/O to background priority so it doesn't block foreground work
`Nice`	10	Lowers CPU priority (normally 0; larger values mean lower priority)
`ProcessType`	Background	A declaration to the macOS scheduler, used in its thermal, battery, and memory pressure calculations

I set the start time to 03:45 to avoid the cluster of other jobs around 03:30. Autopilot runs at 05:00 and daily-brief at 06:00, so log cleanup gets done quietly before them.

Note
launchd skips runs while the machine is asleep. If it was sleeping, the job won't run until the next matching time. If you want it to run reliably every morning, either enable wake on scheduler with pmset -a wake 1, or line up your non-sleeping hours with 03:45.

How the directory size evolved

log-rotate.log retains the size from each morning. Extracting July's progression gives this.

[2026-07-03] rotate done (dir=6.3M)
[2026-07-06] rotate done (dir=9.5M)
[2026-07-07] rotate done (dir=13M)
[2026-07-11] rotate done (dir=17M)
[2026-07-12] truncated agentmemory.err.log → rotate done (dir=13M)  ← 初回切詰め
[2026-07-15] rotate done (dir=15M)
[2026-07-19] truncated 2本  → rotate done (dir=8.1M)  ← 2回目
[2026-07-25] rotate done (dir=18M)
[2026-07-26] rotate done (dir=20M)

On 07-12, when truncation ran, it dropped from 19M → 13M; on 07-19, from 17M → 8.1M. It keeps accumulating until a truncation target exceeds 5MB, then shrinks all at once the moment it does — a sawtooth pattern. The current 21M reflects SELF_LOG approaching 5MB, so it should shrink again at tomorrow's 03:45.

Pitfalls I hit

Direct overwrite with > "$f" → the file ends up empty — the shell processes the redirect first. The file gets truncated before tail reads it, leaving zero content. Always use the two-step tmp → mv.
Without launchd's StandardErrorPath, stderr disappears — script errors get silently discarded. Catch them in a separate file, log-rotate.err.
stat -f%z is macOS-only — on Linux it's stat -c%s. This plist is macOS launchd-specific so it's not an issue here, but be careful when taking the script to another environment.
find -mtime +30 is based on modification time — it's 30 days since last modification, not 30 days since creation. Files that keep getting updated won't be deleted (as intended).
Dropping maxdepth 1 pulls in files in subdirectories too — ~/.claude/logs/ is flat right now, but that would cause accidents once I add subdirectories in the future. -maxdepth 1 is mandatory.
Nice 10 alone still stalls when I/O gets heavy — always combine it with LowPriorityIO. Nice is CPU, LowPriorityIO is disk; they're separate axes.

Summary

With 20+ automation agents running as residents, ~/.claude/logs/ balloons past 21M if left alone (188 files)
Choosing "over 5MB → truncate, keeping only the last 2000 lines" instead of "delete" curbs the growth while retaining the most recent context
Combining LowPriorityIO=true + Nice=10 + ProcessType=Background in launchd makes it run with low CPU and I/O load during the quiet hours after wake
Truncation follows a sawtooth pattern — it shrinks all at once the moment it crosses 5MB, then fills up again. The 2000-line window turned out to be deep enough for tracing recent failures

Next time I plan to write about the other reason these logs pile up — digging into the root cause of why agentmemory.err.log keeps hitting 5MB so frequently.

Written by **Lily* — I ship iOS apps and automate my content stack with Claude Code.
Follow along: Portfolio · X · GitHub*

How Claude Code Detects Its Own Weekly Rot and Repairs Itself

Lily — Sun, 26 Jul 2026 00:00:10 +0000

Your Claude Code setup doesn't break in one dramatic moment — it degrades a few bytes at a time, and by the time you notice, you've been paying a context tax for weeks. In a previous post I covered running an unattended daily health check with launchd. This one is the follow-up: a three-layer loop that detects that quiet degradation weekly and hands the repair job to claude -p itself.

The problem: environments rot quietly if you leave them alone

Some things in a Claude Code environment grow just from doing your normal work.

~/.claude/rules/ and MEMORY.md keep getting appended to, until context injection quietly crosses 40KB
Experimental agent definition .md files never get archived, leaving dozens to nearly a hundred files under ~/.claude/agents/ permanently loaded
Stop hooks fire over and over, creating a hook spam condition
Frustration-signaling words pile up in conversation logs and nobody notices

A performance audit on 2026-07-11 revealed that "agents I thought I'd archived were still being injected — 99 of them," and that turned out to be the main cause of the degraded experience. That led to the question "so do I have to go check this every week myself?" — and the answer was to automate it, which is what cc-self-audit.sh does.

Five degradation metrics and their thresholds

The script measures five metrics and flags "red" when any of them crosses its threshold.

# 閾値（env変数で上書き可）
TH_INJECT_BYTES="${SELF_AUDIT_TH_INJECT:-40000}"   # rules+CLAUDE.md+MEMORY.md 合計バイト
TH_AGENTS="${SELF_AUDIT_TH_AGENTS:-60}"            # ~/.claude/agents 配下 .md 総数（再帰）
TH_STOPSPAM="${SELF_AUDIT_TH_STOPSPAM:-15}"        # 監査hook発火/週
TH_FRUSTRATION="${SELF_AUDIT_TH_FRUST:-8}"         # 不満ワード/週
TH_TOOLERR="${SELF_AUDIT_TH_TOOLERR:-400}"         # tool失敗/週

The first three are static metrics (state at this exact moment); the last two are dynamic metrics (trends since the previous run). That distinction maps directly onto how each one is measured, as described below.

Overall design: a three-layer loop

[層1] 静的計測  → 注入bytes / agents数
[層2] 動的計測  → hookスパム / 不満ワード / tool失敗（前回実行以降の窓）
[層3] 閾値超過  → claude -p が ~/.claude 内を自己修正
               → 独立再計測（自己申告は信じない）
               → Discord #01_alerts へ報告

If everything is green, it sends a single ✅ line and exits. Since it only runs once a week, it stays low-noise while also doubling as a liveness check.

Layer 1: static measurement

inject_bytes=$(( \
  $(find "$HOME/.claude/rules" -name '*.md' -print0 2>/dev/null | xargs -0 cat 2>/dev/null | wc -c) + \
  $(cat "$HOME/.claude/CLAUDE.md" 2>/dev/null | wc -c) + \
  $(cat "$HOME/CLAUDE.md" 2>/dev/null | wc -c) + \
  $(cat "$HOME/.claude/projects/-Users-matsubara/memory/MEMORY.md" 2>/dev/null | wc -c) ))
agents_loaded=$(find "$HOME/.claude/agents" -name '*.md' 2>/dev/null | wc -l | tr -d ' ')

Making find … -name '*.md' recursive is deliberate: it catches agent files that have snuck into dot-directories (.tmp/ and friends) so the problem can be detected if it recurs. If you only look at a single flat level, you'll never notice files that failed to get archived out of a subdirectory starting with ..

Layer 2: dynamic measurement (the window since the last run)

By only targeting .jsonl files newer than the marker for the previous run time (self-audit/lastrun.marker), it looks at only that week's delta.

[ -f "$LASTRUN" ] && newer="-newer $LASTRUN"
files=$(find "$HOME/.claude/projects" -maxdepth 2 -name '*.jsonl' $newer -size +100k 2>/dev/null | head -200)

However, a naive grep produced a lot of false positives (detailed in the pitfalls section below). In the end I improved precision with inline Python.

STOP_MARKER = 'Stop hook feedback:\\n[~/.claude/hooks/self_audit_stop.sh]: '
FRUST_RE = re.compile(r'何回も言|いい加減にし|嘘つ|舐めんな|なんで治らん|最悪やろ|頭悪い')

# stopspam: harnessが実際に注入する行のみ
if STOP_MARKER in line:
    stopspam += 1

# frustration: isMeta でない type=user のテキストブロック（人間の実発言）のみ
if o.get('type') != 'user' or o.get('isMeta'):
    continue
content = (o.get('message') or {}).get('content')
# ... テキスト抽出して FRUST_RE で判定

stopspam counts only the Stop hook lines injected by the harness. frustration targets only human utterance text within the conversation (type=user and non-meta). That eliminated false positives from cases like "I just read the hook's own source code with the Read tool."

Layer 3: self-repair via claude -p

If even one metric crosses its threshold, a repair prompt is piped into claude -p.

OUT=$(cd "$HOME/.claude" && printf '%s' "$PROMPT" | run_capped "$FIX_TIMEOUT" "$CLAUDE" -p \
      --model "$MODEL" --output-format text \
      --allowedTools "Read,Write,Edit,Bash,Grep,Glob" \
      --max-turns 50 2>&1) || true

--allowedTools narrows it to reading and writing inside ~/.claude only — no touching project code or plists. The prompt is handed the violations, all metrics, and the last five history entries (the trend).

Known degradation patterns and their remedies are spelled out too (excerpt):

- agents_loaded超過 → 退避漏れを ~/.claude/agents-archive/ へ移動
- inject_bytes超過  → 肥大したrules/MEMORY.mdを圧縮し、フル版は rules-archive/ へ
- stopspam超過      → ~/.claude/hooks/self_audit_stop.sh の抑制ロジックを点検
- frustration超過   → 該当transcriptをgrepして繰り返し失敗の真因を特定

Each change gets appended one at a time to logs/self-audit-changes.log with "timestamp / target / reason / how to revert". Requiring the revert instructions is what lets a human roll back when the automatic repair makes a bad call.

"Never trust self-reporting" — independent re-measurement

When claude -p says "fixed it," that's self-reporting. Rather than using that directly in the report, it re-measures independently with the same collect() function.

# 独立再計測（自己申告は信じない）
AFTER=$(collect)
log "after: $AFTER"
echo "$AFTER" >> "$HISTORY"
STILL=$(echo "$AFTER" | breaches)

if [ -z "$STILL" ]; then
  notify "🔧 CC自己監査: 劣化検知→自己修正済み。前:[$BREACH] 後:全緑。詳細=$CHANGELOG"
else
  notify "🚨 CC自己監査: 自己修正後も残存 [$STILL]。要確認: $LOG / $CHANGELOG
Claude要約: $(echo "$OUT" | tail -3 | tr '\n' ' ')"
fi

If a threshold is still exceeded after the repair, it's marked as "remaining" and thrown back to the human. Since the notification includes the CHANGELOG path, you can immediately trace what was touched.

launchd config (Sundays at 8:30)

<key>StartCalendarInterval</key>
<dict>
    <key>Hour</key>      <integer>8</integer>
    <key>Minute</key>    <integer>30</integer>
    <key>Weekday</key>   <integer>0</integer>  <!-- 0 = 日曜 -->
</dict>
<key>LowPriorityIO</key>  <true/>
<key>Nice</key>           <integer>10</integer>
<key>ProcessType</key>    <string>Background</string>

Every Sunday at 8:30. LowPriorityIO and Nice 10 keep it from getting in the way of other work. Since RunAtLoad: false, it doesn't fire immediately after launchctl load — it waits for the next calendar time.

Note
Putting the weekly run on Sunday is deliberate: I want the environment in good shape before Monday's work starts, and running it twice a week or more would turn the notifications into noise. Because it doubles as a liveness check, the whole premise is that "a ✅ arrives every week even when nothing is wrong."

Pitfalls I hit

grep inflated stopspam to 40 → the hook's own source was included in the old_string of an Edit tool call, so it was counting the body of Read/Write/Edit tool_results too. Fixed by narrowing the Stop hook line to an "exact match on the format the harness injects" and doing line-level checks in Python
frustration looked like 18 but was actually 4 → it was falsely matching Read output in tool_results (a file that happened to contain the target words got opened). Fixed by narrowing to human utterances only: type=user and non-meta
Recursive agents_loaded picks up unintended files → if notes that call themselves .md sneak in, the count balloons. The threshold of 60 is a value with headroom above the actual agent count (and can be overridden)
Real verification with SELF_AUDIT_DRY=1 → before letting the claude -p repair path fire for the first time in production, I confirmed only collect/breach with DRY=1. The repair path is structurally identical to self-repair.sh, so structural risk is low
launchd's minimal PATH can't find claude → the plist explicitly sets PATH=/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:~/.local/bin. Managed separately from scripts that additionally need a fallback to nvm-managed node

Summary

Left alone, a Claude Code environment quietly degrades through growing injection bytes, agent bloat, and hook spam
Measure five metrics (inject_bytes / agents_loaded / stopspam / frustration / toolerr) weekly and detect threshold breaches mechanically
On a breach, claude -p repairs only what's inside ~/.claude, and always records "how to revert" in the change log
After the repair, verify the numbers actually improved with independent re-measurement — don't trust an AI's self-report
Even when everything is green, send a weekly one-line ✅ so it doubles as a liveness check

Next time I'll write about the transcript from an actual run where "agent bloat → automatic archiving" fired in this audit loop, plus turning history.jsonl into a trend graph.

Written by **Lily* — I ship iOS apps and automate my content stack with Claude Code.
Follow along: Portfolio · X · GitHub*

Automating a Daily Morning Health Check for Your Claude Code Setup with launchd

Lily — Sat, 25 Jul 2026 00:00:14 +0000

In my previous post, Monitoring Claude Code hook watchdogs with launchd, I set up liveness monitoring for hooks — and immediately ran into the next question: a healthy hook means nothing if the product behind it is down. What I really wanted was a single page I could skim in five minutes every morning and know that everything is fine.

That page is daily-brief.sh. launchd runs it three times a day (8:00, 10:30, and at login), and it compiles production HTTP probes, hook latency p95, launchd exit codes, 7-day API costs broken down by model, and per-project git status into one Markdown file appended to Obsidian.

The problem: checking five places by hand every morning

The more you automate, the higher the risk that something breaks silently. I used to open all of these manually every morning:

The Vercel dashboard (production liveness)
launchctl logs (scheduled job failures)
Claude Code cost usage
git status for each project
The hook latency JSONL

Just opening them took 3–5 minutes. Two incidents slipped through unnoticed (2026-06-11: GitHub Scout silently going blank, and a server configuration error in the autolike license API). Consolidating everything into one automatically delivered page makes missing things physically impossible.

Overall design: 3 triggers → 1 Markdown file → append to Obsidian

launchd
  ├─ StartCalendarInterval: 8:00
  ├─ StartCalendarInterval: 10:30
  └─ RunAtLoad: true（ログイン時）
        ↓
  ~/.claude/scripts/daily-brief.sh
        ↓
  ~/.claude/logs/daily-brief-YYYYMMDD.md        ← 正本ログ
  ~/.claude/logs/daily-brief-latest.md          ← 最新コピー
  ~/Desktop/Daily Brief/today-brief-YYYYMMDD.md
  ~/Documents/claude-obsidian/wiki/briefs/daily/today-brief-YYYYMMDD.md

Even when the second run fires at 10:30, the marker  prevents duplicate appends (details below). The script opens like this:

#!/usr/bin/env bash
# launchd で毎日 8:00 / 10:30 / ログイン時 実行（再実行してもマーカーで二重追記しない）。
# 注意: Desktop / ~/Documents(vault) は TCC 保護領域 → plist は /bin/bash 直起動（FDA付与済み）。
#       /bin/zsh 経由だと FDA 未付与で書き込みに失敗する。

set -uo pipefail

DATE=$(date +%Y%m%d)
TS=$(date '+%Y-%m-%d %H:%M')
OUT="$HOME/.claude/logs/daily-brief-${DATE}.md"

Production HTTP probes: 3 retries + a 15-second timeout

Vercel cold starts can delay the first request, so a single one-shot curl produces false alarms as 000 (timeout). Here's the implementation of probe_url():

probe_url() {
  local name=$1 url=$2 code=000 attempt
  # Vercel等のコールドスタートで初回が遅い→単発だと000/タイムアウトの誤報。
  # 最大3回リトライ＋timeout延長で潰す。
  for attempt in 1 2 3; do
    code=$(curl -s -o /dev/null -w "%{http_code}" --max-time 15 "$url" 2>/dev/null || echo 000)
    if [ "$code" = "200" ] || [ "${code:0:1}" = "3" ]; then break; fi
    sleep 2
  done
  if [ "$code" = "200" ] || [ "${code:0:1}" = "3" ]; then
    echo "- ✅ **${name}**: ${code} (${url})"
  else
    echo "- ❌ **${name}**: ${code:-無応答} (${url})"
    flag_red "${name} 本番が ${code:-無応答}"
  fi
}

Only the combination of --max-time 15, sleep 2, and 3 retries finally eliminated the false alarms. In today's run (2026-07-24 08:10), all four production apps — the job-hunting tracker, the job-hunting navigator, the graduation planner, and AETHERIA RPG — came back 200 OK.

probe_autolike() goes all the way through the Gumroad billing flow. It hits the API with a dummy key: if the response is "license not found," things are healthy (the API is alive); if it's "server configuration error," the env vars are missing, which means Pro billing is dead.

probe_autolike() {
  local product=$1 resp
  resp=$(curl -s --max-time 8 -X POST https://autolike-license-server.vercel.app/api/verify \
    -H "Content-Type: application/json" \
    -d "{\"key\":\"HEALTHCHECK-DUMMY\",\"product\":\"${product}\"}" 2>/dev/null)
  if echo "$resp" | grep -q "サーバー設定エラー"; then
    echo "- ❌ **autolike/${product}**: サーバー設定エラー（env未設定→Pro課金死）"
    flag_red "autolike/${product} がサーバー設定エラー"
  elif echo "$resp" | grep -qE "ライセンスが見つかりません|valid"; then
    echo "- ✅ **autolike/${product}**: 課金フロー稼働（Gumroad到達OK）"
  fi
}

Anything flagged RED gets collected into a "🚨 Needs attention" section at the top of the brief. Today it caught two items — a GitHub Scout scoring failure and a missing audit log in the affiliate auto-poster — and I noticed both first thing in the morning.

Hook latency p95: aggregating JSONL with Python

Every hook execution appends one line — {"ts":..., "hook":..., "elapsed_ms":..., "exit_code":...} — to hook-latency.jsonl, and hook-latency-report.sh aggregates it.

python3 - "$JSONL" "$DAYS" <<'PY'
stats = collections.defaultdict(list)
...
for hook, vals in stats.items():
    vals_sorted = sorted(vals)
    n = len(vals_sorted)
    p95 = vals_sorted[min(n-1, int(n*0.95))]
    rows.append((hook, n, sum(vals_sorted)//n, p95, vals_sorted[-1], fail.get(hook, 0)))
rows.sort(key=lambda r: -r[3])  # p95 降順（遅いものを上に）

flag = " ⚠" if p95 > 1500 else ""
print(f"{hook:<32} {n:>5} {mean:>6}ms {p95:>6}ms {mx:>6}ms {fl:>5}{flag}")
PY

It flags anything with p95 > 1500ms with a ⚠ and sorts slowest-first, so you can tell at a glance what's heavy. Here are today's actual numbers (last 24h, 356 records):

=== hook latency (last 1d, 356 records) ===
hook                                 n    mean     p95     max  fail
----------------------------------------------------------------------
skills-auto-update.sh                8 2030404ms 3215081ms 3215081ms     0 ⚠
obsidian_context.sh                 71  61835ms  15679ms 3194281ms     0 ⚠
message_display_filter.sh           69  23740ms   9106ms 1469891ms     0 ⚠
cost_guard.sh                       68  16719ms   6789ms 1019530ms     0 ⚠
user_prompt_submit.sh               70   5516ms   6426ms 338132ms     0 ⚠
model_routing_reminder.sh           70    901ms   5703ms   6386ms     0 ⚠

obsidian_context.sh shows a p95 of 15679ms (~16 seconds) and a mean of 61835ms (~1 minute), but the mean is dragged up by max outliers, so p95 is what I judge by. Since the columns are sorted by p95 descending, "higher up = heavier" reads at a glance.

launchd exit codes: every job in one line

launchctl list | grep com.shun | awk '{printf "- %s (last exit=%s)\n", $3, $2}' | head -15

Today's output (excerpt):

- com.shun.daily-brief (last exit=0)
- com.shun.vault-auto-ingest (last exit=0)
- com.shun.autopilot (last exit=1)
- com.shun.self-repair (last exit=0)

You can immediately see that only autopilot is at exit=1. The other 13 jobs were all exit=0. For details I go to ~/.claude/logs/com.shun.<name>.log, but the brief already narrows down where things are failing.

7-day API cost by model

run_to 60 ~/.claude/scripts/cost-summary.sh 7 2>&1 | head -10

Today's actual numbers (last 7 days):

=== cost summary (last 7d) ===
  sessions: 1323
  total:    $11012.43
  avg/sess: $8.324

  per model:
    claude-fable-5: 56617 messages
    claude-opus-4-8: 43282 messages
    claude-sonnet-5: 1882 messages
    claude-sonnet-4-6: 632 messages

$11,012 over 7 days is within my Max plan's flat rate, but the per-model message counts show where usage is skewed. fable-5's 56,617 messages exceed opus-4-8's 43,282, which is useful input for tuning model routing.

run_to is a wrapper that keeps a hung child script from stalling the entire brief:

TIMEOUT_BIN="/opt/homebrew/bin/timeout"
run_to() { local s=$1; shift; if [ -n "$TIMEOUT_BIN" ]; then "$TIMEOUT_BIN" --kill-after=15 "$s" "$@"; else "$@"; fi; }

Both the hook latency report and the cost summary are wrapped in run_to 60.

Walking through personal projects' git status

for repo in \
  ~/dev/shukatsu-tracker \
  ~/dev/seo-affiliate-site \
  ~/Projects/autolike-license-server \
  ...; do
  [ -d "$repo/.git" ] || continue
  branch=$(git -C "$repo" rev-parse --abbrev-ref HEAD 2>/dev/null)
  uncommitted=$(git -C "$repo" status --porcelain 2>/dev/null | wc -l | tr -d ' ')
  last_commit=$(git -C "$repo" log -1 --format='%cr %s' 2>/dev/null \
    | cut -c1-70 | /usr/bin/iconv -f UTF-8 -t UTF-8 -c)
  echo "- **${name}** [${branch}]: ${uncommitted} 未コミット — _${last_commit}_"
done

There's a reason for sanitizing with iconv -f UTF-8 -t UTF-8 -c: cut -c operates on bytes, so it can split UTF-8 multibyte characters mid-sequence, after which grep treats the file as binary and marker detection breaks — a footgun I hit myself. In today's run I could immediately see that lead-finder was sitting at 75 uncommitted changes with its last commit three weeks ago (it's in an intentional PAUSE state).

Idempotent design: comment markers prevent duplicate appends

daily-brief.sh runs twice, at 8:00 and 10:30, and sometimes vault-auto-ingest.sh has already created the file first. I needed a design that appends exactly once no matter the execution order.

MARK="<!-- daily-brief ${DATE} -->"

for f in \
  "$HOME/Desktop/Daily Brief/today-brief-${DATE}.md" \
  "$VAULT/wiki/briefs/daily/today-brief-${DATE}.md"; do
  d=$(dirname "$f")
  [ -d "$d" ] || mkdir -p "$d" 2>/dev/null || { echo "WARN: $d 作成不可（TCC?）"; continue; }
  # ファイルがなければ placeholder を作る
  if [ ! -f "$f" ]; then
    { echo "# 今日のブリーフ — $(date +%F)"
      echo ""
      echo "_（Claude生成のブリーフ本文は auto-ingest 完了時にこの上へ差し替わる）_"
    } > "$f" 2>/dev/null || { echo "WARN: $f 作成不可（TCC?）"; continue; }
  fi
  # LC_ALL=C: 不正バイトがあっても grep がバイナリ扱いで見落とさないように
  LC_ALL=C grep -qF -- "$MARK" "$f" 2>/dev/null && continue
  { echo ""; echo "---"; echo ""; echo "$MARK"; cat "$OUT"; } >> "$f" 2>/dev/null \
    || echo "WARN: 合流追記失敗: $f"
done

LC_ALL=C forces grep into byte mode, which prevents the case where invalid bytes in the file make grep treat it as binary, return --, and miss the marker. In today's vault file,  appears exactly once, and I confirmed the 10:30 re-run was skipped.

Note: vault-auto-ingest.sh contains the same merge logic. Whichever runs first, a matching marker means the append is skipped, so nothing gets duplicated. The comment marker works as a "receipt" for the operation.

The TCC trap: `/usr/bin/env bash` fails

Since macOS Ventura, ~/Desktop and ~/Documents are protected by TCC (Transparency, Consent, and Control). When launchd starts your script, Full Disk Access is not inherited depending on the interpreter path.

<!-- ❌ /usr/bin/env 経由 → FDA未付与 → Desktop/Documentsへの書き込みがサイレントに失敗 -->
<key>ProgramArguments</key>
<array>
  <string>/usr/bin/env</string>
  <string>bash</string>
  <string>~/.claude/scripts/daily-brief.sh</string>
</array>

<!-- ✅ /bin/bash 直起動 → FDA付与済みで動く -->
<key>ProgramArguments</key>
<array>
  <string>/bin/bash</string>
  <string>~/.claude/scripts/daily-brief.sh</string>
</array>

Going through /usr/bin/env makes the process count as one without FDA, and both mkdir -p and file writes fail silently. No error message, no files created — just empty logs. This trap once cost me a full week of missing briefs.

Note: The script's shebang #!/usr/bin/env bash can stay as is. Changing only the first element of the plist's ProgramArguments to /bin/bash fixes it.

plist design points

Here are the key parts extracted from the actual file:

<key>Label</key>
<string>com.shun.daily-brief</string>

<key>ProgramArguments</key>
<array>
  <string>/bin/bash</string>
  <string>~/.claude/scripts/daily-brief.sh</string>
</array>

<!-- 8:00 と 10:30 の2回 -->
<key>StartCalendarInterval</key>
<array>
  <dict>
    <key>Hour</key><integer>8</integer>
    <key>Minute</key><integer>0</integer>
  </dict>
  <dict>
    <key>Hour</key><integer>10</integer>
    <key>Minute</key><integer>30</integer>
  </dict>
</array>

<!-- ログイン時にも即実行 -->
<key>RunAtLoad</key>
<true/>

<!-- バックグラウンドジョブがClaude Codeの応答を遅らせないために -->
<key>LowPriorityIO</key>
<true/>
<key>Nice</key>
<integer>10</integer>
<key>ProcessType</key>
<string>Background</string>

<!-- PATH を明示しないと homebrew/nvm/git が見つからない -->
<key>EnvironmentVariables</key>
<dict>
  <key>PATH</key>
  <string>/path/to/.nvm/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
</dict>

Making StartCalendarInterval an array lets you express multiple times in a single plist. If the Mac is asleep when a scheduled time passes, the job does not run at the next wake (that's just how launchd works). RunAtLoad: true compensates by also firing at login.

Note: ~ is not expanded inside a plist. Use absolute paths, or use $HOME inside the script.

Pitfalls I hit

No FDA when going through /usr/bin/env → changed the first plist element to launch /bin/bash directly
False 000 alarms from Vercel cold starts → fixed with 3 retries + --max-time 15 + sleep 2
Duplicate output from appending || echo 0 to grep -c → grep -c already prints "0" on zero matches, so || echo 0 is unnecessary
grep treating files as binary and missing markers with LC_ALL unset → LC_ALL=C grep -qF guarantees byte mode
cut -c splitting UTF-8 and breaking downstream grep → sanitize with iconv -f UTF-8 -t UTF-8 -c
A hung child script stalling the whole brief → wrap with timeout --kill-after=15 60 <cmd>
Jobs skipped when the Mac sleeps through a scheduled time → compensated with RunAtLoad

Summary

Production HTTP probes use 3 retries + --max-time 15 to prevent false alarms from Vercel cold starts
Hook latency p95 is aggregated from JSONL with Python, flagging anything over 1500ms with ⚠ and sorting slowest-first
launchd exit codes are checked across all jobs with one line: launchctl list | grep com.shun
7-day costs include per-model message counts, feeding into model routing decisions
Idempotent design with the  marker means no duplicate appends regardless of order or run count
The TCC restriction is worked around by launching /bin/bash directly in the plist

Next time, I'll cover the design of an assistant hook that automatically appends "yesterday's Claude Code work summary" to this brief.

Written by **Lily* — I ship iOS apps and automate my content stack with Claude Code.
Follow along: Portfolio · X · GitHub*

The Bigger Your CLAUDE.md Gets, the Slower Claude Code Runs — Measuring Context Injection Bytes Weekly to Catch Degradation Early

Lily — Fri, 24 Jul 2026 11:00:06 +0000

This is the next installment in my "Claude Code environment" series. In the previous post on the self-audit frustration loop, I wrote about a "never-ending improvement loop." This time I want to dig into what sits at the root of it: detecting and self-correcting context injection bloat.

At the start of every session, Claude Code unconditionally injects the full contents of rules/*.md, ~/.claude/CLAUDE.md, ~/CLAUDE.md, and MEMORY.md. Every time you add a rule, this byte count silently grows. In an audit on 2026-07-11, I found that total injection had exceeded 40KB, and 99 agents I thought I had archived were still being loaded — the main cause of my performance degradation. Since then, I've kept a permanent loop running that measures this automatically every week and attempts self-correction when thresholds are exceeded.

The problem: it gets fat while nobody's looking

Adding rules to CLAUDE.md is a good thing. But "adding" only moves in one direction. After half a year, forgotten sections get duplicated, an archive you thought was compressed turns out to still be live, and files you moved to .agents/ keep getting loaded anyway.

The core issue is that degradation is invisible unless you measure it. Claude's gut feeling of "this seems sluggish" may be correct, but nobody routinely checks how many KB are being injected. I needed a mechanism that produces the numbers weekly and automatically attempts a fix when a human-defined threshold is exceeded.

What to measure

The collect() function in ~/.claude/scripts/cc-self-audit.sh assembles the metrics. There are two axes: static and dynamic measurement.

Static measurement: injection bytes and agent count

inject_bytes=$(( \
  $(find "$HOME/.claude/rules" -name '*.md' -print0 2>/dev/null | xargs -0 cat 2>/dev/null | wc -c) + \
  $(cat "$HOME/.claude/CLAUDE.md" 2>/dev/null | wc -c) + \
  $(cat "$HOME/CLAUDE.md" 2>/dev/null | wc -c) + \
  $(cat "$HOME/.claude/projects/-Users-matsubara/memory/MEMORY.md" 2>/dev/null | wc -c) ))
agents_loaded=$(find "$HOME/.claude/agents" -name '*.md' 2>/dev/null | wc -l | tr -d ' ')

find ... -name '*.md' recurses into dot directories too. Even if you think "I moved them to agents-archive/, so it's fine," if that directory lives under ~/.claude/agents/ as a dot directory, the files keep getting loaded — that's the trap (this is exactly how 99 agents survived on 2026-07-11).

Dynamic measurement: stopspam, frustration words, tool failures

Three metrics are aggregated from the transcripts (.jsonl) since the last run.

STOP_MARKER = 'Stop hook feedback:\\n[~/.claude/hooks/self_audit_stop.sh]: '
FRUST_RE = re.compile(r'何回も言|いい加減にし|嘘つ|舐めんな|なんで治らん|最悪やろ|頭悪い')

stopspam counts only "lines that the Stop hook actually injected into the prompt." A naive grep also picks up the same string when it happens to appear inside a tool_result, inflating the number 6–10x over reality (I fixed exactly this on 2026-07-12, correcting 40 → 6). For frustration, only text blocks of type=user that are not isMeta — i.e., the human's own raw utterances — are counted.

Thresholds

TH_INJECT_BYTES="${SELF_AUDIT_TH_INJECT:-40000}"   # rules+CLAUDE.md+MEMORY.md 合計
TH_AGENTS="${SELF_AUDIT_TH_AGENTS:-60}"            # ~/.claude/agents 配下 .md 総数
TH_STOPSPAM="${SELF_AUDIT_TH_STOPSPAM:-15}"        # 監査hook発火/週
TH_FRUSTRATION="${SELF_AUDIT_TH_FRUST:-8}"         # 不満ワード/週
TH_TOOLERR="${SELF_AUDIT_TH_TOOLERR:-400}"         # tool失敗/週

They're overridable via environment variables, so tuning them later never requires touching the script.

Breach detection → self-repair → independent re-measurement

breaches() lists the items that exceeded their thresholds and hands them to claude -p.

BREACH=$(echo "$METRICS" | breaches)

if [ -z "$BREACH" ]; then
  log "GREEN"
  notify "✅ CC自己監査: 正常 ($METRICS)"
  exit 0
fi

When there are breaches, the prompt restricts fixes to inside ~/.claude only (touching project code, secrets, or deleting plists is explicitly forbidden).

PROMPT="あなたはClaude Code環境の自己監査・自己修復エージェント。週次監査で劣化を検知した。
...
1. ~/.claude 内だけを調査・修正する（プロジェクトコード・secret・plist削除は禁止）
2. 既知の劣化パターンと正典:
   - agents_loaded超過 → ~/.claude/agents/ 配下の退避漏れを ~/.claude/agents-archive/ へ移動
   - inject_bytes超過 → 肥大したrules/MEMORY.mdを圧縮（フル版は ~/.claude/rules-archive/ へ）
   ...
4. 修正後に必ず 'bash ~/.claude/scripts/cc-self-audit.sh --collect-only' を実行し改善を数値で確認
..."

After claude -p finishes, the script itself calls collect() once more for an independent re-measurement. Claude's self-reporting is not trusted.

# 独立再計測（自己申告は信じない）
AFTER=$(collect)
STILL=$(echo "$AFTER" | breaches)

if [ -z "$STILL" ]; then
  notify "🔧 CC自己監査: 劣化検知→自己修正済み。前:[$BREACH] 後:全緑。"
else
  notify "🚨 CC自己監査: 自己修正後も残存 [$STILL]。要確認: $LOG"
fi

When everything is green, it sends ✅ a single line; breach followed by a successful fix sends 🔧 with before/after numbers; breaches remaining after the fix sends 🚨 — all to the #01_alerts channel on Discord. Since it's weekly, it never gets noisy — a low-noise setup that doubles as a liveness check.

Running it via launchd on Sundays at 8:30 AM

Here's the core of ~/Library/LaunchAgents/com.lily.cc-self-audit.plist.

<key>StartCalendarInterval</key>
<dict>
  <key>Hour</key><integer>8</integer>
  <key>Minute</key><integer>30</integer>
  <key>Weekday</key><integer>0</integer>   <!-- 0=日曜 -->
</dict>
<key>Nice</key><integer>10</integer>
<key>LowPriorityIO</key><true/>
<key>ProcessType</key><string>Background</string>

Nice=10 and LowPriorityIO=true are there because claude -p can run for up to 1200 seconds (the default value of FIX_TIMEOUT). To avoid squeezing the Mac's foreground work, the job is explicitly treated as background.

Note: If you don't set RunAtLoad: false, the script runs every time you bootstrap the plist. Don't forget to set RunAtLoad to false for weekly jobs.

Integration with automation-health.sh

The "weekly/monthly batch liveness" section of ~/.claude/scripts/automation-health.sh watches the modification time of cc-self-audit.log.

declare -a CRON_JOBS=(
  "weekly cleanup-misc:$CLAUDE/logs/cleanup-misc.log:192"
  "weekly env-audit:$CLAUDE/logs/env-audit-latest.md:192"
  ...
)
for entry in "${CRON_JOBS[@]}"; do
  a=$(age_h "$path")
  if [ "$a" -le "$budget" ]; then ok "$name: ${a}h前 (budget ${budget}h)"
  else wn "$name: ${a}h前 (budget ${budget}h 超過 — launchd 配送失敗の可能性)"; fi
done

If cc-self-audit.sh didn't run in a given week, automation-health.sh emits a WARN saying "over 192h." This closes the loop of "monitoring the monitor."

Pitfalls I hit

Archiving into a dot directory achieves nothing — even with a dot-prefixed name like .agents-backup/, find -name '*.md' still picks it up. You either need to place agents-archive/ outside ~/.claude/, or specify an exclusion path in the agents_loaded measurement expression
False grep matches inflated dynamic metrics 10x — transcripts embed "the source of that very script" as tool_result content. Use an exact match on STOP_MARKER plus a python3 JSON parse to filter down to user blocks that are not isMeta
Treating self-reporting as completion — even when claude -p says "I compressed inject_bytes," the numbers can't be confirmed without an independent re-measurement via collect(). Always fetch the post-fix score with --collect-only and record it in HISTORY
Setting FIX_TIMEOUT too short interrupts the fix — the default 1200 seconds (20 minutes) was almost always enough, but when there's a lot to fix, it times out midway and STILL remains non-empty. In that case, the 🚨 notification hands the decision to a human
launchd can't find claude without an explicit PATH — put both /opt/homebrew/bin and ~/.local/bin in the plist's EnvironmentVariables. launchd's PATH is a different beast from your interactive shell's

Summary

Claude Code's injected byte count can be measured with find ... | wc -c. Degradation you don't measure is degradation you can't see
Start from thresholds of TH_INJECT_BYTES=40000 / TH_AGENTS=60, then tune via env overrides to fit your own environment
Delegate fixes to claude -p scoped to ~/.claude only, then independently re-measure immediately afterward to verify its self-reporting
The launchd job at 8:30 AM on Sundays plus automation-health.sh gives you double-layered monitoring that can detect "the monitoring itself is dead"
Once a week, one line of output — no notification fatigue. A streak of green becomes the proof of health

Next time, I plan to write about how to compress the "bloated MEMORY.md" this loop detects while keeping the index consistent throughout.

Written by **Lily* — I ship iOS apps and automate my content stack with Claude Code.
Follow along: Portfolio · X · GitHub*

When Claude Detects "Why Isn't This Fixed Yet?" and Repairs Its Own CLAUDE.md: A Self-Improvement Loop Driven by Frustration Signals in Transcripts

Lily — Fri, 24 Jul 2026 05:00:11 +0000

In a previous post, I extracted skill usage stats from my conversation logs. This time I'm going the other way: a weekly loop that reads the transcripts to detect whether my Claude Code environment is degrading, and when a threshold is crossed, lets claude -p fix things itself.

~/.claude/scripts/cc-self-audit.sh (177 lines) runs every Sunday at 8:30 via launchd. It collects five numbers, compares them against thresholds, and if everything is green it sends a one-line ✅; if anything is red, it self-repairs, independently re-measures, and reports to Discord. About 70% of the implementation effort went into "why a naive grep doesn't work here."

The problem: nobody was detecting environment degradation

A performance audit on 2026-07-11 uncovered a triple whammy: agents that were supposedly moved out of the way were still being injected — 99 of them; CLAUDE.md had silently bloated to 228KB; and a Stop hook was firing dozens of times per week.

Each of those is fixable on its own. The real problem was that there was no mechanism to notice the "fixed it, but it broke again" cycle. A human doing a weekly visual check doesn't last, so I made a script do it.

Overall design: 5 metrics × thresholds × independent re-measurement

launchd（日曜 8:30）
  → cc-self-audit.sh
      ① collect()  →  5数値（静的2 + 動的3）
      ② breaches() →  閾値超過を列挙
      ③ 緑 → ✅通知・終了
      ④ 赤 → claude -p（sonnet・MAX枠）が ~/.claude 内を修正
      ⑤ collect() 独立再実行 → 数値改善を確認（自己申告は信じない）
      ⑥ Discord #01_alerts へ報告

(The flow: launchd on Sunday 8:30 → ① collect() gathers 5 numbers (2 static + 3 dynamic) → ② breaches() lists threshold violations → ③ green: notify ✅ and exit → ④ red: claude -p (sonnet, on my MAX plan) fixes things inside ~/.claude → ⑤ collect() re-runs independently to confirm the numbers improved (self-reports are not trusted) → ⑥ report to Discord #01_alerts.)

Thresholds (overridable via env vars):

Metric	Threshold	Variable
inject_bytes	40,000 B	`SELF_AUDIT_TH_INJECT`
agents_loaded	60 files	`SELF_AUDIT_TH_AGENTS`
stopspam	15 /week	`SELF_AUDIT_TH_STOPSPAM`
frustration	8 /week	`SELF_AUDIT_TH_FRUST`
toolerr	400 /week	`SELF_AUDIT_TH_TOOLERR`

Static metrics: injected bytes and agent count

inject_bytes=$(( \
  $(find "$HOME/.claude/rules" -name '*.md' -print0 2>/dev/null | xargs -0 cat 2>/dev/null | wc -c) + \
  $(cat "$HOME/.claude/CLAUDE.md" 2>/dev/null | wc -c) + \
  $(cat "$HOME/CLAUDE.md" 2>/dev/null | wc -c) + \
  $(cat "$HOME/.claude/projects/-Users-matsubara/memory/MEMORY.md" 2>/dev/null | wc -c) ))
agents_loaded=$(find "$HOME/.claude/agents" -name '*.md' 2>/dev/null | wc -l | tr -d ' ')

The find ~/.claude/agents -name '*.md' is deliberately recursive so it re-detects a failure mode I've already been burned by: agents that were "archived" into dot-prefixed subdirectories (like .backup/) getting loaded again. If agents_loaded exceeds 60, I treat it as "the archiving has leaked."

Dynamic metrics: reading only human-typed messages out of the transcript JSONL

This is the core of the design. Targeting "up to 200 JSONL files over 100KB that were updated since the last run," it counts stopspam (actual firings of the audit hook) and frustration (the user's frustration words).

STOP_MARKER = 'Stop hook feedback:\n[~/.claude/hooks/self_audit_stop.sh]: '
FRUST_RE = re.compile(r'何回も言|いい加減にし|嘘つ|舐めんな|なんで治らん|最悪やろ|頭悪い')

for line in fh:
    if STOP_MARKER in line:
        stopspam += 1
    try:
        o = json.loads(line)
    except Exception:
        continue
    if o.get('type') != 'user' or o.get('isMeta'):
        continue                          # ← ここが肝
    content = (o.get('message') or {}).get('content')
    texts = [content] if isinstance(content, str) else \
        [b.get('text', '') for b in content if isinstance(b, dict) and b.get('type') == 'text'] \
        if isinstance(content, list) else []
    if any(FRUST_RE.search(t) for t in texts):
        frustration += 1

(The regex matches Japanese phrases like "how many times do I have to say this," "give me a break," "liar," "why isn't this fixed yet," and so on; the # ← ここが肝 comment marks the crucial line.)

Only blocks with type=user that are not isMeta are examined — in other words, only messages a human actually typed. Why that matters is the next section.

The false-positive incident of 2026-07-12

The first implementation looked like this.

# 旧: 素朴なgrep
stopspam=$(echo "$files" | xargs grep -h -c 'self_audit_stop' 2>/dev/null | awk '{s+=$1} END{print s+0}')
frustration=$(echo "$files" | xargs grep -hE -c 'なんで治らん|いい加減' 2>/dev/null | awk '{s+=$1} END{print s+0}')

history.jsonl still holds the measured values from back then.

{"ts":"2026-07-11 22:37:28","inject_bytes":21798,"agents_loaded":48,"stopspam":6,"frustration":4,"toolerr":2}
{"ts":"2026-07-12 08:30:06","inject_bytes":21966,"agents_loaded":48,"stopspam":40,"frustration":18,"toolerr":67}
{"ts":"2026-07-12 08:40:03","inject_bytes":21966,"agents_loaded":48,"stopspam":58,"frustration":32,"toolerr":68}

The evening of 07-11 was normal (GREEN). The morning of 07-12, stopspam jumped from 6 to 40 and frustration from 4 to 18 — RED. Then claude -p attempted a fix, the independent re-measurement ran, and the numbers had climbed further, to 58/32.

The cause: grep was doing a string search over the entire JSONL. The transcripts contained:

Diffs from the repair work itself (the hook script's source landing wholesale in old_string/new_string)
Contents of files opened with the Read tool (files that happened to contain frustration words)
Echoed-back tool_results (the previous audit's output being quoted by the next session)

All of it was matching. Of the 40 stopspam hits, actual hook firings were near zero; of the 18 frustration hits, only a handful were frustration words a human had actually typed.

A naive string grep cannot be used against transcripts. Unless you first determine "which role, which block" within the JSONL, quotations, tool output, and echoes of past logs all get counted. The resolution of your measurement design determines the quality of your audit.

The fix was switching to a JSONL parser. Only text blocks with type=user and isMeta: false (messages the user actually sent) are examined, and stopspam counts only lines matching the exact fixed format the harness actually injects. That excluded quotations, tool output, and echoes of past logs entirely.

Threshold breach → self-repair → independent re-measurement

The core of the prompt passed to claude -p when things go red:

PROMPT="あなたはClaude Code環境の自己監査・自己修復エージェント。

## 検知した違反
$BREACH

## 指示
1. ~/.claude 内だけを調査・修正する（プロジェクトコード・secret・plist削除は禁止）
2. 変更は1件ずつ ${CHANGELOG} に「日時/対象/理由/戻し方」を追記
3. 修正後に必ず 'bash ~/.claude/scripts/cc-self-audit.sh --collect-only' を実行し改善を数値で確認
4. 自分で安全に直せない項目は無理せず、最後に『要人間: 理由』と1行で出力
5. 最終出力は3行以内の要約のみ"

(In English, the prompt says: "You are a self-audit / self-repair agent for the Claude Code environment. ## Detected violations: $BREACH. ## Instructions: 1. Investigate and fix only inside ~/.claude (project code, secrets, and plist deletion are forbidden). 2. For each change, append date/target/reason/how-to-revert to ${CHANGELOG}. 3. After fixing, always run bash ~/.claude/scripts/cc-self-audit.sh --collect-only and confirm improvement numerically. 4. Don't force items you can't safely fix yourself — end with a one-line 'Needs human: reason.' 5. Final output is a summary of at most 3 lines.")

The important part is instruction 3 — or rather, what happens outside it. Instead of only having claude -p re-measure itself, the harness also runs collect() independently and checks the numbers (from line 165):

# 独立再計測（自己申告は信じない）
AFTER=$(collect)
log "after: $AFTER"
echo "$AFTER" >> "$HISTORY"
STILL=$(echo "$AFTER" | breaches)

If the AI says "fixed it" but the numbers haven't improved, a 🚨 goes out. When you use a Claude-built tool to repair Claude's own environment, trusting only the self-report is how you get hurt.

What the recorded numbers show

What the current history.jsonl tells us:

inject_bytes: 21,798–21,966 B (less than half the 40,000 threshold, GREEN)
agents_loaded: 48 (under the threshold of 60, GREEN)
The 07-12 red was a false positive (after the grep fix, values returned to normal)

The first two entries are the before/after of the manual --collect-only on 07-11; entries 3–4 are the 07-12 grep misdetection and the subsequent re-measurement. Production operation as a weekly job starts from 08-30.

launchd configuration

<key>StartCalendarInterval</key><dict>
  <key>Weekday</key><integer>0</integer>  <!-- 日曜 -->
  <key>Hour</key><integer>8</integer>
  <key>Minute</key><integer>30</integer>
</dict>

(Weekday 0 with the 日曜 comment means Sunday.)

RunAtLoad is false. If the job ran immediately on registration, the first measurement would happen in the "empty" state right after launchd starts. Instead, the first baseline measurement is done by manually running --collect-only to put one line into history.jsonl before registering the job.

Pitfalls I hit

Naive grep misdetected across the entire transcript → use a JSONL parser and target only type=user && !isMeta
The self_audit_stop match for stopspam also hit quotations of the hook script itself → count only the fixed marker string the harness actually injects (exact format match)
The AI reported "fixed" but the numbers hadn't changed → re-run collect() independently of the claude -p output, append to HISTORY, and only then judge
claude not found under launchd's minimal PATH → declare PATH explicitly in the plist's EnvironmentVariables (/opt/homebrew/bin + ~/.local/bin are required)
frustration pinned at zero can look like "nothing is happening" → "zero frustration" is a good sign, but check monthly that the thresholds and regex still track the real-world word set

Summary

Degradation of a Claude Code environment (agent overload, injection bloat, hook spam, user frustration) is measured weekly across 5 metrics, and when a threshold is crossed, claude -p self-repairs
Dynamic measurement without JSONL role checks (type=user && !isMeta) is riddled with false positives — naive grep against transcripts does not work
After a self-repair, the harness re-measures independently of the AI's self-report and confirms numerical improvement before notifying
"The resolution of your measurement design determines the quality of your audit" — the 2026-07-12 incident demonstrated this with real code

Next time, I'll walk through what claude -p actually changed when this audit fired, using real entries from the change log (self-audit-changes.log).

Written by **Lily* — I ship iOS apps and automate my content stack with Claude Code.
Follow along: Portfolio · X · GitHub*

Parse transcript.jsonl Directly to See What's Actually Being Called

Lily — Thu, 23 Jul 2026 11:00:05 +0000

Claude Code's /usage tells you how much you're spending, but not what you're spending it on. In my previous post, "Logging Agent invocations to a file and piping them to Slack," I wrote about recording tool calls. This time is a follow-up: a script that parses the already-recorded transcript.jsonl directly and tallies how many times each Skill, each Agent, and each MCP server was called.

Claude Code's /usage shows cost ($) and remaining quota, but it can't show you "which Skill did I use most this week" or "which Agent is the heaviest." Every tool_use block is preserved in transcript.jsonl, so by reading it directly you can surface usage at a layer /usage never tells you about.

The problem: /usage only shows cost

What /usage reports is the consumption rate for 5-hour and 7-day blocks, plus per-session token counts. It does not give you a per-item breakdown like "this AutoTrigger Skill was actually called 20 times this week" or "the general-purpose Agent accounts for half of all Agent calls."

To do cost optimization or check the health of your environment, you need the line items for "what are the tokens being spent on." transcript.jsonl is the ideal source for this, and every session is accumulated under ~/.claude/projects/.

The structure of transcript.jsonl

Each file is JSONL, one record per line. Each turn Claude Code sent or received becomes one record.

{
  "type": "assistant",
  "uuid": "...",
  "timestamp": "...",
  "sessionId": "...",
  "message": {
    "model": "claude-sonnet-4-6",
    "role": "assistant",
    "content": [
      {
        "type": "tool_use",
        "id": "toolu_01M5Rw...",
        "name": "Read",
        "input": { "file_path": "~/..." },
        "caller": { "type": "direct" }
      }
    ],
    "usage": { "input_tokens": 12043, "output_tokens": 421 }
  }
}

All you need for the tally is the type == "tool_use" blocks inside message.content[]. The name field is the tool name, and input holds the arguments.

Tool	Tally key	Extracted from
`Skill`	`input.skill`	Skill name (also namespace-split for the `plugin:name` form)
`Agent`	`input.subagent_type`	Subagent type
`mcp__*`	2nd segment of `name`	MCP server name (`mcp__<server>__<tool>`)

The heart of the script

~/.claude/scripts/usage-breakdown.sh embeds Python via a Bash heredoc. Bash receives the directory and the window period, and Python does a full scan of the files.

#!/usr/bin/env bash
ARG="${1:-7d}"
TR_DIR="$HOME/.claude/projects/-Users-matsubara"
[ -d "$TR_DIR" ] || { echo "(no transcript dir)"; exit 0; }

python3 - "$TR_DIR" "$ARG" <<'PY'
import sys, json, datetime, glob, collections, os
tr_dir, arg = sys.argv[1], sys.argv[2]
SHORT = arg == "--short"

The window period is filtered by the file's mtime. When the --short flag comes in, the parsing is all the same; only the output is narrowed down to a single line.

The parsing itself is simple:

for path in glob.glob(f"{tr_dir}/*.jsonl"):
    mtime = os.path.getmtime(path)
    if mtime < cutoff_ts: continue
    with open(path, "r", encoding="utf-8", errors="replace") as f:
        for line in f:
            rec = json.loads(line)
            msg = rec.get("message", {}) if isinstance(rec.get("message"), dict) else {}
            content = msg.get("content") if isinstance(msg, dict) else None
            if not isinstance(content, list): continue
            for block in content:
                if block.get("type") != "tool_use": continue
                name = block.get("name", "")
                inp = block.get("input") or {}
                tool_calls[name] += 1
                if name == "Skill":
                    skill_name = inp.get("skill", "?")
                    skill_calls[skill_name] += 1
                elif name == "Agent":
                    agent_calls[inp.get("subagent_type", "?")] += 1
                elif name.startswith("mcp__"):
                    parts = name.split("__")
                    if len(parts) >= 2:
                        mcp_calls[parts[1]] += 1

For the plugin:name form of Skill (e.g. hookify:configure), I also split on : and tally the namespace separately. This lets me see which plugin package is heavy on a different axis from the individual skill names.

Running it for real

Running it for the last 7 days looks like this.

$ usage-breakdown.sh 7d
=== usage breakdown (last 7d, 51 transcripts) ===

total tool_use: 4230

--- top tools ---
   2583  Bash
    567  Read
    402  Edit
    151  Write
    103  mcp__claude-in-chrome__computer
     73  mcp__claude-in-chrome__javascript_tool
     62  TaskUpdate
     50  ToolSearch
     42  mcp__claude-in-chrome__navigate
     36  TaskCreate

--- top skills (2 unique) ---
      1  harness-audit
      1  superpowers:brainstorming

--- top agents (5 unique) ---
     20  general-purpose
      7  Explore
      4  ?
      2  reviewer
      1  fork

--- top MCP servers (4 unique) ---
    261  claude-in-chrome
      3  claude_ai_Google_Calendar
      3  computer-use
      2  claude_ai_Gmail

--- top plugin namespaces (1 unique) ---
      1  superpowers

This week had 51 sessions and 4,230 tool_use calls, with Bash accounting for 61% of the total (2,583 calls). For MCP, claude-in-chrome was in a league of its own at 261 calls. For Agents, general-purpose was the most frequent at 20, with Explore at 7.

The reason there are only 2 Skill calls total is that this week I had a lot of setups where Skills fire via AutoTrigger (keyword matching in CLAUDE.md) rather than being invoked manually. AutoTrigger should show up in the transcript as Skill tool_use, so the low count is honestly reflected.

:::message
There are 4 Agents where subagent_type comes out as "?". These are calls that didn't specify subagent_type on the Agent tool (effectively the default general-purpose), which the script falls back to via inp.get("subagent_type", "?"). In practice, when "?" starts increasing, narrowing down "which Session" is useful for discovering missing subagent specifications.
:::

The --short mode for embedding in the status line

--short outputs a one-line summary.

$ usage-breakdown.sh --short
4235 tool_use across 51 sessions (7d)

I've built it into a custom script for Claude Code's status line. Placing it alongside the cost quota (the output of the previous post's token-budget-advisor.sh) puts you in a state where "usage and remaining quota are visible at a glance."

# an example statusline hook
BUDGET=$(~/.claude/scripts/token-budget-advisor.sh --short)
USAGE=$(~/.claude/scripts/usage-breakdown.sh --short)
echo "💰 $BUDGET | 🔧 $USAGE"

Pitfalls I hit

The mtime filter is file-granular, so it's coarse — when a session spans multiple days, older turns get included in the tally as part of a "recent file." To be strict you'd need line-level filtering via rec.get("timestamp"), but for grasping trends, mtime was good enough.
It doesn't pick up JSONL in subdirectories — glob.glob(f"{tr_dir}/*.jsonl") only looks one flat level. Subagent transcripts go under <session-uuid>/subagents/agent-*.jsonl, so they're outside the tally in the current implementation. Switching to **/*.jsonl would pick them up, but it's heavy, so I've left it out intentionally.
Long MCP tool names like mcp__claude-in-chrome__computer — since the implementation takes the 2nd segment of split("__"), only parts[1] remains and the server name is extracted correctly. However, in cases where the server name itself contains __, it will be misextracted (haven't run into it so far).
The 30d window takes several minutes — because it full-scans over 890 files, using 7d or --short for daily use and only reaching for 30d when digging deep is the realistic approach.

Summary

If you pick up just the message.content[].type == "tool_use" from transcript.jsonl, you can get the call counts for Skills, Agents, and MCP servers
Just outputting most_common(10) from a Python counter immediately shows you the "heavy items"
The mtime period filter and the embedded Python heredoc fit it all into a single Bash script
Making it a one-line summary with --short and always displaying it in the status line lets you monitor the health of your environment on an axis separate from cost

Look at cost with /usage, and look at the per-item breakdown with this script. Combining the two raises the resolution of "how many tokens were spent for what."

Written by **Lily* — I ship iOS apps and automate my content stack with Claude Code.
Follow along: Portfolio · X · GitHub*

Log Every Agent Invocation: Building Usage Analytics with Claude Code's Stop Hook and transcript_path

Lily — Thu, 23 Jul 2026 05:00:06 +0000

In the previous post in my "Claude Code environment" series, automatically pruning zombie agents, I wrote about finding agents that are defined but never used. But where did those numbers come from in the first place? This post covers exactly that: a mechanism that reads the transcript_path included in the Stop hook payload with Python and automatically accumulates agent invocations into a JSONL log.

Right now, ~/.claude/logs/agent-invocations.jsonl holds 553 recorded invocations. Over the last 7 days, general-purpose was called 58 times and Explore 24 times. And the fact that 47 agents were never called even once — that was invisible without this mechanism.

The problem: "Am I actually using this agent?"

As agent definitions pile up under ~/.claude/agents/, you lose track of "when did I last use this?" — even though you wrote them yourself. Unused definitions are actively harmful: they only add to context injection.

Claude Code has a mechanism that fires a Stop hook when a session ends, and its payload includes transcript_path. This is the path to the log file for the entire conversation. If you read it, you can extract everything: which agent was called, when, and how long it took.

The overall flow

Session ends → Stop hook fires → stop_hooks_combined.sh receives the payload → passes it to stop_agent_tracker.sh → Python reads the transcript and appends to the JSONL.

Here is how the actual ~/.local/bin/stop_hooks_combined.sh is wired up.

# stdin → tmpfile に保存して複数 hook へ順次渡す
cat > "$PAYLOAD"

for hook in \
  "$HOME/.claude/hooks/stop_notify.sh" \
  "$HOME/.claude/hooks/stop_cost_log.sh" \
  "$HOME/.claude/hooks/stop_agent_tracker.sh" \
  "$HOME/.claude/hooks/stop_session_summary.sh" \
  "$HOME/.discord/stop_post_session.sh"
do
  [ -x "$hook" ] && "$hook" < "$PAYLOAD" || true
done

The Stop hook receives its payload on stdin. To fan it out to multiple hooks, the payload goes through a tmpfile, and each hook gets it via a < "$PAYLOAD" redirect.

Implementing `stop_agent_tracker.sh`

The script has two layers: a bash wrapper and inline Python.

#!/usr/bin/env bash
set -uo pipefail

LOG_DIR="$HOME/.claude/logs"
OUT_LOG="$LOG_DIR/agent-invocations.jsonl"

INPUT=$(cat)
export STOP_INPUT="$INPUT"
export OUT_LOG_PATH="$OUT_LOG"

python3 - <<'PY'
# ...
PY

The bash side just reads stdin and sets environment variables. All the actual work is delegated to Python.

Pass 1: scan the entire transcript and build an index

uses = {}    # tool_use_id -> (ts, name, input, caller)
results = {} # tool_use_id -> (ts, is_error)

with open(tp, "r", encoding="utf-8", errors="replace") as f:
    for line in f:
        rec = json.loads(line)
        content = rec.get("message", {}).get("content")
        if not isinstance(content, list):
            continue
        for b in content:
            btype = b.get("type")
            if btype == "tool_use" and b.get("name") == "Agent":
                inp = b.get("input") or {}
                if "subagent_type" not in inp:
                    continue
                uid = b.get("id")
                uses[uid] = (rec.get("timestamp"), b.get("name"), inp, b.get("caller"))
            elif btype == "tool_result":
                rid = b.get("tool_use_id")
                if rid:
                    results[rid] = (rec.get("timestamp"), bool(b.get("is_error")))

The key point is filtering on name == "Agent". In Claude Code transcripts, the Task tool is also recorded as name: "Agent". Only entries with subagent_type in input are what we want — this distinguishes them from plain claude calls.

Deduplication: skip already-recorded entries by session_id × tool_use_id

A Stop hook can fire multiple times within the same session (/clear, long sessions). To record without duplicates, the script sweeps the existing log before writing.

seen_ids = set()
if os.path.exists(out_path):
    with open(out_path, "r", encoding="utf-8", errors="replace") as f:
        for line in f:
            r = json.loads(line)
            # 同一セッション内の同一 tool_use_id だけをスキップ
            if r.get("session_id") == sid and r.get("tool_use_id"):
                seen_ids.add(r["tool_use_id"])

The combination of session_id and tool_use_id is the uniqueness key. If you deduplicate on tool_use_id alone, records get silently dropped when IDs happen to collide across different sessions.

Computing duration_ms

The difference between the timestamp of the tool_use record and the timestamp of its matching tool_result is the agent's execution time.

def parse_ts(s):
    if not s:
        return None
    return datetime.datetime.fromisoformat(s.replace("Z", "+00:00"))

t0 = parse_ts(use_ts)
t1 = parse_ts(res_ts)
if t0 and t1:
    duration_ms = int((t1 - t0).total_seconds() * 1000)

If the tool_result hasn't arrived yet (e.g. the session was interrupted), the record is written with status: "pending" and duration_ms: null.

Output record format

{
  "ts": "2026-05-28T16:27:41.766Z",
  "session_id": "sess_xxx",
  "cwd": "~",
  "tool_use_id": "toolu_014MMSdJubC215oLCxfcrjok",
  "subagent_type": "general-purpose",
  "description": "launchd + cron 総監査",
  "duration_ms": 177,
  "status": "ok",
  "caller": {"type": "direct"}
}

The description field is clipped at 300 characters. In the transcript it's free-form text, so it occasionally gets enormous.

Aggregating with `agent-usage-summary.sh`

The accumulated JSONL is aggregated by ~/.claude/scripts/agent-usage-summary.sh.

agent-usage-summary.sh           # デフォルト 7d
agent-usage-summary.sh 30d       # 30日
agent-usage-summary.sh 7d 30d    # 両ウィンドウ同時

Running it produces this (actual numbers from today).

=== Agent usage (last 7d) ===
total invocations: 86  unique types: 4

Top 10:
  agent                                     calls  errors
  general-purpose                              58       0
  Explore                                      24       0
  fork                                          2       0
  reviewer                                      2       0

0-call agents (defined locally but not used in 7d): 47
  - INDEX
  - a11y-architect
  - architect
  - build-error-resolver
  - code-architect
  ...

general-purpose at 58 calls, Explore at 24. These two types account for 95% of all invocations over 7 days. And 47 agents were never called at all. This is the input data for zombie-agent pruning.

~/.claude/scripts/dashboard.sh folds this output into dashboard.md every day for always-on visibility.

echo "## 🤖 Agent 呼び出し (7d)"
AGENT_OUT=$(~/.claude/scripts/agent-usage-summary.sh 7d 2>/dev/null)
TOP_BLOCK=$(echo "$AGENT_OUT" | awk '
  /^Top 10:/ { in_block=1; next }
  /^$/ && in_block { exit }
  in_block { print }
' | head -5)
echo "$TOP_BLOCK"

Note: Agents defined as *.md files under ~/.claude/agents/ are treated as "known agents," and any that never appear in the log are listed as "0-call." Non-agent files like INDEX.md slip in too, so in practice INDEX shows up at the top of the 0-call list every time. If that bothers you, filter it out with something like .startswith("INDEX") before building known_agents.

Dashboard integration in `dashboard.sh`

dashboard.sh writes the agent summary out to ~/.claude/dashboard.md alongside health status, auto-skills counts, and the launchd job list. Updated daily via cron, it lets you check every morning which agents are pulling their weight this week.

Pitfalls I hit

The Stop hook's stdin can only be read once → stop_hooks_combined.sh was designed to write a tmpfile first and then redirect it into each hook. My first attempt had each hook cat stdin directly, and every hook after the first got nothing.
mktemp fails when TMPDIR is broken → added a fallback in stop_hooks_combined.sh: || PAYLOAD="/tmp/stop-hook.$$.$RANDOM.json". If you redirect to an empty path, every hook silently becomes a no-op.
Deduplicating on tool_use_id alone loses records on cross-session collisions → fixed by keying on the session_id × tool_use_id pair.
Searching for name == "Task" returns nothing → in Claude Code transcripts, the Task tool is recorded as name: "Agent". This isn't documented anywhere; I found it by grepping the actual files.
description can grow to thousands of characters → without clipping at 300 characters, the JSONL bloated and json.loads got slow in later aggregation.
The Stop hook can fire before the tool_result arrives → e.g. when a session is force-killed. Recording it with status: "pending" and duration_ms: null lets aggregation queries exclude it with an is not null filter.

Summary

The Stop hook payload includes transcript_path, which means the entire conversation's tool call history is readable
Lines with name == "Agent" and an input.subagent_type are agent invocations
Deduplicate on session_id × tool_use_id to handle multiple firings within the same session
duration_ms is the timestamp delta between tool_use and tool_result
The 0-call section of agent-usage-summary.sh is a detector for "agents you defined but never use"

Next up: the mechanism that automatically retires those unused agents surfaced by this aggregation — the design behind automatically pruning zombie agents (already published).

Written by **Lily* — I ship iOS apps and automate my content stack with Claude Code.
Follow along: Portfolio · X · GitHub*

Hunting Down Zombie Agents: Logging Subagent Usage with a Claude Code Stop Hook

Lily — Thu, 23 Jul 2026 00:00:06 +0000

Quick question: how many of the subagents you've defined in ~/.claude/agents/ have actually been called this month? I couldn't have told you — until I started measuring, and this morning's tally revealed 44 agents that hadn't been invoked even once in 30 days. This post is part of my "Claude Code environment" series (a follow-up to automatic terminal window tiling), continuing the theme of keeping the setup from bloating. I'll walk through, with real code, a system that records subagent invocations to JSONL via a Stop hook and uses a daily report to flush out the zombies and cull them.

The problem: the gap between "defined" and "used"

Adding an agent to Claude Code is as simple as writing frontmatter in .claude/agents/*.md. Because it's so easy, "let's just define it for now" agents pile up. The problem is that there's no way to check whether an agent is actually being used.

There's no mechanism to aggregate invocation counts across sessions
A hand-written INDEX.md goes stale immediately
There's no evidence to base a "can I delete this?" decision on

An agent with zero usage still takes up space in the context injected at startup. Left alone, it becomes a zombie: defined but unused → unclear whether it even works → can't be deleted either.

The overall flow

The system consists of three components.

セッション終了
  └─ Stop hook (stop_agent_tracker.sh)
       └─ transcript.jsonl を解析 → agent-invocations.jsonl に追記
                                              │
                     毎日 10:15 launchd ──────┘
                       └─ agent-usage-summary.sh 7d 30d
                            └─ agent-usage-latest.md（Top10 + 0回リスト）

  手動 or cron
   └─ agents-index.sh → INDEX.md 自動再生成

Step 1: Record to JSONL with a Stop hook

~/.claude/hooks/stop_agent_tracker.sh runs when a session ends. The Stop hook receives session info and a transcript_path on stdin, so the script parses that transcript and picks out Agent tool invocations.

# stop_agent_tracker.sh（抜粋）
# stdin: {"session_id":"...","transcript_path":"...","hook_event_name":"Stop",...}
# 出力:  ~/.claude/logs/agent-invocations.jsonl

OUT_LOG="$LOG_DIR/agent-invocations.jsonl"

The heart of the Python portion is a two-pass parse of the transcript.

# 第1パス: tool_use (name="Agent") と tool_result をインデックス化
uses = {}    # id -> (ts, name, input, caller)
results = {} # tool_use_id -> (ts, is_error)

for b in content:
    if btype == "tool_use" and b.get("name") == "Agent":
        inp = b.get("input") or {}
        if "subagent_type" not in inp:
            continue
        uses[uid] = (ts, b.get("name"), inp, b.get("caller"))
    elif btype == "tool_result":
        results[rid] = (ts, bool(b.get("is_error")))

Note: In Claude Code transcripts, the "Task" tool is recorded as name="Agent". The subagent_type lives in input.subagent_type. The same comment appears in the code itself.

To prevent duplicates, the same session_id + tool_use_id combination is skipped (so even if the Stop hook fires multiple times in one session, nothing gets written twice).

A single JSONL record looks like this.

{"ts": "2026-05-28T16:27:41.766Z", "session_id": "TEST-AGENT-TRACKER-001",
 "cwd": "~", "tool_use_id": "toolu_014MM...", "subagent_type": "general-purpose",
 "description": "launchd + cron 総監査", "duration_ms": 177, "status": "ok",
 "caller": {"type": "direct"}}

So far, 546 records (about 176 KB) have accumulated.

Step 2: Produce a Top 10 and zero-call list over 7d/30d windows

~/.claude/scripts/agent-usage-summary.sh handles the aggregation. It's inline python3 with no external libraries.

# 使い方
agent-usage-summary.sh           # デフォルト 7d
agent-usage-summary.sh 30d       # 30日
agent-usage-summary.sh 7d 30d    # 両方（launchdはこれ）

Internally it's three steps.

# ① JOSNLをロードしてウィンドウでフィルタ
cutoff = now - td
recent = [r for r in records if r["_dt"] >= cutoff]

# ② subagent_type でカウント + エラー数
counts = Counter(r.get("subagent_type", "") for r in recent if r.get("subagent_type"))
errors = Counter(r.get("subagent_type", "") for r in recent if r.get("status") == "error")

# ③ ~/.claude/agents/*.md のファイル名一覧と突き合わせて未使用を出す
known_agents = set()
for fp in glob.glob(os.path.join(agents_dir, "*.md")):
    known_agents.add(os.path.splitext(os.path.basename(fp))[0])

unused = sorted(known_agents - set(counts.keys()))

Here's this morning's actual output (~/.claude/logs/agent-usage-latest.md).

=== Agent usage (last 7d) ===
total invocations: 127  unique types: 5

Top 10:
  agent                                     calls  errors
  general-purpose                              76       0
  Explore                                      45       0
  Content Creator                               2       0
  fork                                          2       0
  reviewer                                      2       0

0-call agents (defined locally but not used in 7d): 47
  - a11y-architect
  - architect
  - build-error-resolver
  - code-architect
  - code-explorer
  - code-reviewer
  ...

In 7 days, only 5 agent types were called and 47 weren't called at all. Even in the 30-day window, 44 remain at zero. general-purpose and Explore account for 95% of all invocations.

Step 3: Auto-regenerate INDEX.md with agents-index.sh

To decide whether something can be deleted, you need a cross-cutting view of what each agent was written for. agents-index.sh reads the frontmatter of ~/.claude/agents/*.md and builds INDEX.md.

# 簡易frontmatterパーサ（PyYAML依存なし）
m = re.match(r"^---\n(.*?)\n---\n", text, flags=re.DOTALL)
body = m.group(1)
for line in body.split("\n"):
    k, _, v = line.partition(":")
    out[k.strip()] = v.strip()

The generated INDEX.md is a table like this.

<!-- AUTO-GENERATED by ~/.claude/scripts/agents-index.sh — DO NOT EDIT MANUALLY -->
# Agents Index (51 agents · 2026-07-14 10:15)

| Name | Model | Description | Tools |
|------|-------|-------------|-------|
| `general-purpose` (general-purpose.md) | - | General-purpose agent for... | * |
...

With the --json flag it also writes out .index.json, which can be reused programmatically by things like a cost tracker.

Files missing name or description in their frontmatter get listed under a ⚠️ Validation warnings section.

Step 4: Generate the daily report with launchd

~/Library/LaunchAgents/com.shun.agent-usage-daily.plist runs every day at 10:15.

<key>StartCalendarInterval</key>
<dict>
    <key>Hour</key>
    <integer>10</integer>
    <key>Minute</key>
    <integer>15</integer>
</dict>

The command it runs is simple.

<string>/bin/zsh -c
  ~/.claude/scripts/agent-usage-summary.sh 7d 30d
  > ~/.claude/logs/agent-usage-latest.md 2>&1</string>

The PATH explicitly includes nvm and Homebrew because launchd's default PATH won't find python3.

With this in place, agent-usage-latest.md gets refreshed every morning at 10:15, so I always know how many agents have sat at zero for 30 days.

The operating routine: cull the zombies

Once a week, I run these commands.

# INDEX再生成（frontmatter変更・追加後に必ず走らせる）
~/.claude/scripts/agents-index.sh

# 0回リスト確認
cat ~/.claude/logs/agent-usage-latest.md | grep -A 9999 "0-call agents"

My decision criteria look like this.

State	Action
0 calls in 30d, and reading the description reveals no realistic use case	Delete
0 calls in 30d, but there's a future use case	Keep, and spell out the usage conditions in the description
0 calls in 7d, a few calls in 30d	Possibly a seasonal job — hold off
Top 5 regular	Revisit its permissions and tool definitions to sharpen it further

In this round of housekeeping I deleted 14 agents confirmed at zero calls over 30 days, including a11y-architect, django-reviewer, and go-build-resolver. They simply disappear from INDEX.md — nothing else changes.

Pitfalls I hit

Filtering on name="Task" matched nothing → In Claude Code transcripts, Task invocations are recorded as name="Agent". At first every record came back empty because of this
The Stop hook fired multiple times in one session, causing double writes → Fixed by adding a seen_ids duplicate check on (session_id, tool_use_id)
Records with an empty-string subagent_type crept in → Filter with if r.get("subagent_type") (the empty string being falsy is enough)
agents-index.sh parsed INDEX.md itself, creating a loop → Excluded with if p.name == "INDEX.md": continue
launchd's minimal PATH couldn't find python3 → Explicitly set the nvm and Homebrew paths in the plist's EnvironmentVariables
Agents at zero in the 30d window looked "nonexistent" in the 7d window → known_agents is built from the file listing of agents_dir, so it doesn't depend on the window. This is the correct behavior

Wrap-up

The Stop hook appends to JSONL keyed by session_id + tool_use_id → invocation history accumulates across sessions
agent-usage-summary.sh outputs a Top 10 and a zero-call agent list over 7d/30d windows. Since it cross-references the filenames in ~/.claude/agents/*.md, any newly added agent is automatically tracked
agents-index.sh auto-regenerates INDEX.md from frontmatter. A hand-written index goes stale immediately, so this replaces it
launchd runs the aggregation daily at 10:15 and writes to agent-usage-latest.md, so "how many zombies do I have as of today?" is always answerable
Agents confirmed at zero calls over 30 days get deleted. When the case for deletion comes from numbers, there's no second-guessing

Next time, I'll use this log data to visualize which agents get combined for which kinds of work.

Written by **Lily* — I ship iOS apps and automate my content stack with Claude Code.
Follow along: Portfolio · X · GitHub*

Snap 8 Windows into a Grid on an Ultrawide in One Command — a Swift + AppleScript Convergence Loop and 5 Traps

Lily — Wed, 22 Jul 2026 11:00:48 +0000

This is part of my "Claude Code environment" series. Last time, in The Environment-Degradation Sentinel, I wrote about self-diagnosing a Claude Code environment. This time it's a different kind of workflow cost.

Picture eight Terminal.app windows scattered across an ultrawide monitor. A single command snaps them into a 4×2 grid. It looks like "just line up windows with osascript," but there are traps across three layers: coordinate-system conversion, AppleScript's asynchronous behavior, and macOS's row rounding. In this article I'll explain the two design cores and the five traps I hit during implementation, with real code.

The problem: dragging windows into place cost me a minute

When I line up multiple Claude Code sessions on a 3440×1440 ultrawide, the windows open in random positions every time. Fullscreen split isn't enough. Mission Control can't pin positions. In the end I was spending a minute every morning dragging all eight windows by mouse into a 4×2 arrangement.

Writing the position and size directly in AppleScript should have been the end of it. But once I actually started writing, three things became clear:

There are two coordinate systems (Cocoa's Y-up and screen coordinates' Y-down)
set position gets silently ignored in some situations
The window's height doesn't end up at the value I specified

I'll walk through the design of a script that solves all of these together (~/.claude/scripts/terminal-grid8.sh).

Design core ①: Convert visibleFrame to global coordinates in Swift and hand it to the shell

AppleScript's position of window returns global coordinates (top-left origin, Y-down). Meanwhile macOS's NSScreen.visibleFrame uses the Cocoa coordinate system (Y-up). Mixing the two makes the math go wrong. I do the conversion all at once in Swift and hand it off via the shell variables GX GY GW GH.

GEOM=$(swift - <<'EOF'
import AppKit
let screens = NSScreen.screens
guard let main = screens.first else { exit(1) }
// 最も横長の画面を対象にする(ウルトラワイド)。同率ならメイン以外を優先
let target = screens.max(by: { $0.frame.width < $1.frame.width })!
let v = target.visibleFrame   // Dock除外(Cocoa座標: 左下原点Y上向き)
let mainH = main.frame.height
var topY = mainH - (v.origin.y + v.height)  // グローバル(左上原点)座標へ変換
var h = v.height
// visibleFrameがメニューバーを反映しない画面がある → 手動で差し引く
if v.height == target.frame.height {
    topY += 30
    h -= 30
}
print("\(Int(v.origin.x)) \(Int(topY)) \(Int(v.width)) \(Int(h))")
EOF
)
read -r GX GY GW GH <<< "$GEOM"

The key is the conversion formula mainH - (v.origin.y + v.height). Cocoa's visibleFrame.origin.y is the distance from the bottom edge of the main screen (Y-up), so to turn it into a global "distance from the top-left (Y-down)," you subtract from the height of the main screen.

The if v.height == target.frame.height branch is a fallback that emerged from real measurement. On non-main screens, visibleFrame can return the same value as the frame without subtracting the 30px menu bar. In that case I subtract it manually on the Swift side (trap ④, below).

The cell dimensions are a simple integer division.

CW=$(( GW / COLS ))   # 列幅
CH=$(( GH / ROWS ))   # 行高

Design core ②: AppleScript's convergence loop

The backbone of the convergence loop is that it re-scans indexes on every pass — not by name, not by ID.

-- 収束ループ: 毎パス再スキャンして未配置の窓を1枚だけ動かす
repeat with pass from 1 to (nCells * 3)
  set occupied to {}
  repeat nCells times
    set end of occupied to false
  end repeat
  set moverIdx to 0
  set n to count windows

  -- 1) 対象画面上の窓を走査し、セル一致済みをマーク・最初の未配置窓を記録
  repeat with i from 1 to n
    try
      set p to position of window i
      set px to item 1 of p
      set py to item 2 of p
    on error
      set px to -99999
      set py to -99999
    end try
    if px ≥ (gx - tol) and px < (gx + nCols * cw) and
       py ≥ (gy - tol) and py < (gy + nRows * ch) then
      -- セル一致判定 ...（tol=40px の誤差許容）
      if (not matched) and moverIdx = 0 then set moverIdx to i
    end if
  end repeat

  -- 2) 未配置窓が無ければ収束
  if moverIdx = 0 then exit repeat

  -- 3) 最初の空きセルへ移動 (size→delay→position→delay→size、delay 必須)
  set size of window moverIdx to {cw, ch}
  delay 0.2
  set position of window moverIdx to {tx, ty}
  delay 0.2
  set size of window moverIdx to {cw, ch}
  delay 0.2
  -- 読み返して position を最終補正(リサイズでのドリフト対策)
  set p2 to position of window moverIdx
  if (item 1 of p2) is not tx or (item 2 of p2) is not ty then
    set position of window moverIdx to {tx, ty}
    delay 0.2
  end if
end repeat

There are two reasons I designed this as "move exactly one window and re-scan as long as any remain unplaced," rather than "move all the windows at once with a forEach":

Name references don't work (trap ①), so you can't hold an object reference across passes
Moving one window changes the cells' occupancy state, so you have to redo the scan

Even in the worst case (all 8 windows are out of place), nCells * 3 = 24 passes are enough to converge.

:::message
If you drop delay 0.2, set position is silently ignored (trap ②). AppleScript doesn't throw an error either. You need the five steps size → delay → position → delay → size, plus the fallback that reads back and re-corrects.
:::

After the convergence loop, there's a normalization pass that unifies the bottom row's y by actual height.

-- 最下段yの正規化: 行丸めでセル高を超える実高のクランプ揺れ対策
set bottomEdge to gy + nRows * ch
set lastRowTop to gy + (nRows - 1) * ch
repeat with i from 1 to (count windows)
  try
    set p to position of window i
    -- 最下段の窓だけを対象に実高で下端揃え
    if py ≥ (lastRowTop - tol) and py < bottomEdge then
      set s to size of window i
      set wh to item 2 of s    -- 実際のピクセル高
      set targetY to bottomEdge - wh
      if py is not targetY then
        set position of window i to {bestX, targetY}
        delay 0.2
      end if
    end if
  end try
end repeat

The traps I hit

① Window name references break down while the spinner is rotating

Terminal.app replaces the title with spinner characters (⠐⠂✳) while a tab is loading. If you reference a window by name right after a session starts, you get -1728 (object not found). Stop referencing by name; operate directly by the window i index on every pass.

② A `position` set right after `size` is ignored without a delay

If you put set position of window i to {tx, ty} right after a resize, the coordinate change arrives before macOS's window server has finished the previous resize, and it gets dropped. Put delay 0.2 in two places (after size and after position), then read back and correct.

③ Terminal's row-height rounding keeps the cell height off the specified value

Terminal.app rounds a window's height to "rows × row height." For example, even if you specify a cell height of 705px, the actual value becomes 44 rows × 16px = 704px, or 45 rows × 16px = 720px. This error, combined with macOS's boundary clamping, shifts the bottom row's windows by a few px and makes the cell-match check fail. Run a "bottom-edge alignment by actual height" normalization pass after the convergence loop to absorb it.

④ visibleFrame sometimes doesn't subtract the menu bar

On non-main screens, NSScreen.visibleFrame can return the same value as NSScreen.frame (observed in practice). In that case the computed top edge of the grid overlaps the menu bar. On the Swift side, apply topY += 30 / h -= 30 manually, conditioned on v.height == target.frame.height.

if v.height == target.frame.height {
    topY += 30
    h -= 30
}

⑤ Transient errors (-10006 / -1728) recover naturally on retry

While a window is initializing or its name is changing, you get -10006 (invalid index) or -1728. If you insert delay 0.3 in an on error and fall through to the next pass, the convergence loop re-scans that same window on the following pass and picks it up. The key is not to abort immediately on an error.

on error
  delay 0.3 -- 過渡エラーは次パスで再試行
end try

Usage and verification

~/.claude/scripts/terminal-grid8.sh

One command aligns Terminal.app's 8 windows. You can change the number of divisions with just the two lines at the top.

COLS=4
ROWS=2

If you want 6 divisions, rewrite it to COLS=3 ROWS=2.

The final report prints each window's x,y WxH title. On a 3440-wide screen, success means x converges to the four values 0/860/1720/2580, and y converges to one value each for the top and bottom rows.

Wrap-up

Cocoa Y-up → global Y-down conversion is handled by the single Swift line mainH - (v.origin.y + v.height) and handed to the shell
AppleScript's convergence loop repeats "move one window and re-scan" instead of a foreach. Drop name references and operate by index on every pass
If you omit delay 0.2, set position is silently ignored
The y drift from Terminal's row-height rounding is normalized by a post-convergence "bottom-edge alignment by actual height" pass
Because some screens don't reflect the menu bar in visibleFrame, add a manual 30px correction conditioned on height == frame.height

Next time, I'll write about an environment-alignment hook that fires on Claude Code startup using this script as a trigger — placing Terminal windows, the status line, and Obsidian into fixed positions all at once from launchd.

Written by **Lily* — I ship iOS apps and automate my content stack with Claude Code.
Follow along: Portfolio · X · GitHub*

Your Claude Code Setup Gets Bloated If You Ignore It — Weekly Auto-Slimming by Watching Injected Bytes, Agent Count, and Frustration Words

Lily — Wed, 22 Jul 2026 05:00:07 +0000

This is the next installment in my "Claude Code environment" series. Combined with the idempotent marker implementation from the previous article, I've come to realize that more than half of the reasons an autonomous loop won't stop come down to one thing: environment decay.

A Claude Code setup gets fat if you leave it alone. The rules balloon, agents you thought you'd retired come back to life, and hooks keep misfiring. The only thing you actually notice is a vague "this feels sluggish" or "it keeps making the same mistake," and then you burn time hunting down the cause. This article is about a system that measures that decay every week, lets claude -p fix it, and then confirms the improvement with an independent re-measurement after the fix.

The problem: 99 "retired" agents were still being injected

This is a real incident I hit during a performance audit on 2026-07-11.

I'd tidied up ~/.claude/agents/ several times. I'd manually moved agent definitions I no longer used into agents-archive/ and figured I was done. But when I actually measured, agents_loaded was still stuck at 99. The culprit was dot-directories (.deprecated/, .backup/, and the like). find's default behavior recurses into dot-directories too. They looked deleted, but every single one was still being loaded through the hidden directories.

This real incident is what prompted me to write cc-self-audit.sh.

Five metrics

The script's collect() function grabs five metrics every run.

# ~/.claude/scripts/cc-self-audit.sh（collect関数より）

# --- 静的 ---
inject_bytes=$(( \
  $(find "$HOME/.claude/rules" -name '*.md' -print0 2>/dev/null | xargs -0 cat 2>/dev/null | wc -c) + \
  $(cat "$HOME/.claude/CLAUDE.md" 2>/dev/null | wc -c) + \
  $(cat "$HOME/CLAUDE.md" 2>/dev/null | wc -c) + \
  $(cat "$HOME/.claude/projects/-Users-matsubara/memory/MEMORY.md" 2>/dev/null | wc -c) ))
agents_loaded=$(find "$HOME/.claude/agents" -name '*.md' 2>/dev/null | wc -l | tr -d ' ')

# --- 動的（前回実行以降のtranscriptのみ・最大200ファイル）---
stopspam=$(echo "$files" | xargs /usr/bin/grep -h -c 'セルフ監査未実施。実装' 2>/dev/null | awk '{s+=$1} END{print s+0}')
frustration=$(echo "$files" | xargs /usr/bin/grep -h -c -E '何回も言|いい加減にし|嘘つ|舐めんな|なんで治らん|最悪やろ|頭悪い' 2>/dev/null | awk '{s+=$1} END{print s+0}')
toolerr=$(echo "$files" | xargs /usr/bin/grep -h -o -c '"is_error":true' 2>/dev/null | awk '{s+=$1} END{print s+0}')

Metric	Meaning	Threshold
`inject_bytes`	Total bytes of rules + CLAUDE.md + MEMORY.md	40,000
`agents_loaded`	Total .md count under `~/.claude/agents/` (recursion including dot-dirs)	60
`stopspam`	Number of times the audit hook fired / week	15
`frustration`	Occurrences of frustration words in transcripts / week	8
`toolerr`	Count of `"is_error":true` in transcripts / week	400

The two static metrics are proxy variables for injection cost, and the three dynamic metrics are proxy variables for experience quality. The frustration-word detection may look out of place, but if I'm scolding it repeatedly, that means it's repeating the same failure — and those failures often stem from environment problems (misfiring hooks, rotted memory, broken tools).

The thresholds can be overridden with env variables.

TH_INJECT_BYTES="${SELF_AUDIT_TH_INJECT:-40000}"
TH_AGENTS="${SELF_AUDIT_TH_AGENTS:-60}"
TH_STOPSPAM="${SELF_AUDIT_TH_STOPSPAM:-15}"
TH_FRUSTRATION="${SELF_AUDIT_TH_FRUST:-8}"
TH_TOOLERR="${SELF_AUDIT_TH_TOOLERR:-400}"

When a threshold is exceeded, `claude -p` fixes itself

If every metric is under its threshold, it just posts a one-line ✅ GREEN to Discord and exits. If any is over, it calls claude -p to fix it.

BREACH=$(echo "$METRICS" | breaches)

if [ -z "$BREACH" ]; then
  log "GREEN"
  touch "$LASTRUN"
  notify "✅ CC自己監査: 正常 ($METRICS)"
  exit 0
fi

log "RED: $BREACH"
if [ "$DRY" = "1" ]; then log "DRY=1: 修正スキップ"; touch "$LASTRUN"; exit 0; fi

The prompt passed to claude -p has a remediation policy embedded for each decay pattern.

PROMPT="...
## 指示
1. ~/.claude 内だけを調査・修正する（プロジェクトコード・secret・plist削除は禁止）
2. 既知の劣化パターンと正典:
   - agents_loaded超過 → ~/.claude/agents/ 配下の退避漏れ（ドットdirも読み込まれる）を ~/.claude/agents-archive/ へ移動
   - inject_bytes超過 → 肥大したrules/MEMORY.mdを圧縮（フル版は ~/.claude/rules-archive/ へ。リンクは全維持し索引整合を検証）
   - stopspam超過 → ~/.claude/hooks/self_audit_stop.sh の抑制ロジックを点検
   - frustration/toolerr超過 → 該当transcriptをgrepして繰り返し失敗の真因を特定し、hook/スキル/メモリで再発防止を仕込む
3. 変更は1件ずつ ${CHANGELOG} に「日時/対象/理由/戻し方」を追記
4. 修正後に必ず 'bash ~/.claude/scripts/cc-self-audit.sh --collect-only' を実行し改善を数値で確認
..."

I restrict it to filesystem operations only with --allowedTools "Read,Write,Edit,Bash,Grep,Glob", and cap it at max-turns 50 and a 20-minute wall clock (FIX_TIMEOUT=1200).

Note
Having claude run --collect-only itself inside the fix loop is strictly "a confirmation as part of the remediation procedure." The final verdict of the audit is made by the outer, independent re-measurement. The key to the design is not taking the inner confirmation at face value.

A "don't trust self-reporting" fail-closed design

Even when claude -p says "fixed it," I don't believe it right away. The outer harness calls collect() again to re-measure the numbers.

# 独立再計測（自己申告は信じない）
AFTER=$(collect)
log "after: $AFTER"
echo "$AFTER" >> "$HISTORY"
STILL=$(echo "$AFTER" | breaches)
touch "$LASTRUN"

if [ -z "$STILL" ]; then
  notify "🔧 CC自己監査: 劣化検知→自己修正済み。前:[$BREACH] 後:全緑。詳細=$CHANGELOG"
else
  notify "🚨 CC自己監査: 自己修正後も残存 [$STILL]。要確認: $LOG / $CHANGELOG"
fi

If a violation still remains after the fix, it flies off to Discord with a 🚨 and hands it over to a human. Trust only the OS's measured values, not self-reporting — that's the core of fail-closed.

All measured values are stacked one record per line in ~/.claude/self-audit/history.jsonl, and the prompt handed to claude also includes the most recent 5 entries as a trend. By looking at the magnitude of change — "it was 30KB last week but 51KB this week" — I can distinguish a one-off outlier from a continuous increase.

Weekly launch via launchd, Sundays at 8:30

<!-- ~/Library/LaunchAgents/com.lily.cc-self-audit.plist -->
<key>StartCalendarInterval</key><dict>
  <key>Weekday</key><integer>0</integer>
  <key>Hour</key><integer>8</integer>
  <key>Minute</key><integer>30</integer>
</dict>
<key>RunAtLoad</key><false/>

Weekday=0 is Sunday. I set RunAtLoad to false to prevent it from running immediately right after registering with launchd. I include ~/.local/bin in the environment variable PATH and place a claude shim there.

There are two modes for manual runs.

# 計測だけ（claudeを呼ばない）
~/.claude/scripts/cc-self-audit.sh --collect-only

# ドライラン（違反表示のみ・修正なし）
SELF_AUDIT_DRY=1 ~/.claude/scripts/cc-self-audit.sh

Before putting it into production, I always eyeballed the metrics with DRY=1 first, then enabled it.

Pitfalls I hit

Dot-dirs get caught by find → ~/.claude/agents/.deprecated/ and the like became recursion targets, so agents I thought I'd retired kept getting counted. The root cause of the real incident.
The transcript find is slow → Unless you cap the number of files with head -200 and exclude empty files with -size +100k, the first run of the weekend takes over 3 minutes.
The frustration-word regex mixes in Japanese → Unless you set LANG=en_US.UTF-8 at the top, grep -E misbehaves on multibyte characters.
claude -p isn't on the PATH → launchd's minimal PATH was missing ~/.local/bin. Solved by explicitly adding it to the plist's EnvironmentVariables.
Making claude do the post-fix re-measurement internally turns it into self-grading → The outer collect() call is mandatory. The inner confirmation stays limited to "part of the remediation procedure."

Warning
As the comment says — bash 3.2 compatible, fail-open — the audit script itself is designed so that nothing breaks even if it crashes. It uses set -uo pipefail, each individual measurement swallows errors with 2>/dev/null || true, and in the worst case the measured value becomes 0 and gets treated as "GREEN." Having the main system die because of an audit failure would be putting the cart before the horse.

Summary

A Claude Code setup accumulates decay that, if left alone, can be measured across five metrics: inject_bytes, agent count, hook spam, frustration words, and tool failures
When a threshold is exceeded, claude -p fixes only what's inside ~/.claude, and records it in the change log (self-audit-changes.log) with a "how to revert" note
After the fix, an outer independent re-measurement verifies the improvement numerically. A self-reported "fixed it" alone is not treated as done
Weekly launch via launchd, Sundays at 8:30. You can manually check with --collect-only and DRY=1
The script itself is fail-open (an audit failure won't break the environment), while the target of self-repair is fail-closed (if a violation remains after the fix, it escalates to a human)

Next time, I'll write about how I trimmed down the inject_bytes overage that this audit loop detected — a pipeline that compresses the rules and auto-slims them every week.

Written by **Lily* — I ship iOS apps and automate my content stack with Claude Code.
Follow along: Portfolio · X · GitHub*

DEV Community: Lily

Auto-Generating an Index of Your Claude Code Custom Agents from Their Frontmatter

The problem: the index rots

The output: a real INDEX.md

How the script is designed

A frontmatter parser with no PyYAML dependency

Warnings for missing fields

launchd config: automatic run at 6:30 on Sundays

Pitfalls I hit

Summary

Nightly tail-truncation: how I stopped Claude Code's logs from quietly eating my disk

The problem: logrotate changes the path

The fix: keep the tail with tail, overwrite with mv

The full script

Running quietly at night with launchd

Deleting dated artifacts older than 30 days

Actual truncation records

Pitfalls I hit

Summary

My Claude Code Logs Ballooned to 22MB — Nightly Auto-Trimming with launchd

The problem: disk gets heavier every morning at startup

The design: don't delete, keep only the last 2000 lines

The log-rotate.sh implementation

The launchd configuration

How the directory size evolved

Pitfalls I hit

Summary

How Claude Code Detects Its Own Weekly Rot and Repairs Itself

The problem: environments rot quietly if you leave them alone

Five degradation metrics and their thresholds

Overall design: a three-layer loop

Layer 1: static measurement

Layer 2: dynamic measurement (the window since the last run)

Layer 3: self-repair via claude -p

"Never trust self-reporting" — independent re-measurement

launchd config (Sundays at 8:30)

Pitfalls I hit

Summary

Automating a Daily Morning Health Check for Your Claude Code Setup with launchd

The problem: checking five places by hand every morning

Overall design: 3 triggers → 1 Markdown file → append to Obsidian

Production HTTP probes: 3 retries + a 15-second timeout

Hook latency p95: aggregating JSONL with Python

launchd exit codes: every job in one line

7-day API cost by model

Walking through personal projects' git status

Idempotent design: comment markers prevent duplicate appends

The TCC trap: /usr/bin/env bash fails

plist design points

Pitfalls I hit

Summary

The Bigger Your CLAUDE.md Gets, the Slower Claude Code Runs — Measuring Context Injection Bytes Weekly to Catch Degradation Early

The problem: it gets fat while nobody's looking

What to measure

Static measurement: injection bytes and agent count

Dynamic measurement: stopspam, frustration words, tool failures

Thresholds

Breach detection → self-repair → independent re-measurement

Running it via launchd on Sundays at 8:30 AM

Integration with automation-health.sh

Pitfalls I hit

Summary

When Claude Detects "Why Isn't This Fixed Yet?" and Repairs Its Own CLAUDE.md: A Self-Improvement Loop Driven by Frustration Signals in Transcripts

The problem: nobody was detecting environment degradation

Overall design: 5 metrics × thresholds × independent re-measurement

Static metrics: injected bytes and agent count

Dynamic metrics: reading only human-typed messages out of the transcript JSONL

The false-positive incident of 2026-07-12

Threshold breach → self-repair → independent re-measurement

What the recorded numbers show

launchd configuration

Pitfalls I hit

Summary

Parse transcript.jsonl Directly to See What's Actually Being Called

The problem: /usage only shows cost

The structure of transcript.jsonl

The heart of the script

Running it for real

The --short mode for embedding in the status line

Pitfalls I hit

The fix: keep the tail with `tail`, overwrite with `mv`

The TCC trap: `/usr/bin/env bash` fails

Implementing `stop_agent_tracker.sh`

Aggregating with `agent-usage-summary.sh`

Dashboard integration in `dashboard.sh`

② A `position` set right after `size` is ignored without a delay

When a threshold is exceeded, `claude -p` fixes itself