The request

Every app from one developer account:

1

https://itunes.apple.com/lookup?id=1557125814&entity=software&limit=200

id is the developer (artist) ID from your App Store URL. entity=software returns the apps as well as the developer record, and limit=200 raises the default page size. Each result has the name, icon, screenshots, version, genre, minimum OS and release dates. That covers a portfolio page.

The cache

Check the headers:

1
2
3

$ curl -sD - -o /dev/null "https://itunes.apple.com/lookup?id=1557125814&entity=software&limit=200" | grep -iE "cache"
cache-control: max-age=86400
x-cache: TCP_MISS from a23-219-204-163.deploy.akamaitechnologies.com ...

Run the same request again a few seconds later:

1
2

cache-control: max-age=86394
x-cache: TCP_HIT from a23-219-204-163.deploy.akamaitechnologies.com ...

max-age=86400 is 24 hours, and the second request is a TCP_HIT: the edge node answered and Apple’s servers never saw it. That’s fine for an app page that changes once a month. It’s not fine when you ship an app in the morning and deploy the site right after, because the build can get the list from before the release. BaliSurf went live the same day I wrote this script, so I needed the fix straight away.

The fix

Akamai keys the cache on the full URL, query string included, and the Lookup API ignores parameters it doesn’t know. So add one that’s different on every request:

1
2

const URL_ =
  `https://itunes.apple.com/lookup?id=1557125814&entity=software&limit=200&_=${Date.now()}`;

Every deploy is now a cache miss and gets the current list from Apple.

The rest of the script

It’s about 50 lines of Node with no dependencies (built-in fetch), and it runs in the GitHub Actions workflow before hexo generate. It writes source/_data/apps.json, and Hexo templates read that as site.data.apps. Three details worth copying:

• Never fail the build. The JSON file is committed. If Apple is down or the response looks wrong (no apps, an app with no screenshots), the script logs the error, keeps the committed file and exits 0. The site deploys anyway with slightly older data.
• Smaller screenshots. Lookup returns fixed-size thumbnails like .../392x696bb.jpg. Apple’s image CDN reads the size from the last path segment, so replacing it with 480x0w.webp gives a 480px-wide WebP with the same aspect ratio. That change fixed the mobile LCP on the home page.
• Clean store links. trackViewUrl ends with an affiliate-style ?uo=4. Strip it.

1
2

const shot = (u) => u.replace(/\/[^/]+$/, '/480x0w.webp');
const url = r.trackViewUrl.replace(/\?uo=\d+$/, '');

That’s all of it: one public endpoint, one cache-busting parameter, and a committed fallback file.

The tool is Claude Code. The workflow has four steps and one piece of infrastructure.

1. Spec: decide what “done” means

Every non-trivial piece of work starts as a conversation that ends in a short design document: goal, scope, what’s explicitly out of scope, which files change, and how we’ll know it’s done. For the redesign it was 89 lines.

This is where I spend my attention. The spec is where I choose between options (often from rendered mockups, not descriptions), cut scope, and write down constraints the agents can’t guess — “no new npm dependencies”, “motion only on three pages”, “copy may only use facts from the CV”.

2. Plan: small tasks, each with its own check

The spec becomes a plan: a list of tasks, each small enough for one agent in one go. Every task in a good plan has the same shape:

1. A failing check — a command that fails now and should pass after the task, with its expected output.
2. The change — which files, often with the actual code.
3. The same check again, now expected to pass.
4. A commit, with the exact message.

On top sits a short list of global constraints that must hold after every task. The redesign plan was 1,180 lines for 9 tasks. That sounds like a lot of writing, but the agents write most of it; my job is to read it and push back before any code exists — the cheapest moment to change your mind.

3. Execute in a fresh session

Here’s a rule from my global CLAUDE.md: small tasks run inline, but for a large plan, stop before implementing. Save the plan, update the project notes, end the session, and start the implementation in a new one.

Two reasons. The long design conversation is expensive to carry around — every message re-reads the whole history, as I found out the hard way. And a fresh session that knows only the plan is a good test of the plan: if it can’t execute from the document alone, the document isn’t done.

4. Implement and review with subagents

The implementation session doesn’t write code itself. For each task it starts an implementer subagent, then a separate reviewer subagent that checks the result against the spec and the plan. At the end, one more reviewer looks at the whole branch.

Models are picked by the kind of work, also written down in CLAUDE.md:

• Searching → the cheapest model.
• Mechanical edits, summaries, log triage → the mid-tier model.
• Reasoning that actually needs it — the final review, a hard bug → the strongest model.

The whole-branch review is the one that earns its cost. In the redesign, the per-task reviewers passed everything; the final reviewer found the two real bugs, both in how two tasks interacted.

The missing piece: memory

Agents start every session from zero. Without memory, each new session re-discovers the same project, re-asks the same questions and repeats the same mistakes. I use two layers to fix that.

Project notes: obsidian-memory

obsidian-memory is a small Claude Code plugin I wrote. It’s two hooks:

