Claude Code Yaw Mode - NFHN Reader

Claude Code ships with a config directory at ~/.claude/. It's where your CLAUDE.md lives, your skills, your agents, your permission allowlists, your OAuth credentials, and the JSONL transcripts for every session you've ever run. It's a deeply personal directory by the time you've used Claude Code for a few months - and anything that wants to change how Claude Code behaves has to either edit that directory in place or teach you to maintain a second config somewhere else.

Yaw Mode is a third option. It's a per-session overlay that layers an opinionated bundle on top of your ~/.claude/ without mutating it. Claude Code inside the overlay sees your CLAUDE.md plus ours, your skills plus ours, your permissions merged with a safe default set for sub-agents, and conversation history that writes straight through to your real home - so every session still shows up in --resume exactly where you'd expect. When the session ends, the overlay is gone. Your real config is untouched.

This post is the "what's in the box, how does the box work, how do I open it" tour.

What's in the bundle

Two kinds of content ride along with Yaw Mode. First: a set of rule files that get @-imported into a merged CLAUDE.md, so the model's baseline instructions pick them up on every turn. Second: a curated skill set, plus the hooks and permission defaults that make dispatched sub-agents work out of the box.

Rules (merged into CLAUDE.md)

agent-setup - pin the highest-capability model tier at top effort. Don't drop effort unless latency dominates correctness.
code-quality - no speculative abstractions. Three similar lines beats a premature helper. Validate at system boundaries; trust internal code.
deploy - reproducible builds decoupled from your workstation. Secrets via Secret resources, never inline env. Migrations run versioned, automatically, on boot.
git - new commits over amending published history. No hook-bypass flags without explicit permission. No git add -A - bulk-add sweeps in .env files.
npm - publish via CI on tag push, never locally. Don't run npm login or npm publish from an agent session. Keep deprecation messages short and actionable.
positioning - never invent capability gaps in competitors. A product isn't done until the full UX is done.
self-state - verify Yaw Mode is actually on by reading $YAW_MODE, not by guessing from skill names. Don't refuse work claiming you're in an overlay you haven't verified.
terminal-output - prefer ASCII substitutes (--, >=, x) over Unicode punctuation in terminal output. On Windows ConPTY, — becomes ΓÇ—. Real examples happen.
testing - integration tests hit a real database, not mocks. UI work isn't done until you've used it in a browser. Zero failing tests before commit.

Each file starts with the rule, then a Why: line and a How to apply: line. That structure is deliberate: the why is what lets the model (or a person reading it) decide whether an edge case falls under the rule or not. A rule without context gets applied mechanically; a rule with context gets applied correctly.

Skills (curated subset)

The bundle ships a small set of skills that together cover the "finish a thing" loop - plan, implement, review, ship-ready. Specifically:

implement - execute an agreed plan end to end. Run checks. Confirm it works before declaring done.
review - scan recent changes for bugs, performance issues, UX issues. Return a punch list with file:line and suggested fixes.
ship-ready - audit a branch for shippability. Golden path, error UI, loading states, empty states, destructive confirmations, hygiene. Returns done / missing / blocked.
coverage - identify untested branches, edge cases, failure paths. Returns missing test cases with rationale.
full-pass - end-to-end sweep over a module or subsystem. Read everything carefully, report surprises.
simplify - review changed code for reuse, quality, efficiency, then fix what it finds.

These are intentionally not exhaustive. Yaw Mode's job is to give you the discipline layer; your own ~/.claude/skills/ is where project-specific or personal skills live. In augment mode (below), both sets show up.

How the overlay actually works

The mechanism is simpler than it probably sounds. When yaw spawns a Claude Code session in Yaw Mode, it:

Creates a temp directory under your platform's tmp root, namespaced by process id + pty id so no two overlays can ever collide.
Hardlinks the small identity files from your ~/.claude/ into the overlay: settings.json, .credentials.json, history.jsonl, ~/.claude.json. Hardlinks mean Claude Code reads the real file; anything it writes through the same inode reaches home directly.
Junctions (on Windows) or symlinks (elsewhere) the conversation-transcript directories: projects/, sessions/, plans/, file-history/. Writes go straight through to home - your --resume list is unaffected.
Merges the Yaw CLAUDE.md into the overlay's CLAUDE.md under a heading that identifies it: "## Yaw Mode - added instructions".
Spawns Claude Code with CLAUDE_CONFIG_DIR=<overlay>. Claude Code reads its config from the overlay and never touches your real ~/.claude/.

On session exit: a guarded sync of the overlay's .claude.json back to home (more on the guard below), a live-synced copy-back of refreshed OAuth credentials, and then the overlay directory is deleted. A per-session overlay, created from scratch, torn down when you're done. No accumulating state, no stale config from yesterday's session, and - critically - no risk of the overlay's teardown reaching into your real home.

Augment vs Fresh

Two modes. Both do the same overlay dance; they differ in what they start with.

Augment (default): your ~/.claude/ gets layered underneath the Yaw bundle. Your skills, your agents, your settings all participate. The merged CLAUDE.md is your CLAUDE.md plus Yaw's. This is the "I already have my Claude Code set up the way I like it, I just want Yaw's rules and skills on top" shape.

Fresh: only the Yaw bundle. Your ~/.claude/ is ignored for skills, agents, CLAUDE.md, settings. Conversation transcripts still route through home so you don't lose history, but the working configuration is exactly what the bundle ships - nothing more, nothing less. This is the "I want a clean slate to run the Yaw discipline against" shape, or the "I'm reproducing behavior someone else saw in Yaw Mode and need to eliminate my personal config as a variable" shape.

Both modes expose a runtime marker - $YAW_MODE is set to augment or fresh in the session env. A bundled rule tells the model to verify its own mode from that env var rather than inferring from skill names (which overlap with Claude Code built-ins and produce confident-sounding wrong answers). Small detail, but the kind of thing that matters when you're debugging why a session behaved unexpectedly.

Why an overlay

Because you shouldn't have to choose between your setup and ours. A replacement config would make you pick one; an overlay lets you run ours for the sessions where you want it, and your baseline the rest of the time. Opening a non-Yaw-Mode tab in yaw gets you vanilla Claude Code, reading your real ~/.claude/, same as you'd see anywhere else. Opening a Yaw-Mode tab gets you the layered version. Two tabs side by side, same conversation history, different working styles. That's the whole pitch.

It also means when Claude Code ships a new feature, you get it the day it lands - nothing in Yaw Mode is a re-implementation of Claude Code itself. The overlay is strictly additive to the official binary.

Context discipline, pre-baked

Anthropic recently framed agent quality at scale as "the discipline of deciding what belongs in Claude's context" and grouped the practical patterns into four pillars. Yaw Mode wasn't designed against that talk - the overlay predates it - but the four pillars line up cleanly with how the bundle was already shaped, which is the more useful kind of validation. We didn't add primitives Claude Code doesn't have; we shaped Yaw Mode to work with the ones it does.

1. Tool search - keep unused tool and skill schemas out of context. The Yaw bundle ships seven skills - yaw-implement, yaw-review, yaw-ship-ready, yaw-coverage, yaw-full-pass, yaw-status, yaw-help - plus three sub-agents (full-pass, review-loop, ship-ready-audit). Their bodies don't ride in the persistent system prompt - they load only when invoked. The model sees their names and one-line descriptions; the multi-thousand-token instructions inside are paged in on demand.

2. Programmatic tool calling - keep intermediate tool results out of context. The Yaw sub-agents are dispatch surfaces, not paraphrasers. A full-pass over a subsystem reads dozens of files in its own context window and returns a digest - solid / fragile / worth fixing now / file for later - to the parent. The 50,000 tokens of file content stay on the sub-agent's side of the wall; the parent sees the verdict.

3. Compaction - keep stale turn history out of context. Compaction is a Claude Code primitive; what Yaw Mode contributes is making sure the cached prefix actually survives across sessions. The bundle is built to be cache-stable: rule bodies don't interpolate dates, session counters, or environment markers, and edits prefer additive changes over reordering. That keeps the largest cacheable region of the system prompt hashing identically across releases, so users hit the cache rather than re-paying full prompt cost on every new session.

