An opinionated bundle of rules, skills, and agents for Claude Code. Toggle it on and the next Claude Code session you launch from a yaw pane inherits a curated working style without touching the config on your disk.
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.
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.
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.
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.
The mechanism is simpler than it probably sounds. When yaw spawns a Claude Code session in Yaw Mode, it:
~/.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.projects/, sessions/, plans/, file-history/. Writes go straight through to home — your --resume list is unaffected.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.
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.
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.
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.
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.
Yaw Mode is the shape you want if:
implement, review, ship-ready available everywhere without installing them into every ~/.claude/skills/.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.
Try Yaw Mode
Yaw Terminal is free to use, no account required. Install from PowerShell on Windows:
irm https://yaw.sh/install-win.ps1 | iex
We write about AI tools and terminal workflows weekly. Subscribe to Token Limit News.