• When a session ends, it reads the transcript and, if there were at least four meaningful turns, runs one small, cheap model call that writes two notes into my Obsidian vault: an immutable note for that session, and an updated SUMMARY.md for the project — goal, current state, key files, recent decisions, open tasks, and “context to resume”.
• When a session starts, it loads that project’s SUMMARY.md into the context.

So a new session starts by knowing that the redesign is merged, which CV variants exist, and what’s still open. Specs and plans live next to the summaries, in the same vault, so they’re searchable and linked.

One design decision I’d repeat: the summarizer treats the transcript as untrusted input. A transcript can contain anything — web pages, tool output, text someone crafted to look like instructions. So the child process that writes the notes is allowed to use exactly one tool, Write. No shell, no reading other files, no network. If something in a transcript tries to hijack it, there’s nothing to hijack it with.

Lessons: feedback memories

The second layer is Claude Code’s own per-project memory: small files, one fact each. The most valuable kind is feedback — a correction I gave once, with the reason, so I don’t have to give it again. Two real examples:

• “Find every call site before shipping.” Twice in one day a fix shipped after finding only the first matching call, or was declared “verified” from evidence that couldn’t tell it apart from another explanation. The rule now: search every spelling of the API before naming the cause, and don’t claim “verified” if the evidence is ambiguous.
• “Plain UI over decoration.” I kept rejecting decorative additions — a coloured ring, a gradient background — in favour of system colours and native materials. The rule now: don’t add styling nobody asked for.

What I still do myself

Looking at this workflow from the outside, it can seem like I’ve automated myself away. The opposite happened. My work moved to both ends:

• Before the code: choosing the direction, writing down what “done” means, deciding what’s out of scope.
• After the code: the questions agents escalate, the bugs that only show up on a real device, and the final call on every merge.

The agents are very good at following a clear plan and at catching each other’s mistakes. They’re only as good as the plan — and the plan is still my job.

The setup

The tool is RenderCV: you describe the content in YAML, and it typesets the PDF through Typst. The content looks like this:

1
2
3
4
5
6
7
8
9
10
11

cv:
  name: Vladimir Babin
  headline: "Senior iOS/macOS Engineer · Architecture-led, agent-driven delivery · Remote since 2015"
  sections:
    Experience:
      - company: Independent
        position: Software Engineer
        start_date: 2026-07
        end_date: present
        highlights:
          - "Took four apps from idea to the App Store in two months — ..."

No layout, no fonts, no margins — just facts. The design lives separately.

Four variants, one design

I apply to different kinds of roles: native Apple, cross-platform mobile, full-stack, AI engineering. The same experience deserves different emphasis for each, so there are four files:

1
2
3
4
5
6

source/cv/
├── design.yaml                     # theme, fonts, colours, margins
├── Vladimir_Babin_CV.yaml          # main: Apple platforms + agent-driven delivery
├── Vladimir_Babin_CV_KMP.yaml      # cross-platform mobile
├── Vladimir_Babin_CV_FullStack.yaml
└── Vladimir_Babin_CV_AI.yaml

Each variant points to the shared design with one line:

1
2
3

settings:
  render_command:
    design: design.yaml

At one point there were six variants, each carrying its own copy of the same 47-line design block. Change the link colour — edit six files. When I consolidated them into four and extracted the design into design.yaml, the commit deleted 610 lines and added 106 — and the split into content and design didn’t change a single pixel of the PDFs.

The pipeline

The GitHub Actions workflow that builds this Hexo site also renders the CVs:

1
2
3
4
5
6
7
8
9
10

- name: Install RenderCV
  run: pip install "rendercv[full]==2.8"

