Claude Code Yaw Mode: Overlay Skills, Slash Commands, and typed Support

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 - now updated with the slash command catalog, typed.cloud backend support, and every rule and hook we've added since launch. (The disciplines the overlay encodes -- rule layering, hook-as-policy, scope, capacity, the seven hazards -- are the book-length treatment in Claude Code in Production.)

What's new since launch

If you read the April 22 version of this post, the additions since the April launch are worth scanning before the section-by-section tour:

• typed.cloud is now a supported backend. Run Yaw Mode against the typed launcher's ANTHROPIC_BASE_URL=https://api.typed.cloud + ANTHROPIC_MODEL=typed-xhigh environment and the bundle adapts - model defaults, throttle handling, and self-state verification all branch on the active backend.
• Five new rule files covering corrections (echo back corrected names), scope discipline (don't pivot mid-task), subagent prompts (pass the delta, not the agent's job description), verification (verify load-bearing state before asserting it), and investigation (probe hypotheses yourself; don't hand the user a list).
• 20+ slash commands grouped into code review, session telemetry, memory hygiene, audits, and scaffolding categories. The full set lives on a dedicated slash command reference page, with shareable anchor links per command.
• Mechanical safety hooks. Two PreToolUse hooks - canonical-source-gate.sh and gh-pr-merge-admin-gate.sh - turn two failure modes that previously relied on agent discipline into hard gates.
• New custom sub-agents for changelog drafting, CI watching, MCP bundle building, memory curation, postgres probing, and runbook walkthroughs.
• Platform-specific guidance. The bundle now ships a dedicated Windows rule file covering MSYS path translation, node:path fixture skew in tests, and a documented npm-on-ARM64 segfault workaround.

Full details below.

What's in the bundle

Three 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, the slash commands users invoke at runtime. Third: the hooks, custom sub-agents, and permission defaults that make dispatched work safe and reliable out of the box.

Rule files (merged into CLAUDE.md)

The bundle currently ships 22 rule files. Each starts with the rule, then a Why: line and a How to apply: line - the why is what lets the model (or a person reading it) decide whether an edge case falls under the rule.

• agent-setup - default to the highest-capability model tier at the backend's recommended effort. Pin runtime defaults in project-scoped settings. Yaw skills are invoked via the Skill tool, never as Agent subagent_type.
• corrections - when the user corrects a name (package, branch, file path), echo back the corrected form on the next reference, don't revert to the wrong form within a turn or two.
• deploy - reproducible builds decoupled from your workstation. Run kubectl from your workstation, not the build environment. Secrets via Secret resources, never inline env. Migrations versioned and automatic on boot.
• edit-tool-silent-noop - re-read a file after every Edit; the tool can report success while the file on disk is unchanged. Re-derive the match from the current state instead of replaying the same no-op.
• investigate - probe hypotheses yourself; don't hand the user a list. A diagnostic is tool-call shaped (ssh, curl, grep, journalctl, kubectl) - run it, surface the conclusion, not the possibilities.
• kubectl-debug - long kubectl read pipelines get denied by the auto-mode classifier; restructure into a single short invocation or allowlist the read-only shapes. Never allowlist destructive verbs.
• kubectl-verify-after-apply - always kubectl get pods after a deployment-shaped change. A successful apply only means the API accepted it; a surviving old pod masks failing new ones until the next eviction.
• memory - when stuck, search memory before trying a third approach. Re-read a memory you just wrote if the topic resurfaces. Resolve memory paths via the canonical env-var path, not the per-PTY tmpdir string.
• multi-agent-coordination - you can't message sibling sessions; coordinate through git and non-overlapping scope. When writes are authorized in a fleet, isolate in your own worktree.
• npm - prefer CI-on-tag-push for npm publish. Don't initiate npm login from an agent session; once logged in, write ops are fine. Never copy ~/.npmrc tokens into CI.
• parallel-tool-use - when you need multiple independent reads or checks, emit them in one turn. Dependent calls stay serial; don't batch writes.
• platform-windows - don't pass bare Unix paths to native .exe binaries from Git Bash (MSYS translates them). Test fixture keys must use path.join, not POSIX literals. The npm-on-ARM64 segfault workaround for biome.
• scope - finish the task first; surface the bigger fix separately. Don't read frustration as a redesign mandate. Pre-existing issues you encounter are yours to fix, not "out of scope". Surface a finding once with file:line + fix, then move on. Don't volunteer passive monitoring the user didn't ask for.
• self-state - verify Yaw Mode state by reading the environment, never by guessing from skill names. Don't infer runtime state from the shape of your system reminder. Verify the active API backend the same way (Anthropic-direct vs typed.cloud).
• shared-infra-delete - probe shared-infra dependencies before any destructive call. A repo's "unused" claim means unused by THIS repo, not by the whole account.
• subagent-prompts - pass sub-agents the delta, not the agent's job description. Restating the report format the skill already defines wastes tokens twice (orchestrator's prompt + sub-agent's own loaded definition).
• terminal-output - prefer ASCII substitutes (--, >=, x) over Unicode punctuation in terminal output. On Windows ConPTY, — becomes mojibake.
• throttle-recovery - server-side limits are a valid reason to drop tiers. Mechanism differs by backend - Anthropic-direct throttles trigger Yaw Terminal's "switch to Fast" toast; typed.cloud 429s mean quota exhausted, handled via dashboard top-up.
• verification - ask or verify load-bearing user-domain state before asserting it. Fetch the next piece of context yourself before asking the user to paste more. A justifying comment is a hypothesis, not a fact - verify external claims when the thing it explains is failing.
• verification-budget - verification is necessary; serial re-verification is waste. Budget two cycles per edit and declare done on the first green result.
• workflow-orchestration - default to a multi-agent workflow for substantive work when orchestration is on. Scope the fan-out before spawning; verify findings adversarially before reporting.
• yaw-shortcuts - the reference for every Yaw Terminal keyboard shortcut, translated to the platform key you actually press (Cmd on macOS, Ctrl on Windows/Linux) rather than the internal binding string.

Safety hooks (PreToolUse)

Two hooks turn previously-soft rules into hard mechanical gates. They live in ~/.claude/hooks/ and fire before the gated tool executes.

• canonical-source-gate.sh - blocks Edit/Write to paths under yaw-mode-* overlay tmpdirs. Without it, edits to skill/agent/rule files through the per-PTY junction can detach the hardlink and the change lands on a throwaway copy while the durable source stays unchanged. Confirmed twice in May 2026 - edits were lost on session end while the agent confidently reported them as applied. The hook surfaces the canonical path to retry at. Test-mode bypass: inline # canonical-override comment or YAW_CANONICAL_OVERRIDE=1.
• gh-pr-merge-admin-gate.sh - blocks gh pr merge --admin unless the invocation carries an inline # yaw-admin-authorized marker or YAW_ADMIN_AUTHORIZED=1 in env for that one command. Origin story: on 2026-04-16 an agent admin-merged a ~6,000-line deletion PR with zero CI reports, after GitHub's policy explicitly refused the normal merge. The hook makes "stop and ask" the default; the carve-out is per-invocation, not session-wide.

Skills (Claude Code slash commands)

The bundle ships 25 skills - invoked as /yaw-* slash commands. Their bodies don't ride in the persistent system prompt; the model sees only names and one-line descriptions until you invoke one.

Full reference with shareable links: the complete slash command reference.

Custom sub-agents (dispatch surfaces)

Sub-agents read whatever they need in their own context window and return a digest to the parent. The bundle ships:

• full-pass - end-to-end sweep over a module, returning solid / fragile / worth fixing now / file for later.
• review-loop - independent bug/perf/UX review on recent changes. Punch list with file:line.
• ship-ready-audit - branch shippability check covering golden path, error UI, loading, empty states.
• ci-watch - polls a gh run to completion, pulls failing logs, identifies the root cause.
• changelog-writer - generates release notes from a git range, groups commits by area.
• mcp-bundle-builder - scans package.json + code for API integrations, proposes which @yawlabs/*-mcp servers to load.
• memory-curator - scans transcripts for memory-worthy moments. Proposes; never auto-writes.
• postgres-prober - read-only SQL against a Yaw Labs prod RDS via kubectl-exec. Refuses INSERT/UPDATE/DELETE/DROP/ALTER.
• runbook-runner - walks you through the current project's incident runbooks step by step. Read-only checks run automatically; destructive steps gated behind confirmation.

How the overlay actually works

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

1. Creates a temp directory under your platform's tmp root, namespaced by process id + pty id so no two overlays can ever collide.
2. 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.
3. 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.
4. Merges the Yaw CLAUDE.md into the overlay's CLAUDE.md under a heading that identifies it: "## Yaw Mode - added instructions".
5. 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.

Running Yaw Mode against typed.cloud

Yaw Mode is wire-compatible with any Anthropic-API-shaped backend. As of May 2026, the most common alternative we run against is typed.cloud - an AI CLI that ships ~40% more tokens per dollar than Claude Pro/Max at the same monthly price, with cheaper overage and monthly billing instead of 5-hour rolling windows. (See typed Is Live for the full pricing and migration breakdown.)

You don't need a special Yaw Mode build to use it. The typed launcher sets the right environment variables before spawning Claude Code:

export ANTHROPIC_BASE_URL=https://api.typed.cloud export ANTHROPIC_AUTH_TOKEN=<your typed key> export ANTHROPIC_MODEL=typed-xhigh

When Claude Code launches from a Yaw pane with those vars set, Yaw Mode picks up the backend automatically. Three things change:

1. Model defaults shift. The agent-setup rule branches on the active backend - on Anthropic-direct it pins claude-opus-4-8 at xhigh; on typed it pins typed-xhigh (the second-from-top of typed's five tiers: typed-max / typed-xhigh / typed-high / typed-medium / typed-low). Same shape - default to the flagship at the recommended effort, reserve max for genuinely hard problems.
2. Throttle handling diverges. A 429 from Anthropic means rate-limited, and Yaw Terminal offers to drop Opus 4.8 to Opus 4.6 + Fast across every pane (the recovery target stays on 4.6 because /fast is only valid there). A 429 from typed means monthly quota exhausted, handled via dashboard one-click top-up ($5 / $10 / $20 / $50) or auto-top-up if pre-enabled. The bundle's throttle-recovery rule covers both branches.
3. Self-state checks updated. When the model is asked "which model are you?", the bundle's self-state rule has it check $YAW_MODE_PROVIDER and $ANTHROPIC_BASE_URL before answering. On typed it reports the typed model ID, not the Claude model the system prompt was trained to self-identify as.

Both can coexist on the same machine. Open one tab against typed, another against Anthropic-direct; same conversation history, different upstreams. typed disable bounces the launcher back to your Claude subscription if you want to spread spend across both.

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 25 skills plus 9 sub-agents. 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. That's the difference between a 5KB persistent footprint and a 200KB one.

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 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 first month.

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.

Mechanical gates on top of the rules. The two PreToolUse hooks (canonical-source-gate.sh and gh-pr-merge-admin-gate.sh) turn "the agent will remember to do the right thing" into "the agent gets blocked if it doesn't." Documented in the Safety hooks section above.

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.

The bundle ships 25 skills, invoked as /yaw-* slash commands. Their bodies don't ride in the persistent system prompt; the model sees only names and one-line descriptions until you invoke one. These are the ones you'll reach for most - the full slash command reference lists all 25, with shareable per-command links.

See the complete slash command reference →

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.

To run Yaw Mode against typed.cloud instead of the Anthropic API: install the typed launcher (one curl), then enable Yaw Mode in Yaw Terminal. Each pane spawned via t or typed inherits the typed env vars; Yaw Mode picks them up automatically.

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 /yaw-implement, /yaw-review, /yaw-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.
• You want to try typed.cloud as an alternative backend without rewriting your CLAUDE.md to account for the different model identifiers and throttle behavior.

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.

Frequently asked questions

Published by Yaw Labs.

Related Articles

• Best Terminal for Claude Code
• Your CLAUDE.md Is Lying to Your Agent
• typed Is Live: AI CLI With More Volume And Cheaper Extra Usage
• How to Use AI CLI Tools