4. Advisor strategy - cheap executor + capable advisor on hard sub-problems. Yaw's sub-agents are the dispatch surface for this pattern. A routine session can run on a fast tier and still escalate the genuinely hard sub-problems - an architectural review, an ambiguous debug, a ship-readiness audit - to a sub-agent pinned to a higher-tier model. The bundle's agent-setup rule has the conventions; the sub-agent boundary makes them mechanically expressible.

The framing isn't ours, but the architecture it validates is. If you want the talk's full shape, search Anthropic's developer talks for "Getting more out of the Claude Platform" - the four pillars are the spine.

The safety story

An overlay that shares your conversation history via junctions, hardlinks, and sync-back is a mechanism with real blast radius. "Yaw Mode broke my Claude Code history" would be an unrecoverable user experience. So the safety properties are worth spelling out, because we've done the work to make them real - including finding and fixing two data-loss edge cases in the last week.

Teardown can't touch your conversation history. Every recursive delete of an overlay directory - at session end, at startup sweep of stale overlays, at legacy-format cleanup - first unlinks the known junction points and then removes the overlay. The recursive rm sees only an empty shell; the junction targets (~/.claude/projects/, sessions/, etc.) cannot be reached, regardless of whether the Electron-bundled Node.js in a given release follows junctions or not. This is defense in depth against a behavior that shifts quietly across Node versions.

Concurrent overlays don't race each other to data loss. Running four Yaw Mode tabs in parallel used to mean only the first-to-exit's new projects landed in home's .claude.json - the rest hit a stale-snapshot guard and were silently dropped on teardown. Now the guard falls back to an additive merge: new projects get unioned in, shared projects keep home's newer values (no regression on last-session stats), counters take the max. Every overlay's additions reach home, even when four of them exit in quick succession.

Before every sync-back, we snapshot. A timestamped copy of your home .claude.json lands in ~/.yaw-claude-json-backups/. Seven are kept, pruned by age. If anything ever does slip through - and "never" is a claim we're unwilling to make about filesystem-level code on Windows - you have recovery points.

Ghost entries get cleaned up automatically. A project entry in .claude.json whose transcript directory doesn't exist on disk clutters --resume and select-to-nothing. Sync-back filters them out, so the picker only lists projects that actually have sessions to resume.

Everything is covered by tests. The junction-follow, concurrent-overlay, and ghost-filter cases all have regression tests pinned at the source level - they trip the moment anyone reintroduces the pre-fix behavior. If a future Node bump changes the filesystem primitives underneath us, those tests catch it in CI before it reaches anyone.

Turning it on

Settings → Yaw Mode → toggle to Augment or Fresh. The bundle is downloaded on first use; subsequent sessions reuse the local copy. You can preview the merged CLAUDE.md from the same settings panel - useful for confirming what the model will actually see on its first turn.

Once it's on, the next Claude Code session you launch from any yaw pane inherits the overlay. Existing sessions are unaffected until you close and re-open them. Toggling back to Off reverts to vanilla Claude Code with no residue - the overlay directory was always temp-scoped to that session anyway.

What it's for, put plainly

Yaw Mode is the shape you want if:

You've written down a set of rules you'd like Claude Code to follow across projects, and you're tired of copy-pasting them into every repo's CLAUDE.md.
You want skills like implement, review, ship-ready available everywhere without installing them into every ~/.claude/skills/.
You want an opinionated baseline for sessions where that's useful, and a clean baseline for sessions where it isn't, and you don't want to maintain two Claude Code installations.
You've experienced Claude Code's config directory as a thing you've slowly accreted, and you'd prefer a per-session overlay that doesn't accrete.

It's not the shape you want if Claude Code's defaults already match the working style you want, or if you prefer to edit your own CLAUDE.md directly. Both are valid. Yaw Mode is a convenience, not a requirement.

Published by Yaw Labs.