- name: Render CV
  run: |
    cd ./source/cv/
    rendercv render Vladimir_Babin_CV.yaml
    cp -r rendercv_output/* ../../public/cv/
    rendercv render Vladimir_Babin_CV_KMP.yaml -pdf ../../public/cv-kmp/Vladimir_Babin_Cross_Platform_Mobile_Engineer.pdf
    # ...and so on for each variant

A few details that turned out to matter:

• Pin the version. RenderCV’s CLI changes between releases; a flag that worked in one version fails in the next. ==2.8 means the CV renders the same way next year.
• Stable URLs. The main CV always lives at /cv/Vladimir_Babin_CV.pdf. That’s the link I put in job applications and profiles. Update the YAML, push, and every link I’ve ever sent now points to the new version.
• Don’t break old links. When I merged the iOS and TON variants into others, their URLs (/cv-ios/, /cv-ton/) became tiny HTML redirects to the successors. Someone who got the link a month ago still lands on a real CV.
• Publish the source. The YAML is copied next to each PDF. Anyone curious can see exactly what the CV is made of.

The one-page rule

Every variant must be exactly one page. That constraint does more editing than I do.

Typst breaks pages atomically: add one bullet, and the whole Skills + Education block jumps to page two. So every change goes through the same loop: render all four variants, count pages, look at the PNG preview to see what spilled over, cut. The first time I fit the main CV onto one page, it was typography only — margins, 9.5pt body text, tighter line spacing — without removing a single bullet. Since then, every new line has had to push an old one out.

That’s the point. A one-page limit forces the question “is this bullet better than the one it replaces?” on every edit.

Git as a CV changelog

The best part is the history. git log -- source/cv is a record of how I’ve been presenting myself, with reasons:

1
2
3
4
5
6

CV: state English level as C1
CV: tighten bullets, add verified metrics across all variants
CV: merge to 4 variants, shared design.yaml, add Independent entry
CV: normalize job titles across all variants
CV: soften metrics that can't be backed up
Fit the CV onto a single page

That “soften metrics” commit is my favourite. An earlier version claimed “reduced crash rate by ~40%” and “first TestFlight build in 2–3 weeks”. They sounded good, but I couldn’t point to a dashboard or a document that proves them. So the diff replaced them with what I can defend:

1
2

- Reduced crash rate by ~40% through refactoring, monitoring, and defensive coding.
+ Drove crash-rate reduction through crash-report triage, refactoring, and defensive coding.

A CV in Word has no memory of why a line changed. A CV in git does, and a reviewer — human or AI — can check every claim against the diff that introduced it.

Should you do this?

If you edit your CV twice a year, probably not; a template in any editor is fine. But if you keep several versions, update them often, or apply to a lot of roles, treating the CV like code pays off quickly: one source of truth, a shared design, automatic publishing, and a history that explains itself.

The files are public: the main CV and its YAML.

Spec first, code later

The work happened in two separate sessions, on purpose.

Session one — design. A brainstorm with rendered mockups of several visual directions, side by side in the browser. I picked “Editorial Paper”: warm paper background, Instrument Serif headlines, JetBrains Mono labels, and real App Store screenshots of my own apps as the only imagery. Then an 89-line spec — palette, fonts, motion behaviour, performance budget, done criteria — and a 1,180-line plan split into 9 tasks, each with exact files, code and checks.

Some decisions made there, before any code existed:

• GSAP + Lenis, no Three.js. A fanned stack of screenshots gains nothing from WebGL, and Lighthouse would pay for it.
• Progressive enhancement. HTML and CSS render the final state; JavaScript only adds motion when it’s allowed. prefers-reduced-motion exits before a single tween is created.
• Motion only on Home, About, Apps. Blog posts get the new fonts and colours, but stay calm.

Session two — execution. A fresh context that only knows the plan. This is the same lesson as in the 1M context post: the long design conversation doesn’t need to ride along into implementation.

The pipeline

The orchestrator session doesn’t write code. For each task it dispatches an implementer subagent, then a separate reviewer subagent that checks the result against the spec and the plan. The final review of the whole branch runs on a stronger model.

Result: 10 commits, 39 files changed, +730/−227 lines. First event to last commit of the implementation: 82 minutes. Merge and deploy check: another 3.

What the reviews caught

Tasks 1–8 all passed review. The interesting findings came from elsewhere.

A contradiction in my own plan. The Task 5 reviewer noticed that the reduced-motion failsafe animated visibility, while the plan’s global constraints said “transforms and opacity only.” The agent didn’t silently pick one — it stopped and asked. I kept the failsafe; visibility is an instant toggle, not an animation cost.

Two real bugs, found only by the final review. Per-task reviewers look at one task; the whole-branch reviewer sees how tasks interact:

1. A GSAP stagger tween finished by leaving an inline transform: translate(0, 0) on the work rows. Inline style beats the stylesheet, so the CSS hover nudge on the home page was permanently dead. Fix: clearProps: 'transform'.
2. The scroll parallax on screenshots also ran inside the horizontal-scroll strip on mobile, cropping shadows and adding vertical scroll where there should be none. Fix: gate it with gsap.matchMedia() to desktop widths.

Neither bug would show up in a unit test. Both are the kind a human would find a week later, on their phone.

Performance: an honest 87

The plan’s target was mobile performance ≥ 90 in Lighthouse. The first measurement of the home page: 77, with LCP at 5.6 s.

The culprit was the hero screenshots: JPEGs from Apple’s CDN. The CDN serves the same image as WebP if you ask for .webp instead of .jpg in the URL — a one-line change in the build script. One screenshot went from 69 KB to 24 KB at the same size. FCP dropped from 2.3 s to 0.9 s, performance rose to 87.

The remaining gap comes from the intro animation: the hero fades in, and Lighthouse only credits LCP once the element is visible. The agent laid out the trade-off and asked. I kept the animation — the intro is the point of the page.

Final numbers (mobile, performance / accessibility / best practices / SEO):

What didn’t go smoothly

• The browser was locked. Chrome DevTools MCP uses a shared browser profile, and another Claude Code session held it through most of the run. Live browser checks for tasks 3–8 were deferred to the final task, which worked around it with the standalone lighthouse CLI and an isolated profile in /tmp.
• A hanging screenshot. Headless chrome --screenshot hung indefinitely — twice. The workaround was Lighthouse’s own final-screenshot audit.
• Five minor findings parked, not fixed: a font preload on pages that don’t need it, missing lang="ru" on archive titles, and similar. They’re written down; they’ll wait.

My part

Three questions from the agents over the whole run, each with a recommended option: keep the failsafe, keep the animation, delete the merged branch. Everything else — code, reviews, measurements, fixes — happened without me.

What I actually did was the work before the code: choose the direction from rendered mockups, write down what “done” means, and cut scope (no Three.js, no motion on reading pages). The agents are good at following a plan and catching each other’s mistakes. They can’t decide what the site should be. That part is still the job.

The count

The repo keeps a manifest.yml per server — a plain list of app names, types, and hosts, used by the backup scripts to know which volumes exist. Counting real entries instead of guessing:

1
2

$ cat servers/*/manifest.yml | grep -c "^  - name:"
49

