My Cost Monitor Said $234 When the Real Bill Was $48. Then set -e Made It Go Silent for a Week.

A developer's cost-monitoring script for Claude Code silently failed twice, once overcounting weekly spend by 4-6x and once going quiet due to set -e, leading to a redesign that prioritizes fail-open behavior so the dashboard never goes silent. The 212-line bash script now displays 'n/a' on errors instead of terminating, ensuring cost anomalies remain visible.

A monitoring script that dies quietly is worse than no monitoring at all. Mine proved it twice: first it reported a 7-day spend of $234 when ccusage daily said the real number was $48 a 4–6x overcount from double-summing cumulative log lines, now down to a set -euo pipefail , a single ccusage timeout made the whole thing exit 1 and my status bar sat critical without me noticing. The fix in both cases was the same design decision: ⚫ n/a , and exit 0. This post walks through the one script — 212 lines — that runs my cost monitoring today, and the design principle behind it: never let the dashboard go quiet.I went from ¥100k/month as a university student juggling side work up to ¥600k, dropped to zero after a company-side layoff, spent six months building an autonomous Claude Code environment, and now hold ¥1.2M/month in revenue. The core of that operating base is one rule: the dashboard must never stop . This isn't really a post about dashboards. It's a post about environments. Once you start using Claude Code heavily, API cost management becomes a life-or-death issue. Even holding ¥1.2M/month in revenue, Claude Code's metered cost can blow past $3,000 in a single week if you take your eye off it. In the autonomous environment I built, launchd fires a cost-monitoring script every 30 minutes and the result is rendered into my status bar and terminal dashboard. The problem is this: if the monitoring script dies, the whole dashboard dies with it. set -euo pipefail looks robust. It gets recommended as a shell scripting best practice all the time. But the moment the 5-hour-window token calculation trips partway through, the status bar goes blank. The moment ccusage doesn't respond over the network, the launchd job terminates with an error. The moment the first automated run fires before cost-log.jsonl exists, the script dies on an exception. That's the structural problem: the happy path is all green; what breaks is the error paths and the passage of time. Design it fail-closed — meaning set -e turns every error into script termination — and the dashboard goes silent on all of those error paths. Silence looks like "no problems." That's the worst possible UI. You lose the ability to distinguish normal operation from missing data. Design it fail-open, and the error paths still display ⚫ n/a . "No data" and "healthy" look different. You glance at the dashboard and immediately know something is off. That's the crux of dashboard design. The property you need from a monitoring script isn't accuracy. It's never going quiet. When you're mass-producing personal projects as a side business, an autonomous environment running alongside AI is a productivity multiplier. But if that environment itself isn't monitored , it keeps running while broken. You blow past a $3,000 weekly threshold with the cost anomaly invisible. A fail-open monitoring script is your environment's autoimmune system. I suspect most readers stop at "I wrote a script and it runs." I did too. But once you hit the mass-production phase, "it worked at first and then broke without me noticing" happens constantly. Nothing is more harmful than broken monitoring — that's the angle here. ~/.claude/scripts/token-budget-advisor.sh is a 212-line bash script that calls Python3 internally — a mixed-language setup. The file looks long, but the structure is simple. token-budget-advisor.sh │ ├─ 前処理 set -u のみ -e は外す・fail-open方針 │ ├─ データ源① ccusage blocks --json ← 公式カウント 優先 │ │ │ └─ 取得失敗 → CC OUTPUT TOK="" のまま続行 fail-open │ ├─ データ源② $HOME/.claude/logs/cost-log.jsonl ← 自前ログ │ │ │ └─ ファイル不在 → fail open → exit 0 │ ├─ 集計 Python3 heredoc │ ├─ 5hウィンドウ: session dedup + ccusage優先マージ │ ├─ 7dウィンドウ: weekly cost集計 │ └─ 直近3d burst判定 avg 5 sess/day │ ├─ 判定 🟢 OK / 🟡 warn / 🔴 critical │ └─ 出力 ├─ --short モード → 1行 "🟢 OK 5h:XXXk tok $X.X / 7d:$XXX " └─ JSON モード → 整形済みJSONオブジェクト（全フィールド） The key point is that each layer fails open independently . If ccusage can't be read, it proceeds to the Python aggregation. If the Python aggregation comes up empty, it exits through fail open . Whichever layer breaks, the design guarantees it doesn't go silent. Lines 15–27 at the top of the script condense the entire design philosophy. set -u -e は外す: fail-open 方針 LOG="$HOME/.claude/logs/cost-log.jsonl" MODE="${1:-json}" fail-open ヘルパ fail open { if "$MODE" = "--short" ; then echo "⚫ n/a" else printf '{"5h status":"unknown","weekly status":"unknown","advice":"%s"}\n' "${1:-no data}" fi exit 0 } The reason for dropping set -e is stated in a one-line comment: "fail-open 方針" fail-open policy . That's the declaration of design intent. fail open takes an error-reason string as an argument. In --short mode it prints a single line, ⚫ n/a ; in JSON mode it emits a minimal JSON object containing 5h status:"unknown" and weekly status:"unknown" , then terminates with exit 0 . Because it exits zero, both launchd and cron treat it as a normal termination. The dashboard shows ⚫ n/a , and a human instantly understands "some data isn't being collected." This function gets called in three places. 1. Log file missing line 29 : -f "$LOG" || fail open "cost-log.jsonl not found" Day one of setup, or when the log path changes. The existence check lives only here. 2. Python aggregation comes up empty lines 203–205 : if -z "$RESULT" ; then fail open "python aggregation failed" fi For when Python throws an error to stderr and leaves stdout empty. Since 2 /dev/null discards the error output, all bash learns is "aggregation failed." 3. JSON parse failure line 208 : python python3 -c "import sys,json; print json.load sys.stdin ' short' " 2 /dev/null || fail open "json parse failed" For when Python emits malformed JSON. The || falls through to fail open . In every case, fail open guards only the points where "if this trips, downstream output can't be guaranteed." This isn't defensive programming that catches every error — it's a design that explicitly protects the minimal set of chokepoints where a failure means no output at all. The data sources are a two-stage setup lines 34–56 . if command -v ccusage /dev/null 2 &1; then CC JSON=$ ccusage blocks --json 2 /dev/null || true if -n "$CC JSON" ; then EXTRACTED=$ printf '%s' "$CC JSON" | python3 -c " import sys, json try: d = json.load sys.stdin active = b for b in d.get 'blocks', if b.get 'isActive' if active: b = active 0 tc = b.get 'tokenCounts', {} or {} out = int tc.get 'outputTokens', 0 cost = float b.get 'costUSD', 0 print f'{out}|{cost}' else: print '|' except Exception: print '|' " 2 /dev/null || echo "|" CC OUTPUT TOK="${EXTRACTED%| }" CC COST 5H="${EXTRACTED |}" fi fi ccusage blocks --json 2 /dev/null || true — throwing errors into /dev/null and falling back to true keeps the pipeline from stopping. Even in an environment where ccusage doesn't exist, processing continues with CC OUTPUT TOK and CC COST 5H as empty strings. Inside the inline Python script, try/except Exception swallows all exceptions and prints | just the separator on failure. After splitting EXTRACTED , you get CC OUTPUT TOK="" and CC COST 5H="" , and the rest of the processing treats it as "no ccusage." When ccusage is alive, its values take priority over the self-log aggregates as the "official" numbers lines 126–131 . ccusage の値が有効ならそちらを優先 transcript 計算より信頼できる own out 5h = out 5h if cc out is not None and cc out 0: out 5h = cc out if cc cost is not None and cc cost 0: cost 5h = cc cost On top of that, the source diff pct field computes the divergence rate against the self-computed aggregate lines 135–137 and includes in the JSON how far apart the two data sources are. diff pct = None if cc out is not None and own out 5h 0: diff pct = round abs cc out - own out 5h / max cc out, own out 5h 100, 1 This is for debugging, but it's also early detection for bugs in the self-log aggregation logic. In fact, when this source diff pct exceeded 20%, I discovered a session double-counting bug in cost-log.jsonl . The --short mode, meant for dashboard integration, narrows output to a single line. The actual output format is defined at line 196 of the Python heredoc. " short": f"{icon} {label} 5h:{out 5h/1000:.0f}k tok ${cost 5h:.1f} / 7d:${cost 7d:.0f} ", For example, healthy looks like 🟢 OK 5h:342k tok $1.2 / 7d:$48 , and a warning looks like 🟡 burst 5h:823k tok $4.1 / 7d:$1204 . The format assumes it's called by launchd every 30 minutes and embedded in the terminal status bar. The icon decision logic is concentrated in lines 173–181. if s5 == "critical": icon, label = "🔴", "cap-near" elif s5 == "warn" or sw == "warn": icon, label = "🟡", "burst" elif burst: icon, label = "🟡", "burst" else: icon, label = "🟢", "OK" The actual threshold values live at lines 139–141. THRESH 5H WARN = 800 000 output tokens THRESH 5H CRIT = 1 200 000 THRESH WEEK WARN = 3000 USD THRESH SESS PER DAY = 5 Output tokens in a 5-hour block over 800,000 turns it 🟡; over 1,200,000 turns it 🔴. Weekly cost over $3,000 turns it 🟡. If the average session count over the last 3 days exceeds 5, a "focused work" flag is raised. That detection isn't a separate alert — it's folded into the advice string line 169 . if burst: advice parts.append f"直近3d平均 {avg sess:.1f}sess/day: 集中作業中" JSON mode formats output through python3 -m json.tool line 210 . It's for manual inspection and for piping into other scripts. --short targets launchd's automated invocation, JSON targets a human checking manually — that separation of roles is the essence of the two-mode design. When --short returns ⚫ n/a , running JSON mode by hand puts the error reason in the advice field. {"5h status":"unknown","weekly status":"unknown","advice":"python aggregation failed"} Even the debugging path from dashboard to JSON mode is self-contained in those two modes. latest dict The meatiest part of the script is the Python aggregation block at lines 80–124. It reads the file once and throws it away, then reads it again. Let's start with why it's two-pass. The spec of cost-log.jsonl is: "for each session ID, transcript file pair, cumulative values are progressively overwritten." While Claude Code keeps running within the same session, the running token total up to that moment is appended as a JSONL line every 10 minutes. In other words, if you just sum every line in the file, you add the same cost dozens of times over. My first naive implementation did exactly that. A session whose real cost was $0.8 ballooned to $12 — one multiple per log line. The corrected code looks like this lines 99–111 . cost-log は session id × transcript ごとに累積値で書かれる仕様。 最新行のみ採用するため、 session id, transcript で最終行を取り直す。 latest = {} with open log path as f: for line in f: try: r = json.loads line t = datetime.datetime.fromisoformat r "ts" except Exception: continue key = r.get "session id", "" , r.get "transcript", "" prev = latest.get key if prev is None or t prev 0 : latest key = t, r Note that the key is a session id, transcript tuple. If you key on session id alone, a different transcript file generated when Claude Code restarts gets overwritten as "the same session." That actually wiped out an entire day of cost data once. Keying on the pair of both fields gives you the right granularity: "the latest state of the same work context." After building this dict, it loops with for sid, tr , t, r in latest.items line 113 , deciding whether the timestamp falls within 5h or 7d and aggregating accordingly. The two-pass structure exists because the requirement "use only the latest line" can't be satisfied in one pass. To aggregate while reading in a streaming fashion, you'd first have to scan everything to pin down the final line for each key. The first loop, still sitting at lines 80–97, is nearly empty. with open log path as f: for line in f: try: r = json.loads line t = datetime.datetime.fromisoformat r "ts" except Exception: continue sid = r.get "session id", "" ... if t = cutoff 5h: pass ← ここが空 It literally says pass . That's the part where the comment reads "if the transcript is the same we want to overwrite-aggregate with the latest line → simple summing is fine here." The trace of me hesitating mid-rewrite is still sitting there. In reality, the 5-hour window aggregation is also done from the latest dict in the second pass lines 116–119 . The first pass currently only updates sess 7d by day , and even that dict isn't used for the final burst determination the by day counter is used instead — the more you read, the more visible the "refactor stopped halfway" evidence becomes. This isn't a bug; it's a judgment call that there was no need to break working code. The script runs correctly at 212 lines. The implementation that "composes ccusage data and self-log aggregates with a priority order" is just 6 lines, at 126–131. ccusage の値が有効ならそちらを優先 transcript 計算より信頼できる own out 5h = out 5h if cc out is not None and cc out 0: out 5h = cc out if cc cost is not None and cc cost 0: cost 5h = cc cost Stashing the original value in own out 5h is the important part — it's there so that when diff pct is computed at lines 134–136, there's something to compare the ccusage value against. diff pct = None if cc out is not None and own out 5h 0: diff pct = round abs cc out - own out 5h / max cc out, own out 5h 100, 1 The source diff pct field is only visible in JSON mode. You don't normally think about it, but when a bug creeps into the self-log logic, you notice the instant it diverges from ccusage by 20% or more. I've found two bugs that way. In environments where ccusage isn't usable e.g. command -v ccusage fails due to a PATH issue , cc out and cc cost both stay None , the priority handling is skipped, and it runs on self-log aggregates alone. Because the "stages" of the two-stage fallback are cleanly separated, you can also confirm which source was used via the ccusage used field line 194 . The way Python is launched at line 59 is slightly unusual. RESULT=$ python3 - "$LOG" "${CC OUTPUT TOK:-}" "${CC COST 5H:-}" <<'PY' 2 /dev/null python3 - is the mode that reads a script from stdin. After that, <<'PY' pipes a heredoc into stdin. Arguments are passed via sys.argv . Why not split it out into a file? For the simplicity of placement: "everything is contained in one script." When I copy this script to another environment, I don't have to separately verify that the Python file exists. Drop one file into ~/.claude/scripts/ and it works. The launchd plist configuration just points at that single path. The important detail is that the heredoc delimiter is wrapped in single quotes as <<'PY' . With an unquoted <<PY , bash variable expansion is applied inside the heredoc. The moment {} or $HOME shows up in the Python code, expansion kicks in and you get a syntax error. I didn't know that, and wrote it as <<PY at first. When I first implemented naive summing over cost-log.jsonl , 7d cost usd came out at 4–6x the actual billed amount. Judging by the symptom alone, it looks like "API costs are exploding." The first thing I did to verify was check the real billed amount with ccusage daily . It said $48. The script was returning $234. Next, looking a bit at the contents of cost-log.jsonl , I saw dozens of lines with the same session id and incrementing cost usd values. If a session is written out every 10 minutes, you get a run of cumulative values like 0.12, 0.24, 0.37, 0.51... . Adding all of those up recorded a $0.51 session as $1.24. Even after identifying "summing all lines of cumulative values" as the cause, I hesitated once on the fix strategy. To "take only the final line" you have to scan every line once, and the answer changes depending on whether "final line" means "latest timestamp" or "last in file order." Considering that writes to the file might not always be in chronological order, I settled on an implementation that explicitly compares timestamps if prev is None or t prev 0 at lines 107–111 . After the fix, source diff pct read 2.3%. That wasn't an error — it was normal divergence caused by a difference in calculation basis between the self-log aggregation and ccusage the output-token counting method differs slightly . The first week after registering the script in a launchd plist, the status bar kept emitting ⚫ n/a every single time. Running ~/.claude/scripts/token-budget-advisor.sh --short by hand returned 🟢 OK . Tracking down the cause took two hours. The PATH of the shell launchd starts is /usr/bin:/bin:/usr/sbin:/sbin . It's a completely different thing from the $PATH you have in your terminal. When command -v ccusage fails, CC JSON ends up empty and the ccusage path is skipped. But that wasn't the problem — the problem was that a different script an older version that depended on ccusage was written fail-closed and did exit 1 the moment the ccusage command wasn't found. Since rewriting to this script, it runs off self-log aggregation even when ccusage is outside PATH. If ccusage is found, ccusage used: true ; if not, it stays ccusage used: false and aggregates from the self-log alone. Neither path produces ⚫ n/a . As for handling the plist, the root fix is adding nvm's bin path to launchd's EnvironmentKeys. But then the plist needs updating every time the nvm version changes. Keeping a fail-open design that works without ccusage has a lower management cost over the long run. set -e in one version, and the dashboard was dead for a week The predecessor of this script was a different file. When I first wrote it, it started with set -euo pipefail . Because "it looks robust." One Monday morning, the ccusage API returned a timeout. ccusage blocks --json threw an error to stderr and terminated with exit 1, so bash's CC JSON=$ ccusage blocks --json caught the error and the entire script exited 1. set -e "worked" exactly as intended. As a result, the dashboard status bar went blank. Blank looks like "no problems." That week, I missed the ccusage API anomaly entirely and kept doing heavy work, and the 5-hour block crossed critical twice. It wasn't a cost problem — it was a "I couldn't notice" problem. A dashboard that says nothing is the worst possible warning. I realized it the following week while chasing down why the status bar had been blank. Looking at launchd's logs under ~/Library/Logs/ , there were exit-1 records at the same time every day. It turned out the ccusage timeouts had been happening intermittently over several days. This version is the one where I added 2 /dev/null || true , dropped set -e , and left only set -u . || true is the idiom for "silently turn an error into success," but here it carries a clear intent: "even if ccusage fails, don't stop the script." It's not mere defensive programming — it's an explicit statement of the judgment that "errors at this layer should not be propagated to the dashboard." Two weeks ago, when I ran JSON mode manually, it showed "source diff pct": 28.4 . ccusage said the 5h output tokens were 580,000; the self-log said 420,000. A 28% divergence is not within margin of error. At first I thought "ccusage must be wrong." There's no way a homemade log is more trustworthy than the official tool, but that's what it felt like. When I actually inspected cost-log.jsonl with jq , I noticed there were a large number of lines with the same session id under a different transcript path, and both had nearby timestamps. When Claude Code is shut down once and restarted, a new transcript file is generated — and at that point both the final line of the old transcript and the initial lines of the new one entered the latest dict, double-counting the session's cost. Within key = r.get "session id", "" , r.get "transcript", "" , the transcript field sometimes didn't exist in older versions of the cost log. In that case transcript becomes an empty string, and different transcripts get collapsed into the same key session id, "" with only the latest line surviving — that's the behavior I thought I had, but in some lines the field name for transcript was "transcript path" . So r.get "transcript", "" was returning an empty string. The fix is one line. I changed it to r.get "transcript" or r.get "transcript path", "" . That said, it's a separate fix to this script, and the code shown here still has the old r.get "transcript", "" . Without source diff pct , I would have noticed that discrepancy far, far later. The practical value of a design that runs two data sources in parallel and reports the divergence rate only really hit me at that moment. <<PY and <<'PY' and broke Python This is a repeat, but since it actually happened I'm recording it. When I wrote the Python heredoc delimiter as <<PY unquoted , the {} in by day = collections.Counter inside the Python code became a target of bash brace expansion. The error message was syntax error near unexpected token '}' , which reads as nothing other than "the Python code is broken." Per bash's heredoc spec, if the delimiter isn't quoted, variable expansion, command substitution, and backslash processing all happen inside the heredoc. Any ${...} or $ ... syntax in the Python code gets interpreted by bash. The in collections.Counter isn't a problem for bash, but there are cases where dict-literal {} is. Using <<'PY' delimiter in single quotes disables all bash expansion inside the heredoc. When the Python code mixes variable expansion, braces, and command substitution, a quoted delimiter is the correct answer. This is basic bash knowledge, but working backwards from the symptom "why did Python break?" took time. The walkthrough above covers "how it works." From here I'll enumerate "where it breaks." I won't repeat the earlier ones duplicate aggregation, launchd PATH, leftover set -e , <<PY vs <<'PY' . These are the additional places I actually got stuck beyond those. Mixing timezone-naive and timezone-aware datetimes. Line 69's now = datetime.datetime.now is a naive object with no timezone. Line 84's t = datetime.datetime.fromisoformat r "ts" becomes aware if the ts field contains +09:00 . The moment you compare naive and aware with t = cutoff 5h , a TypeError flies. Because the entire script discards stderr with 2 /dev/null , the Python traceback goes nowhere, RESULT just comes back empty, and all you get is fail open "python aggregation failed" . The dashboard shows ⚫ n/a , and even running JSON mode manually gives you nothing but python aggregation failed in the advice field. This is the kind of landmine that detonates the moment an external tool integration changes its ts format. isdigit is for positive integers only. Line 63: cc out = int cc out str if cc out str.isdigit else None . str.isdigit returns True only for positive integer strings. It's False for empty strings, negative numbers, and floats "1234.5" , so cc out falls through to None. If ccusage's API response spec changes to return outputTokens as a float, the script won't stop — it will fall back to the self-log — but you won't notice that the value's source has changed. source diff pct becomes null, which is the only clue. The first-pass code is effectively empty. Read lines 90–93 as written and you get: if t = cutoff 5h: pass . The comment says "simple summing is fine," but it was never updated after migrating to the second-pass latest dict. The actual 5h aggregation is handled at lines 116–119. Anyone reading the code gets confused about "why pass ?" It's not a bug, it's a trace of a half-finished refactor — but without a comment, it'll cost you an hour of head-scratching. sess 7d by day is never used. Line 78 defines sess 7d by day = collections.defaultdict set and line 96 writes sess 7d by day day .add sid . But the burst determination lines 157–159 uses the by day counter built in the second pass. sess 7d by day is never read once before the process ends. At realistic operating scale it's rare for cost-log.jsonl to exceed a few MB, but run it against a large log and that unnecessary set construction consumes memory. 2 /dev/null kills your debugging. Line 59's entire Python invocation is wrapped in 2 /dev/null . When the script terminates normally exit 0 but no data comes back, the only clue is the error string in the advice field. When debugging, temporarily removing 2 /dev/null and running it lets you see the Python stack trace. You don't need to remove it in production, but if you don't know this standard move for "I can't tell why it's failing," tracking down the cause of ⚫ n/a will cost you hours. There's no argument validation for --short. Line 17: MODE="${1:-json}" . With no argument it becomes json . The check is a string comparison, "$MODE" = "--short" , so passing short no hyphen or -short one hyphen runs it in JSON mode. Mistype the argument in the launchd plist and the dashboard always gets multi-line JSON back, breaking the parse. You get neither ⚫ n/a nor 🟢 — the status bar displays { . Because the symptom looks similar to the launchd PATH problem, diagnosis gets delayed. Burst detection is lenient in a fresh environment. Line 157: recent days = sorted by day.keys -3: . On day one or two of setup there's less than 3 days of data, so max 1, len recent days returns 2 or 1. With two days of data you get a two-day average; with one day, the judgment is made from a single day. Burst detection errs toward leniency, so it's the safe direction — but it's the cause of "why am I seeing so many 🟡?" in the first week. The short key is exposed in JSON mode. Line 196's " short": f"..." remains included in the JSON output. Because python3 -m json.tool formats and prints every field, external tools parsing the JSON get short mixed in as an unexpected field. The prefix is a Python internal-use convention; JSON has no hiding mechanism. There's no functional problem so I've left it, but if you're integrating externally you should result.pop " short" before handing it off.Here are the decision criteria I extracted from this one script and six months of operation. Not "you should do this," but "here's why the dashboard went silent in a production environment carrying ¥1.2M/month of revenue when I didn't do this." 1. Declare the design philosophy in a one-line comment at the top set -u -e は外す: fail-open 方針 Dropping set -e is a deliberate choice, not an omission. Without the comment, a later reader — future me, or someone in code review — will put -e back "to harden it." A comment on line 1 of the script becomes the spec document for the design philosophy. 2. Concentrate output-mode branching in one place inside fail open fail open references the MODE variable internally and emits one line for --short or minimal JSON for JSON mode. Having fail open handle it centrally leaves fewer gaps than branching per-mode at each call site. Passing the error reason as an argument — like fail open "cost-log.jsonl not found" — leaves debugging information in JSON mode's advice field. 3. For external commands, write both the existence check and the runtime-error swallow if command -v ccusage /dev/null 2 &1; then CC JSON=$ ccusage blocks --json 2 /dev/null || true command -v alone can't protect against "it exists but timed out at runtime." || true is the explicit expression of the design stance that "errors at this layer are not propagated to the dashboard." Only with both written does fail-open actually hold. 4. Use two data sources and compute the divergence rate Run the official tool ccusage and your own log in parallel, and continuously compute the divergence with source diff pct lines 134–136 . When one of them breaks, a divergence of 20%+ tells you. With a single source, you enter the state where "both can be wrong and you'd never know." When source diff pct exceeded 28%, I discovered the transcript field key-name mismatch bug. 5. For cumulative JSONL logs, always take only the latest line, keyed on a pair Key on the session id, transcript tuple and keep only the latest line lines 100–111 . Keying on session id alone erases the separate transcript after a restart. Summing all lines multi-counts cumulative values. If your cost aggregation reads "5x the real number," suspect this first. 6. Always use <<'PY' for the Python heredoc delimiter An unquoted <<PY runs bash variable expansion inside the heredoc. If your Python code mixes {} , $HOME , or command substitution, you get a syntax error that looks like nothing but "Python broke." Using <<'PY' single quotes disables all expansion inside the heredoc. 7. Assume launchd's PATH problem and design so it works without external commands The PATH of the shell launchd starts is /usr/bin:/bin:/usr/sbin:/sbin . It doesn't include nvm or Homebrew bin paths. If you design so it runs on self-log aggregation even when ccusage is outside PATH, a PATH problem won't take down the entire dashboard. Adding PATH to the launchd plist is the root fix, but it needs updating every time a tool's version changes. Fail-open design has a lower long-term maintenance cost. 8. Have fail open terminate with exit 0 With exit 1 , launchd records the job as an error. If every automated run every 30 minutes gets treated as an error, launchd's execution log fills with noise and the real errors the script got deleted, etc. become invisible. A monitoring script's fail-open depends on exit 0 making launchd treat it as a normal termination. 9. Limit output to four states Narrow it to four: ⚫ n/a no data , 🟢 OK , 🟡 burst , 🔴 cap-near lines 174–181 . Add more than that and the decision logic gets complex, which itself becomes a breeding ground for bugs. Four states are the minimum set that satisfies both "a human can read it instantly" and "the logic stays simple." 10. Collect thresholds as constants at the top of the script THRESH 5H WARN = 800 000 THRESH 5H CRIT = 1 200 000 THRESH WEEK WARN = 3000 THRESH SESS PER DAY = 5 As at lines 139–142, gather the decision values as named constants in one place. If magic numbers are scattered through the decision logic, you go hunting through every location every time you tune a threshold. If you're going to adjust thresholds monthly as revenue changes, having the change surface in one place is a hard requirement. 11. Pair --short and JSON as a debugging path When --short returns ⚫ n/a , the next action must be obvious. Running JSON mode manually puts the error reason in the advice field python aggregation failed , cost-log.jsonl not found , etc. . Build them as a pair, so that the moment the dashboard indicates "something's off," exactly one next command is determined. 12. Standardize timezones on the log-writing side Mixing naive/aware between datetime.now and fromisoformat kills you instantly with a TypeError. If the log writer pins the ts field to a naive ISO format e.g. %Y-%m-%dT%H:%M:%S , the aggregation side can compare it safely against datetime.now . If you're mixing externally generated logs with your own, place a single conversion layer at ingest. 13. Make dead variables explicit — comment them or delete them Variables that get built but never read, like sess 7d by day lines 78 and 96 , confuse the humans who read the code later. Delete it if you can; if there's a reason to keep it, write a comment saying "not currently read because of X." The same goes for the first pass's pass block lines 91–93 . One line saying "old code after migrating to the second pass" prevents the confusion. 14. Understand the limits of isdigit before using it Before casting a numeric string returned by an external tool's API to an integer, be conscious that isdigit is for positive integers only. Generically, the try: int cc out str except ValueError, TypeError : None form is safer. The current script depends on the assumption that ccusage returns integers, and a spec change silently switches it to the self-log fallback. Conversion logic that depends on external tools lowers maintenance cost when you make the degraded mode explicit before writing it. token-budget-advisor.sh is 212 lines. That's not big. But the design decisions condensed inside it are dense. Dropping set -e isn't "abandoning robustness." It's the choice to break the chain of "when this script stops, the dashboard stops too." The property you need from a monitoring script is not accuracy but never going quiet. That's the one point I wanted to make through this single script. In an autonomous environment carrying ¥1.2M/month, the cost of a dashboard saying nothing accumulates in a way that's hard to see. When the ccusage API was timing out for a day, the script with set -e alive kept up a "silence indistinguishable from healthy operation." I found out afterward that the 5-hour block had crossed critical twice that week. It's not that the dashboard kept showing 🟢 . It just showed nothing at all. Blank and healthy were visually indistinguishable. Fail-open is not "a design that ignores errors." It's "a design that delivers the existence of an error to a place where a human can see it." ⚫ n/a is not 🟢 . It's the minimum output required to keep an abnormal state from looking normal. The script is still running every 30 minutes today. As long as it runs, it doesn't go quiet. I've written up the full picture of the system, the breakdown of the ¥1.2M/month, and the 30-day procedure in a paid note. 📕 Claude Code自律環境で、実際どう稼ぐか ― 仕組み・実例・始め方・サポート https://note.com/bokuwalily/n/n849b3a07784a Written by Lily — I ship iOS apps and automate my content stack with Claude Code. Follow along: Portfolio https://bokuwalily.com · X https://x.com/bokuwalily · GitHub https://github.com/bokuwalily