49 entries, minus the three monitoring stacks (a Beszel agent, not an app), gives 46: static sites, Node bots and services, one PHP app, one Go proxy, three Python services, and two blockchain validator nodes. servers/ also holds two more boxes that carry zero apps by design — one is a third-party host where I only hold a VPN tunnel, the other is a bare Tailscale exit node with no inbound path at all. Five servers total, three of them doing the actual hosting.

Deploying with Kamal

Most apps follow the same shape: a Dockerfile, a config/deploy.yml, and a .kamal/secrets file that pulls credentials out of this repo instead of holding them itself:

1
2

# .kamal/secrets
KAMAL_REGISTRY_PASSWORD=$(sops -d --extract '["docker_registry_password"]' "$INFRA/secrets/shared.enc.yaml")

kamal setup provisions the container, registers it with kamal-proxy, and requests a Let’s Encrypt cert over HTTP-01 — which means DNS has to resolve to the server before that command runs, not after. kamal deploy is everything after. Builds run on a remote builder over SSH rather than my laptop, so a deploy doesn’t depend on what’s plugged in at the time.

Adding a new app to the fleet is: provision a DB user if it needs one, scaffold from a static-site/node-app/php-app template, point DNS, deploy, then add the entry to manifest.yml so the nightly backup picks up its volumes. That last step is easy to forget — two apps went undocumented in a manifest for over a week after I deployed them, which meant their SQLite databases were being backed up nowhere. No error, no page, just nothing to restore if the disk died. The manifest is now the thing I check first, not last.

Secrets: SOPS and age

Every credential in the repo is SOPS-encrypted YAML, decrypted only at deploy or backup time. One age key pair covers everything, and the public half sits in plain sight in the config, because that’s the point of asymmetric encryption — the recipient list doesn’t need to be a secret:

1
2
3
4
5

# .sops.yaml
creation_rules:
  - path_regex: secrets/.*\.enc\.yaml$
    encrypted_regex: '^(.*_password|.*_token|.*_key|.*_secret|.*_uri|.*_id|.*_json|ssh_authorized_keys|.*_blob)$'
    age: age1...  # public key

Anything matching that regex gets encrypted field-by-field; everything else — app names, hostnames, comments — stays readable, so a diff of a secrets file still tells you what changed without exposing the value. The private age key lives only on my laptop. Lose it and every secret in the repo is gone with it — there’s no recovery path, which is the tradeoff for not running a KMS for a fleet this size.

When it breaks

The most recent incident was the backup job for the Claude agent I run on one of the servers. Its nightly backup used to stop every container sharing the agent’s data volume, snapshot the SQLite state while nothing could write to it, then restart everything — safe, but it held the agent down for the whole upload. On 2026-09-29 I rewrote it to skip the stop entirely: every SQLite database under the data directory gets a VACUUM INTO snapshot taken while the container keeps running, archived under its original path, with the rest of the directory tarred live. A file changing mid-tar now just produces tar’s exit code 1 (“some files differ”), which the script treats as expected rather than fatal, because the database state comes from the consistent snapshot, not the raw file.

Two commits landed that same day. The first excluded a Swift toolchain and a pnpm store the agent had fetched for its own coding work, after the archive regrew from 2.1 GB back to 11 GB and overflowed the tmpfs it stages to — tar exit 2 plus age exit 1 both mean the same thing, out of space, and the fix each time is du -sh on the data directory to find what grew. The second removed the container stop. Both are small diffs on a script that runs unattended at 4 AM; both came from reading a failed run’s log rather than guessing.

Running it solo

The parts that make this workable alone aren’t clever, they’re boring on purpose: every server bootstraps from the same numbered scripts, every backup pushes a dead-man heartbeat instead of a success message (silence is the healthy state, so a page only fires when something’s actually wrong), and every credential has exactly one place it’s allowed to live in plaintext — a 600-mode file on the server itself, shipped there by one make target. None of that prevents incidents. It just means the fix is usually a few lines in a script I already understand, not an afternoon reconstructing what a dashboard used to show.

obsidian-memory installs as a Claude Code plugin from its own marketplace repo. It writes a project’s state into an Obsidian vault when a session ends, and reads it back in when the next one starts.

The two hooks

The whole plugin is wired through one hooks.json:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/obsidian-load.sh",
            "timeout": 10
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/obsidian-save.sh",
            "timeout": 300,
            "async": true
          }
        ]
      }
    ]
  }
}

SessionStart gets 10 seconds and runs synchronously, because it’s just a file read. SessionEnd gets 300 seconds and runs async: true, because it spawns a model call and shouldn’t block the session from closing.

SessionStart: load the summary

obsidian-load.sh reads the hook’s JSON payload for cwd, takes the basename as the project name, and looks for <vault>/<project>/SUMMARY.md. If it finds one, it emits it as additionalContext:

1
2
3
4
5

jq -n \
  --arg ctx "Obsidian project summary from previous session (loaded from $SUMMARY):

$CONTENT" \
  '{hookSpecificOutput: {hookEventName: "SessionStart", additionalContext: $ctx}}'

It no-ops silently in five cases: a recursion guard is set, the vault env var is unset, the vault directory doesn’t exist, jq isn’t on PATH, or there’s no SUMMARY.md for this project yet. An unconfigured install is just quiet, not broken.

SessionEnd: write the summary

obsidian-save.sh does more work. It reads session_id and cwd from the payload, locates the session’s transcript under ~/.claude/projects/, and counts user/assistant turns. Below four turns it skips — not worth a model call for a one-liner. It also checks a dedup registry keyed on session_id:turn_count, so a hook that fires twice for the same session doesn’t write twice, and it skips projects whose SUMMARY.md has **Status**: archived.

If none of those short-circuit it, it builds a prompt: the last ~150 turns of the transcript capped at 40KB, the project’s MEMORY.md if one exists (treated as authoritative, human-owned ground truth), and the existing SUMMARY.md. That prompt goes to a child claude process that writes two files: a new, immutable session note under sessions/, and a rewritten SUMMARY.md for the project.

Locking down the summarizer

The transcript fed into that prompt is untrusted — it can contain anything a session touched: pasted text, tool output, a web page. The first version ran the child with --dangerously-skip-permissions. A commit review on the day of the first release flagged that as a prompt-injection RCE risk, and I fixed it in the same session, in commit c523729, which also bumped plugin.json from version 0.1.0 to 0.1.1:

1
2
3
4
5
6
7
8

nohup "$CLAUDE_BIN" \
  -p "$PROMPT" \
  --output-format text \
  --permission-mode dontAsk \
  --allowedTools "Write" \
  --disallowedTools "Bash,Read,Edit,MultiEdit,NotebookEdit,WebFetch,WebSearch,Task,Agent" \
  --model claude-haiku-4-5 \
  </dev/null >>"$LOG" 2>&1

--permission-mode dontAsk means it never blocks on an interactive prompt — it auto-denies anything not explicitly allowed. --allowedTools "Write" is the only capability it needs. The --disallowedTools list is belt-and-suspenders: dontAsk still permits read-only Bash by default, so Bash, Read, and the network tools are denied explicitly. That closes both the code-execution and the exfiltration path. The existing SUMMARY.md is passed into the prompt text instead of read by the child, so it doesn’t need Read at all. One risk is still open and documented in the README: a crafted transcript could in principle steer the one allowed Write to an unintended local path. The prompt marks everything between its ===== delimiters as data, not instructions, as the mitigation.

The model doing the writing is claude-haiku-4-5 — cheap enough that a summary per session end isn’t a cost most people would notice.

What gets written

A session note has Summary, Created/Updated timestamps, 2-5 tags, and 6-15 content bullets with [[wikilinks]]. SUMMARY.md has YAML frontmatter (project, cwd, status, tags) followed by ## Goal, ## Current state, ## Key files, ## Recent decisions, ## Open tasks / blockers, ## Context to resume, and a ## Recent sessions block bounded by <!-- SESSIONS:START --> / <!-- SESSIONS:END --> markers. A shell post-processing step (not the model) rebuilds that block from the 10 most recent files in sessions/ after every write, and truncates the whole file if it passes a 12,000-character trigger, keeping the tail intact.

Installing it

1
2
3

/plugin marketplace add chiliec/obsidian-memory
/plugin install obsidian-memory
/obsidian-memory-setup

The setup command checks for jq and the claude CLI, asks for the vault’s Projects-root path, and writes it as OBSIDIAN_MEMORY_VAULT in ~/.claude/settings.json. There’s also a manual install.sh fallback for anyone not on the plugin system.

Before any of that ships, tests/smoke.sh runs: it checks the shipped files for personal strings, validates shell syntax and JSON, and exercises both hooks against a temp vault. Ten checks, all passing, wired into GitHub Actions on every push to main and every pull request.

The vault today

This plugin is why I can make claims like this one. Counting fresh from the vault right now: 99 project folders under Journal/Projects/, holding 406 specs, 445 plans and 1,176 session notes. The session notes go back to April, two months before the plugin: the same hooks ran as local scripts in my config first. Turning them into a plugin mostly meant stripping out the personal parts: hardcoded paths and my Linear logic.

What’s symlinked

setup.sh links seven paths from the repo into ~/.claude/:

1
2
3
4
5
6
7

link CLAUDE.md          CLAUDE.md
link settings.json      settings.json
link skills             skills
link hooks/pin-model.sh     hooks/pin-model.sh
link hooks/context-guard.sh hooks/context-guard.sh
link hooks/obsidian-load.sh hooks/obsidian-load.sh
link hooks/obsidian-save.sh hooks/obsidian-save.sh

Because ~/.claude/settings.json is a symlink, not a copy, any write Claude Code itself makes to that file lands directly in the working tree. That turns out to matter, see below. One thing is deliberately not symlinked: my account switcher is its own public repo, fetched by curl in setup.sh instead, so the auth state it manages stays local to each machine rather than living in a config repo.

Four hooks

settings.json wires four scripts, all in hooks/:

The Obsidian pair is the memory layer I wrote about in how I work with AI agents. context-guard.sh reads the real context size out of the session transcript and nudges toward /exit at 130k tokens, which is below the roughly 166k point where Claude Code auto-compacts a 200k-token window on its own. It also warns on resume past 100k tokens after 300 seconds idle, on the theory that re-caching a cold session costs more than starting a fresh one.

The model setting fights back

settings.json pins "model": "opusplan" — Opus for planning, Sonnet for execution, a rule that’s also spelled out in my global CLAUDE.md. The problem: /model and the harness’s own on-exit save both rewrite that same top-level key, and since the file is a symlink into the repo, the rewrite shows up as uncommitted drift I’d otherwise have to notice and revert by hand. pin-model.sh runs on every prompt and puts it back:

1
2
3
4
5
6
7
8
9
10
11
12
13

PINNED="opusplan"
F="$HOME/.claude/settings.json"

[ -f "$F" ] || exit 0
grep -q "^  \"model\": \"$PINNED\",\$" "$F" && exit 0

current=$(sed -n 's/^  "model": "\(.*\)",$/\1/p' "$F")
[ -n "$current" ] || exit 0

tmp=$(mktemp)
trap 'rm -f "$tmp"' EXIT
sed "s/^  \"model\": \".*\",\$/  \"model\": \"$PINNED\",/" "$F" > "$tmp"
cat "$tmp" > "$F"  # redirect, not mv — mv would replace the symlink with a file

It only touches the on-disk default. A mid-session /model switch still runs on whatever model I picked; only the next fresh session goes back to opusplan. The cat > "$F" instead of mv matters for the same reason the whole setup exists: mv would replace the symlink with a plain file and quietly break the link to the repo.

Skills are generated, not forked

skills/ is superpowers — pinned in this repo at tag v6.2.0 — plus a small overlay, and it’s never hand-edited. build.sh clones the pinned tag, replaces skills/ wholesale, then reapplies the overlay via overlay/customize.sh:

1. A path redirect across every *.md, so upstream’s generic docs convention points at my actual Obsidian vault path instead.
2. Four patches (overlay/patches/*.patch) against brainstorming, writing-plans, executing-plans, and subagent-driven-development — they add the Opus model gates and point plan/session saves at the vault.
3. One shared helper file the patched skills reference for worktree edge cases, which doesn’t exist upstream.
4. Local skills that have no upstream equivalent — currently just disk-cleanup.

Everything else is byte-identical to what obra/superpowers ships. If a future upstream release restructures a patched section, build.sh fails loudly instead of silently applying a stale patch, which is the point of pinning a tag rather than tracking a branch.

What the baseline actually costs

I measured what reaches the model at the start of a session, once, on 2026-08-07, by reading the content field of the SessionStart attachment in a session transcript (not the attachment object — it repeats the text in both content and stdout, which doubles the apparent size):

Roughly 25k tokens of fixed baseline (divide chars by ~3.7), out of a 200k window, leaves about 135k tokens of real working room once a safety margin is subtracted. That’s why context-guard.sh warns at 130k rather than closer to the actual auto-compact point — there isn’t much room past it. The one surprising result: I’d assumed a plugin’s intensity setting (lite/full/ultra) changed how much it injected into context. It doesn’t — all three levels cost about the same, because the level only swaps one table row in the prompt. Turning a block off entirely is the only lever that moves the number.

None of this is exotic. It’s a symlink farm, four small scripts, and one generated directory, kept in git so a change is a commit instead of a fact I have to remember.

The map

diskutil info on the Data volume, right now:

1
2
3
4

$ diskutil info /System/Volumes/Data | grep -E "Volume (Used|Free)|Container Total"
   Container Total Space:     245.1 GB (245107195904 Bytes)
   Volume Used Space:         210.8 GB (210836877312 Bytes)
   Volume Free Space:         9.0 GB (8988352512 Bytes)

245.1 GB in decimal units is 228 GiB, which is where my 228 figure comes from. 210 GB of it is used and 9 GB is free, which is a bad day but not an unusual one. Here’s where the big developer-tool consumers sit, from du -sh on the paths I check most often:

1
2
3
4
5
6
7
8
9
10
11
12

15G   ~/Library/Containers/com.docker.docker/Data
11G   ~/Library/Developer/CoreSimulator
7.5G  /opt/homebrew            (mostly Cellar: 4.2G)
7.4G  ~/Library/Application Support
6.1G  node_modules under ~/Develop (all projects)
1.1G  ~/Library/Application Support/Code
1.0G  ~/Library/Developer/Xcode/DerivedData
932M  ~/.claude
830M  ~/.npm
688M  ~/.cache
554M  ~/Library/Caches/ms-playwright
485M  ~/.gradle

Leaving out Application Support (mostly app data, not cache), that’s about 44 GB of developer tooling, caches and build artifacts that can be reinstalled or rebuilt. The rest of the 210 GB is everything else on the machine.

One line per category

• Docker — the VM’s disk image doesn’t shrink when you delete something inside it. docker builder prune and docker system prune are the levers.
• Xcode DerivedData — rebuilds itself on the next build. Always safe to delete, rarely worth doing manually because it’s small compared to everything else.
• CoreSimulator — every simulator device you’ve ever booted stays at full size, shut down or not, until you delete the device (not just the OS runtime).
• node_modules — reinstalls from a lockfile in seconds. Only worth touching for projects you’re not actively working in; 6.1 GB across every active project isn’t worth curating.
• Package caches (npm, pip, Homebrew, Playwright, Gradle) — each one is just downloaded artifacts, keyed by version. Safe to wipe, refills on the next install.
• ~/.claude — mostly projects/, the session transcripts Claude Code keeps per project (604 MB of the 932 MB total).

Why it keeps coming back

The categories above are honest but slow-moving. The fast-moving one is Docker’s build cache: one recent cleanup found 12.4 GB of it from rebuilding a single project’s image repeatedly that day — roughly a 12 GB/day rate while that project is under active development. docker builder prune after a rebuild session is the fix; there’s no cache-eviction policy that does it for me.

mediaanalysisd — the background process that runs Photos’ on-device ML indexing — is the other one that moves without warning: I’ve seen it anywhere from 1.8 GB to 5.6 GB across different cleanup sessions. It’s not something I asked for, and it comes back after every clear.

Full Disk Access changes what you can trust

One thing worth knowing before you believe any du number on macOS: without Full Disk Access, some tools get silently truncated results. I hit this with my terminal app — du -x ~ was reporting over a hundred paths as “Operation not permitted” and skipping them entirely, no error banner, just a smaller total than reality. Granting Full Disk Access to the terminal fixed it. If your cleanup math never seems to add up, check that first.

What Scrub automates

The actual manual routine — run du on a dozen paths, decide what’s stale versus what’s mid-project, delete, repeat next week — is exactly the kind of task that should be a tool instead of a habit. I’ve been building one: Scrub, a macOS app with 11 scanners split into three safety tiers:

• Always safe: npm, Yarn, pnpm, and Homebrew caches.
• Usually safe: Xcode DerivedData, Playwright, browser caches.
• Review needed: iOS device support files, simulator runtimes, node_modules, Trash.

Each scanner reports its size, then a preview sheet lets me check or uncheck individual items before anything is deleted — nothing runs unattended. An mtime filter keeps it from flagging a node_modules folder that’s been touched in the last 30 days as stale, which is the mistake I’d otherwise make by hand under time pressure. It’s still a dormant side project, ad-hoc signed for my own machine rather than notarized and shipped, but the scanning and preview logic already replaces the du-and-guess part of every cleanup session I run.

The disk itself isn’t getting bigger. Until it does, this is the routine.

That last part is the constraint that shapes everything else. A rename like this touches two different audiences at once: the JSON coming over the wire, and the Swift source code calling into the library. Both need an old name to keep working for a while.

Two compatibility problems, not one

On the wire: the node itself still accepts old method and field names for a deprecation window, but it now returns the new ones. So the library’s decoders have to accept both witness and validator keys in incoming JSON, while its encoders should only ever write the new key. There’s no reason to keep sending a name the node is phasing out.

In Swift source: any app that does block.witness needs to keep compiling. If a rename ships as a hard break, every downstream app needs a same-day fix or it’s stuck pinning an old version. The library needed the old identifiers to still exist, just marked deprecated, so Xcode shows a warning with the new name to switch to instead of a compile error.

Dual-key decode, canonical-only encode

For every struct with a renamed field, I dropped the synthesized Decodable and wrote a manual init(from:) that tries the new key first and falls back to the old one. Here’s the actual code for AccountValidatorVote (was AccountWitnessVote):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

public struct AccountValidatorVote: OperationType, Equatable {
    public var account: String
    public var validator: String
    public var approve: Bool

    public init(account: String, validator: String, approve: Bool) {
        self.account = account
        self.validator = validator
        self.approve = approve
    }

    @available(*, deprecated, message: "Use init(account:validator:approve:)")
    public init(account: String, witness: String, approve: Bool) {
        self.init(account: account, validator: witness, approve: approve)
    }

    @available(*, deprecated, renamed: "validator")
    public var witness: String {
        get { validator }
        set { validator = newValue }
    }

    enum CodingKeys: String, CodingKey {
        case account, validator, approve
        case legacyWitness = "witness"
    }

    public init(from decoder: Decoder) throws {
        let c = try decoder.container(keyedBy: CodingKeys.self)
        self.account = try c.decode(String.self, forKey: .account)
        self.approve = try c.decode(Bool.self,   forKey: .approve)
        self.validator = try (try? c.decode(String.self, forKey: .validator))
                      ?? c.decode(String.self, forKey: .legacyWitness)
    }

    public func encode(to encoder: Encoder) throws {
        var c = encoder.container(keyedBy: CodingKeys.self)
        try c.encode(account,   forKey: .account)
        try c.encode(validator, forKey: .validator)
        try c.encode(approve,   forKey: .approve)
    }
}

Four things carry the whole migration, and this one struct has all of them: a deprecated init that forwards to the canonical one, a deprecated computed property (with a setter, so old mutating code still compiles) that forwards to the new field, a legacyWitness CodingKeys case that only the decoder touches, and an explicit encode(to:) that never writes it. The try (try? …) ?? … shape matters. The first draft of the plan had (try? …) ?? c.decode(…) with no outer try, which doesn’t compile: the right side of ?? is a throwing autoclosure, and try can’t go inside it on the right of a binary operator. Marking the whole expression with try is the version that works.

Renamed enum cases follow the same idea without needing dual keys, since OperationId encodes as a string and decodes through an explicit switch:

1
2
3

case "witness_update", "validator_update": self = .validator_update
case "account_witness_vote", "account_validator_vote": self = .account_validator_vote
case "account_witness_proxy", "account_validator_proxy": self = .account_validator_proxy

Encoding writes "\(self)", so once the case is renamed, encoding the new name is automatic — only decoding needs both spellings.

The .convertFromSnakeCase trap

The root-level response types (DynamicGlobalProperties, ExtendedAccount) are configured with JSONDecoder.keyDecodingStrategy = .convertFromSnakeCase. That strategy converts a JSON key like current_witness to currentWitness before it’s matched against CodingKeys raw values. So the legacy case has to be spelled in camelCase, not snake_case, or it silently never matches:

1
2
3
4
5
6
7
8
9

enum CodingKeys: String, CodingKey {
    case headBlockNumber, headBlockId, time, genesisTime,
         currentValidator,
         // ...
         inflationValidatorPercent,
         // ...
    case legacyCurrentWitness          = "currentWitness"
    case legacyInflationWitnessPercent = "inflationWitnessPercent"
}

Easy to get backwards once, easy to forget on every struct after that, since it looks wrong next to the actual JSON.

What moved

Five operation structs were renamed with a deprecated typealias each (Operation.WitnessUpdate → ValidatorUpdate, AccountWitnessVote → AccountValidatorVote, AccountWitnessProxy → AccountValidatorProxy, ShutdownWitness → ShutdownValidator, WitnessReward → ValidatorReward), matching the five renamed OperationId cases — the underlying integer values (6, 7, 8, 30, 42) never change, only the JSON string names do. Block.swift renamed witness/witnessSignature to validator/validatorSignature on three types. API.swift renamed two fields on DynamicGlobalProperties and three on ExtendedAccount. Client.swift‘s namespace-routing switch got old and new RPC method names both mapped to validator_api.

None of this needed a version bump serious enough to break anyone building against the library: every old identifier still resolves, with a deprecation warning pointing at its replacement. The only thing that doesn’t work is asking the encoder to write the old key on purpose — deprecated names decode, they don’t re-encode, which is deliberate since sending the new name is always what you want.

I split the work into a 12-task plan, one task per struct or file, each with its own commit, so a decode bug in one place couldn’t hide inside a bigger diff. The last task before merge was a compile-smoke test that references every deprecated typealias, property, and init once, marked @available(*, deprecated) itself so Swift doesn’t complain about the file using the very symbols it exists to protect. If a future cleanup deletes one of those symbols, this test file simply stops compiling, which is the whole point: the moment the deprecated surface actually breaks, this is the file that tells you.

What I’d keep doing

Grep for legacyWitness and @available(*, deprecated, renamed: to find every site that needs cleanup once the deprecation window closes, since both markers are deliberately unique strings that exist nowhere else in the codebase. The rename touched five operation types, three files of response structs, and one routing switch, and the two markers find all of it.