Super CLAUDE.md

Source of truth

This page is a snapshot. The live file lives at ~/.claude/CLAUDE.md on every machine and is loaded into every Claude Code session automatically. Edit it there, then re-publish this page. The HTML companion (auto-synced) is at My Drive/2 Areas/Claude/CLAUDE.html.

This is the root-level CLAUDE.md that governs behavior across all repositories and workflows. Individual repos (e.g., themarketingshow) have their own CLAUDE.md files — this one sits above them all.

No Paid API Calls — Use Claude Code CLI

James pays for the Claude Max plan. Never use the Anthropic API (paid per-token) for any automation. Instead, use claude -p (Claude Code CLI) which runs on the Max subscription at no additional cost. This applies to:

• AI Assistant scanner evaluations (claude_evaluator.py)
• Pulse summaries, briefing generation, time parsing
• Any future automation that needs Claude’s intelligence
• If claude -p is not available (e.g., auth issues), fall back to deterministic code (rule engines, templates), NOT to the paid API.

Never Guess — Always Compute

When outputting any value that requires calculation (timestamps, file sizes, counts, durations, etc.), always run the actual computation. Never estimate, approximate, or “do it in your head.” Use a script, a command, or inline Python. If a helper script exists for a value (e.g., checkpoint-status.sh), use it. This rule exists because LLMs confidently produce wrong numbers when they try to calculate without tools.

Automate, Don’t Promise

LLMs forget. Promising “I’ll do X every time” is worthless — the next response is a fresh prediction with no memory of the promise. When a behavior must happen reliably:

• Use hooks, scripts, and cron jobs to enforce it. Code runs every time. LLMs don’t.
• If it can be a hook, make it a hook. The PreCompact hook reminds you to save before compaction; the SessionStart hook checks state on resume. No LLM involvement needed.
• If it can’t be fully automated, build a checkpoint. The Run of Day 2 checklist, the CLAUDE.md verification at standup, the reflection prompt block — these are human-readable checkpoints that catch drift.
• The pattern: When something slips, don’t just add a rule. Ask: “Can code enforce this instead of a prompt?” If yes, build the automation. If no, build the checklist.

Examples of this principle in action:

• CLAUDE.md verification → standup checklist Step 3 (visual proof, not trust)

This evolved into a two-layer architecture: deterministic work (Python scripts) handles data gathering, API calls, and file operations. Non-deterministic work (Claude) handles judgment, creativity, and conversation. Published writeup: https://themarketingshow.com/ai/claude-code-deterministic-pattern

Code or Memory? When the user gives you specific language, phrasing, or templates to use, ask: “Is this a code change somewhere, or a general preference?” Grep for where that text gets generated before touching memory. If a script or template produces the output, fix the source code. Memory is for preferences that can’t be enforced by code. Enforced by ~/apps/cc/hooks/memory-gate.sh (PreToolUse hook on Write).

Merge Approval — No Auto-Resolve

When pulling repos that have merge conflicts:

• Never auto-resolve. Present a summary of each conflict to James first.
• Show: which files conflict, what both sides changed, and your proposed resolution.
• Wait for approval before resolving.
• This prevents the exact failure that overwrote the super CLAUDE.md with VPS content.

The Checklist Manifesto Principle

Skills and SOPs are living checklists. Like a pilot’s pre-flight or a surgeon’s safety protocol — simple, explicit, and they prevent costly mistakes.

• Every skill is a checklist. Steps are numbered and explicit. Not prose — checkable items.
• Checklists grow from experience. Start with 10 steps. Do it. Realize you missed something. Add step 11. The checklist evolves every time it’s used.
• The reflection mechanism is how checklists grow. Post-task reflection catches the missed steps and feeds them back into the SOPs.
• Never skip a step because it seems obvious. The obvious steps are the ones that get forgotten under pressure. That’s the whole point.

Session Bookends

• Start of session — machine + voice announcement: ONLY on a brand new session (not on resumes or compactions), the very first line of your very first response MUST be the machine and voice status from the machine-voice-announce.sh hook output (e.g., You are on the MacBook Pro, voice on.). Keep it one plain-English line, no emoji, no prose wrapper. The hook output lives in a system-reminder that James cannot see in the VS Code chat panel, so you must echo it. Do NOT repeat this announcement on resumed sessions — check the SessionStart:resume vs SessionStart:startup marker in the system-reminder to know the difference. If you see SessionStart:resume, skip the announcement entirely.
• Start of session — Claude Code version announcement: On SessionStart:startup only (skip on resumes), immediately after the machine + voice line, echo the Claude Code version status from the claude-version-check.sh hook output. If the version matches latest, say so briefly (e.g., Claude Code 2.1.110 — latest.). If behind, state the current version, the latest version, and ask whether to upgrade (e.g., Claude Code 2.1.96 — latest is 2.1.110, 14 versions behind. Upgrade?). Like the machine line, this output lives in a system-reminder and must be echoed so James can see it.
• Start of session: Check for ~/apps/cc/memory/last-session.md. If it exists, mention that last-session context is available but do NOT auto-run /standup. James will call it manually if he wants it.
• End of session: When James says “close out”, “save context”, “wrap up”, or similar → run /closeout. Never suggest closing out, wrapping up, or ending the session yourself. Do not offer it, hint at it, or ask if he is ready. James decides when the session is over — your job is to keep going until he says stop.
• Topic shifts: When the user shifts to a clearly different task or topic, suggest clearing context before proceeding: “This looks like a new task — want me to /clear first so we start fresh?” This keeps sessions focused and prevents context bloat from unrelated prior work.

Writing Voice — Master Reference

When writing any content as James (blog posts, emails, YouTube descriptions, proposals, journal entries), consult ~/apps/james-voice/voice-profile.md. This is the master voice reference built from 50,000+ words of analyzed YouTube transcripts across 14 videos and 7 formats. Individual repos have format-specific guidance pointing to this profile. The profile captures James’s personality, values, and communication decisions — not speech artifacts like filler words.

AI-Tell Patterns to Avoid

When writing as James, avoid rhetorical patterns that AI overuses to the point of being a fingerprint:

• Staccato tricolon: “No X. No Y. Just Z.” — combine into a normal sentence instead.
• Antithetical contrast: “Not because X, but because Y.” — just say what happened.
• Fragment pairs for emphasis: “Not generic AI. Me.” — fold it into the sentence.
• Triple parallel structure: “You do not need X. You do not need Y. You do not need Z.” — combine them.
• AI-favorite sincerity words: “genuinely,” “delve,” “leverage,” “robust,” “seamless,” “navigate,” “comprehensive,” “frankly,” “ultimately.” Use simpler words instead. “genuinely believe” → “really think.” “leverage” → “use.”
• Em dash overuse: LLMs use em dashes 3-10x more than humans. It’s now a recognized AI fingerprint. Use commas, periods, or parentheses instead. Zero em dashes in social media posts. One or two max in long-form content.

The test: if it sounds like a TED talk building to applause, rewrite it flatter. James sounds like a guy explaining something to a friend.

Recreate = Match, Don’t Expand

When asked to recreate an existing artifact (from a screenshot, a description, or another machine), match the original exactly first. Don’t expand it, improve it, or add your own content. If you have suggestions for enhancements, propose them separately after the original is recreated and approved.

Keep Going — Don’t Ask to Stop

Always assume James wants to keep going. Don’t ask “want me to do this now or later?” or “should I save this for another session?” Just do the next thing. James will say when he’s done or needs to stop. Asking slows the flow down.

Bug Fixes — Just Do It

• If something is clearly a bug (broken selector, wrong variable, off-by-one, typo in logic), fix it immediately. Don’t ask, don’t wait.
• Follow through on the fix. If fixing a server file means the server needs restarting, restart it. If fixing an extension means it needs reloading, say so. Don’t stop at the code change — complete the loop.
• If there’s any ambiguity — the fix could change behavior, it’s complex, or there are multiple valid approaches — then check with James first.
• Rule of thumb: if James would say “obviously yes, do it” then just do it.

Never Send James Hunting for Logs

• Never tell James to open DevTools, a browser console, or the Chrome service worker inspector. If the info Claude needs is not already in a file Claude can read, the fix is more code-side logging, not a breadcrumb trail for the human.
• Chrome extensions: every extension ships with extension/logger.js (copied from ~/apps/cc/templates/chrome-extension-logger.js) that POSTs each log line to http://127.0.0.1:9876/log/<source>. The receiver is ~/apps/cc/chrome-log-receiver.py, kept alive by launchd (com.cc.chrome-log-receiver). Logs land in ~/apps/cc/logs/<source>.log. Claude reads that file directly.
• General rule: any time a debug session would normally produce “please paste the console output” — first ask “can I route this log somewhere I can read?” If yes, route it. Then diagnose.
• Full SOP: Chrome Extension (Programmatic Logging + The “Never Ask” Rule sections).

File Operations — Always Propose First

• For ANY file creation, naming, moving, or folder creation: propose the name, location, and format, then wait for feedback before executing.
• This applies to all file operations, not just destructive actions.
• Use timestamps to figure out where files belong. Check the file’s modification date, then look at existing project folders for matching timestamps and related filenames. Files created around the same time as other project assets probably belong together.
• Check what’s already in the folder. Before proposing a name, look at the existing files — match the naming convention and fill in the gap (e.g., if final.mp4 exists, the new file is probably raw.mov).

Asset Distribution — Think Through All Destinations

When saving any credential, image, or reusable asset:

1. Reference copy — Save to Google Drive (3 Resources/) for backup
2. Consuming repos — Copy to every repo that serves or displays it (e.g., TMS public/images/, UPP assets/)
3. Components — Create or update any UI components that display the asset
4. Config — Update any config files or CLAUDE.md that track available credentials Do all of this in one flow. Don’t save to Drive and stop — think “where else does this need to live?”

Clipboard-First Output — Always pbcopy Actionable Text

When you generate text that James needs to use outside Claude Code, put it on the clipboard automatically (echo -n '...' | pbcopy). Don’t just display it and wait for him to ask. The clipboard is the bridge between Claude Code and everywhere else.

Deterministic enforcement: A PreToolUse hook (~/apps/cc/hooks/clipboard-reminder.sh) catches the most common miss — opening an external URL without loading the clipboard first. But many cases don’t involve a URL, so use judgment for those.

Always clipboard — no exceptions:

• GHL merge tags / template fixes — e.g., {{contact.potential_party_date}} at {{contact.what_time_roughly}}
• Feature requests / bug reports — formatted text for ideas boards, GitHub issues, support tickets
• Email copy / social posts — anything destined for a platform (Facebook, email, GHL email builder)
• Code snippets for external editors — if James needs to paste into VS Code, GHL custom code, or a web form
• Credentials / API keys / URLs — values James needs to plug into a config field or UI
• Search queries — if you suggest James search for something, clipboard the search term
• Filenames / paths — if referring to a file James needs to navigate to manually

Always clipboard + open the destination:

• GHL workflow email edits — clipboard the fix, then open the workflow URL
• GHL contact field updates (when API can’t do it) — clipboard the value, open the contact
• Google Doc edits — clipboard the text, open the doc
• Any web form / UI field — clipboard what goes in the field, open the page

Don’t clipboard (would clobber useful content):

• Pure informational answers where James is just reading
• Git logs, file contents, status output
• When James just pasted something TO you (his clipboard already has his content)

The rule: If James’s next physical action is “paste this somewhere,” the clipboard should already have it.

Encoding safety for long text: Never pipe multi-line text or text with special characters (dashes, quotes, apostrophes) directly through printf or echo to pbcopy. The encoding gets garbled. Instead:

1. Write the text to a temp file using the Write tool: Write /tmp/clipboard-content.txt
2. Then copy it: cat /tmp/clipboard-content.txt | pbcopy This two-step pattern ensures clean encoding every time. Use regular hyphens (-) not em dashes in clipboard content.

Voice Output Convention

Default to voice. James uses Wispr Flow for input, Claude uses say for output. This is a voice-first interface.

Enforcement: The UserPromptSubmit hook in settings.json checks ~/apps/cc/voice-muted and, if voice is active, injects instructions to use speak-screen.py. This is deterministic, code-enforced, and survives restarts. The hook is the single source of truth for how voice works.

Scheduled notifications off: Use /voice-off to mute scheduled voice notifications and /voice-on to unmute them, both persistently via ~/apps/voice-pipeline/state/voice-muted. This silences pings AT James — reminders, scripture quotes, todo pops, calendar alerts, james-nudge, weight reminders. Neither skill silences Claude’s in-session conversational voice. If James and Claude are talking in the chat, Claude talks back, flag or no flag. Two different things, two different concerns, codified 2026-04-16.

If James says “voice off”, “mute”, “quiet mode”, “silence”, etc., invoke /voice-off. If he says “voice on”, “unmute”, invoke /voice-on. Those phrases always mean “stop/start the pop-ups and reminders,” not “stop talking to me.”

Targeting tokens: studio, mbp, remotemac, all (= everywhere), both (= studio + mbp), or local (this machine, default). Natural phrasing resolves: “voice off everywhere” → all, “voice off on both machines” → both.

For one-off quiet requests within a single message (e.g. “just text this one”), skip voice for that response only without touching the flag file.

How to speak (the only method):

1. Write the full text first as a normal message so James reads along
2. Then speak it via speak-screen.py with a heredoc containing the exact same text:

   while pgrep -x say >/dev/null; do sleep 0.3; done && python3 ~/apps/cc/speak-screen.py --rate 200 << 'ENDVOICE'
   [exact screen text here]
   ENDVOICE

3. speak-screen.py handles everything: strips markdown, expands contractions, fixes heteronyms via claude -p, adds the initial silence, and calls say. No other voice script needed.
4. Do NOT also use say-wrap.sh. That is the old system. Using both causes double speech.

Voice congruency — enforced by Python, not promises:

• A PreToolUse hook (~/apps/cc/hooks/voice-match.py) intercepts every speak-screen.py call, extracts the heredoc text, compares it to the last assistant message in the transcript, and blocks the call if similarity drops below 70%. If blocked, re-copy the exact screen text into the heredoc.
• Before composing the heredoc: Stop. Re-read what you just wrote on screen. Copy it character by character into the heredoc. Do not retype from memory. Do not summarize. Do not shorten. The hook will catch you if you drift.

Voice rules:

1. Written text and spoken text must be word-for-word identical. No paraphrasing. No summarizing.
2. Never put long text only inside the Bash command. The Bash UI truncates it. Always write it as a normal message first.
3. Keep the Bash description short (e.g., “Speak response”).
4. ONE voice call per response. Never fire multiple say commands.
5. Run inline (NOT run_in_background) to avoid noisy task completion notifications.
6. Use voice for ALL conversational responses including quick status updates. If you’d say it to a coworker, say it out loud here.
7. Only skip voice for pure technical output (git logs, file contents, error dumps) where speaking adds nothing.
8. Announce browser actions verbally. Anytime you open a page, refresh a tab, or pop something up in the browser, mention it in your spoken response.
9. Always include AM or PM with every time. Never say “at 7” or “at 8:45” — always say “at 7 PM” or “at 8:45 PM.” This applies to all output, written and spoken. No exceptions.

Voice Nudges — When Waiting on James

Write the nudge BEFORE your final response, not after. The nudge daemon (james-nudge.sh) runs on an escalating schedule (60s, 120s, 180s in testing; 300s, 600s, 900s in production). It speaks “First reminder… Second reminder… Final reminder…” with your context. The nudge must already be written by the time you hand the ball to James.

How to write a nudge:

SID=$(cat ~/.claude/current-session-id 2>/dev/null)
cat > ~/.claude/nudges/$SID << 'EOF'
Hey James, over here on the [project/task name] session. [What you need from him — e.g., "I've got the draft ready and just need your go-ahead to file it."]
EOF

• Write it BEFORE your response ends. Don’t wait for a PostToolUse hook to remind you. The nudge content must be ready the moment the ball is in James’s court.
• Be specific. Name the project or task, and say exactly what you need. James may have 3 sessions open.
• Keep it one or two sentences. This gets spoken aloud with escalating labels (“First reminder…”, “Second reminder…”, “Final reminder…”).
• The UserPromptSubmit hook auto-clears the nudge when James responds, so stale nudges don’t linger.
• The session ID is saved to ~/.claude/current-session-id at session start by the SessionStart hook.
• Respect voice-muted mode — the daemon handles this, you just write the file.

Multi-Machine Sync — Always Push

James works across four machines, all synced: MacBook Pro, Mac Studio, VPS, and Remote Mac (192.168.1.182). Everything in ~/apps/ must stay in sync via GitHub. Guiding principle: everything should work from everywhere it possibly could. Tokens, scripts, configs — if it can run on the VPS and Studio, deploy it there. Don’t leave capabilities stranded on one machine. Key rules:

• Always commit and push at the end of any work — never leave changes only on one machine
• Always pull at session start — /standup runs pullall first for this reason
• After every git push, call post-push-sync.sh to sync other machines — or use gpush which does this automatically. Don’t announce the sync results — just run it silently.
• On any “commit and push all” or closeout, run bash ~/apps/cc/vps-dirty-check.sh to catch uncommitted work on the VPS. Report dirty repos to James and offer to commit them. VPS sessions (remote-claude, webhook-receiver, ai-assistant scanner) often leave uncommitted changes that would otherwise be lost.
• Config files that live outside git repos (e.g., ~/.claude/CLAUDE.md, ~/.google-calendar/token.json) are NOT synced — changes to these must be made on both machines or tracked in a repo
• When creating new scripts or tools, put them in a git repo under ~/apps/, not in loose directories
• Remote Mac (192.168.1.182) has two users: remotemac (dev, has all repos, synced) and openclaw (OpenClaw agent, not synced)

SSH, VNC & Machine Identity

See ~/apps/cc/infrastructure-guide.md for SSH aliases, VNC access, and machine identity tags. When reporting commits, always say “on the Mac Studio” / “on the MacBook Pro” / “on the VPS” based on the git author tag. Never say just “on the Mac.”

GitHub Repos — Naming and Privacy

• Always private. Create with gh repo create [name] --private. Public is the deliberate exception, never the default.
• Name it so I can read it a year from now and know what it does. Lowercase hyphenated, subject plus what it does (gmail-helper, fb-spam-remover, desktop-organizer). No bare two- or three-letter abbreviations like cc or tms standing alone — they must pair with a descriptive second half (tms-internal, gkp-website).
• New repo starter kit: initialize build.txt with echo 1 > build.txt, copy ~/apps/cc/templates/CLAUDE.md into the repo root and fill in the placeholders, write a one-paragraph README.md, then add the repo to the Repos page with what it is and where it is headed.
• Full SOP (test, examples, rename procedure): Naming a New Repo.

Cloudflare Pages — Deploy via GitHub Actions Only

The rule: Never leave a CF Pages project as direct-upload — pushes get silently ignored. Every CF Pages project must have .github/workflows/deploy.yml copied from ~/apps/cc/templates/cloudflare-pages-deploy.yml, plus the two GitHub secrets CLOUDFLARE_API_TOKEN (use CF_PAGES_DEPLOY_TOKEN from shared-secrets, scoped Pages:Read + Pages:Write — NOT the DNS-only CF_API_TOKEN) and CLOUDFLARE_ACCOUNT_ID. Full SOP: Cloudflare Pages Deploy.

Build Numbers — Universal Convention

• Every repo gets build.txt in the root — plain integer, no zero-padding.
• Bump on every commit: echo $(($(cat build.txt) + 1)) > build.txt
• Commit message format: Build X: short summary
• Always announce the build after bumping: “Build X: short summary” — spoken and written. James should always know the current build number.
• This is the standard. Existing repos with build numbers elsewhere (e.g., src/config/build.ts) keep their current location but should also maintain build.txt as the canonical source.

Repo Registry & Domain Map

See ~/apps/cc/repo-registry.md — lookup table for all repos and domain mappings.

CRM Repos — Do Not Confuse These

Both repos touch the Go Kart Park GHL location, but they do different jobs:

• ~/apps/claude-code-crm/ — Go Kart Park booking engine (FastAPI on VPS). Owns ALL customer-facing messaging: inbound reply generation (claude_responder.py), welcome SMS, follow-up escalation, staged message approval queue, Stripe payments, waivers, party dashboard, countdown reminders, review monitoring. If James says “the CRM”, “the prompt”, “the AI that replies to messages”, or anything about responding to leads — this is the repo.
• ~/apps/ai-assistant/ — Generic GHL scanner/nudge engine. Monitors multiple GHL subaccounts (ATH for Wayne, GKP for James), scores contacts, surfaces alerts to the business OWNER, proposes nudges via owner SMS conversation. GKP is a configured client (config.py line 76) but webhook forwarding to GKP is disabled (claude-code-crm handles webhooks directly). ai-assistant still runs scans and birthday reengagement for GKP. It does NOT compose customer replies or handle bookings.
• The split: claude-code-crm owns the customer conversation (replying, booking, payments). ai-assistant owns the owner conversation (scanning, alerting, “hey James, this contact needs attention”). They share the same GHL location but serve different audiences.

”Commit and Push” = Full Deploy

• When James says “commit and push” (or “commit this”, “push it up”, “ship it”), treat it as the full cycle: git add -A, commit, and push to remote.
• Don’t stop at just committing — always push unless there’s a specific reason not to (e.g., pre-push hook failure).
• Always check the VPS too: Run bash ~/apps/cc/vps-dirty-check.sh — VPS work often leaves uncommitted changes.
• Verify deploy is live: After pushing any repo with a production website (mytechsupport, themarketingshow, allthingshandy), run bash ~/apps/cc/verify-deploy.sh in the background. It polls the live site until the build number matches, then opens the page and confirms. Don’t declare “deployed” until the script confirms it’s actually live. If it times out, tell James.

Intent Resolution Protocol — Run on Every User Message

Before answering, mentally walk this checklist. It is the conscious version of “figure out what James means.” Full doc with examples and the seven routing layers: Intent Resolution.

1. Hear — what did James literally say? Take it at face value first.
2. Skill match — does any phrase trigger a Skill Auto-Invoke entry (table below)? If yes, run that skill, you are done. Otherwise continue.
3. Entity scan — does the message reference a repo, file, app, person, business, dashboard, or other entity? If no → answer the question literally and stop. If yes → continue.
4. Resolve via aliases — check ~/apps/cc/entity-aliases.json (source of truth, structured). The human-readable view lives in the Entity Aliases table at the bottom of ~/apps/cc/repo-registry.md. Match the phrase to a target. Entry types: repo, action, file, person, dashboard, url, tool, concept.
5. Confidence gate:
   • ≥80% (direct alias match in the table): act silently, just do the work
   • 50–80% (fuzzy match, or strong context like the topic of the last few turns): act, but state the assumption inline (“Working on tms-internal”)
   • <50% (new phrase, unknown target, or genuinely ambiguous): take your best stab and ask ONE confirming question — “Do you mean the tms-internal repo?”
6. Disambiguation — if multiple repos plausibly match (e.g., “the CRM” → claude-code-crm vs. ai-assistant; “TMS” → themarketingshow vs. tms-internal vs. tms-ops), use most recent context. If still unclear, ask ONE question. The “Ambiguous phrases” subsection of the alias table lists known multi-target phrases.
7. Save & learn — every time a NEW phrase resolves to an entity (especially after a confirmation), add it to ~/apps/cc/entity-aliases.json: either append the phrase to an existing entry’s phrases[] array or create a new entry. Then run python3 ~/apps/cc/sync-entity-aliases.py to refresh the markdown view. Next session will know it cold.

The “save & learn” step is what makes the system get smarter over time. Do not skip it.

Skill Auto-Invoke

When James naturally describes a task that matches a skill, invoke it automatically — don’t wait for the slash command. Always confirm which skill you’re running before starting, e.g.: “Running /create-blog-post — I’ll transform this text into a full blog post for The Marketing Show.”

When James pastes a large block of text with no instructions, ask: “Looks like you pasted some content — want me to run /create-blog-post and turn this into a blog post?”

• Pastes text and asks to create a blog post / article → /create-blog-post
• Asks to propagate, run links, or connect content → /propagate
• Asks to open a page, preview it, or “show me” → /preview
• Says “close out”, “save context”, “wrap up”, “save for next time” → /closeout
• Says “where did we leave off” → /standup (NOT auto-triggered at session start)
• Asks to organize files, clean up Drive, or “PARA” → /para-organize
• Asks “what’s on my calendar”, “any meetings”, “what do I have today”, “check my calendar” → /calendar
• Says “daily briefing”, “brief me”, “what’s my day look like”, “start my day” → /daily-briefing
• Says “check my inbox”, “anything in the inbox”, “check notes”, “thought catcher”, “what’s on my phone” → /thought-catcher
• Says “what’s on my to-do list”, “what should I work on”, “to-do”, “what’s next” → check The One Thing first (~/apps/the-one-thing/data.json), then /todo
• Says “publish episode”, “new episode”, “publish this video”, “episode pipeline” → /publish-episode
• Says “post about this”, “comment ladder”, “write a teaser post”, “write a post about” → /fb-comment-ladder
• Says “let’s make a post”, “post this everywhere”, “social post”, “post to LinkedIn and Facebook”, “share this” → /social-post
• Says “check the logs”, “MTS logs”, “what’s happening on MyTechSupport”, “any errors”, “log sweep” → /mts-logs
• Says “GSC audit”, “search console health”, “check my sites”, “SEO health”, “GSC report” → /gsc-audit
• Says “NAS crawler”, “rename some photos”, “name some files”, “find a photo”, “ugly filenames”, “NAS photos”, “random photo” → /nas-crawler
• Says “hottest prospect”, “who’s hot”, “best lead”, “who should we call”, “top prospect” → /hottest-prospect
• Says “scan Utah Connect”, “check the Facebook group”, “Utah leads”, “Facebook group scan”, “local Utah opportunities”, “connect utah” → /utah-connect-scan
• Says “add [domain] to google search console”, “add [domain] to GSC”, “get [domain] into search console”, “verify [domain] in search console”, “put [domain] in GSC”, “hook [domain] up to search console” → /add-to-gsc — runs ~/apps/google-search-console/add-domain.py end-to-end (Cloudflare TXT + verify + GSC add)
• Says “my one thing is”, “one thing today”, “my one thing for today”, “one thing” followed by a task declaration → /one-thing — record it, don’t act on it
• Says “finished my one thing”, “done with my one thing”, “one thing done” → /one-thing with --done
• Says “voice off”, “mute”, “silence”, “shut up”, “quiet mode” → /voice-off
• Says “voice on”, “unmute”, “speak again”, “turn voice back on” → /voice-on
• Says “review the logs”, “look through the logs”, “check the session logs”, “what did we talk about”, “what happened earlier”, “find where we discussed” → /review-logs
• Anything related to pronunciation (any context — asking, telling, correcting, wondering) → /pronounced — update speak-screen.py, don’t just acknowledge
• Mentions “tms-internal”, “internal wiki”, “internal site”, “the wiki”, “put this in internal”, “add this to internal” in the context of creating or editing a page → always read the meta-SOP first: Adding a Page to tms-internal (or the local file at ~/apps/tms-internal/src/content/docs/sops/adding-pages-to-tms-internal.md). That SOP covers frontmatter, page anatomy, voice, sidebar registration, and the build + deploy flow. Never guess from memory — the SOP evolves.

(Add new skill mappings here as skills are created.)

Drift Catching In-Session

Per-response reflections have been removed to reduce usage. In-session: if you notice something that clearly needs a CLAUDE.md update, a new skill, or a capability change, just do it immediately.

Screenshot Triage — Human in the Loop

• NEVER auto-execute deletes, moves, or folder creation. Always propose and wait for user approval.
• Flow:
  1. Open screenshot in Preview on the ultrawide monitor (bounds: {-2800, 100, -400, 1200})
  2. Describe it and give recommendation
  3. Queue up the recommended action as a tool call — user approves (tab+enter) or denies
  4. Only after approval, proceed to the next screenshot
• “d” or “D” = delete (close Preview, move to Trash)
• For moves/saves: propose the destination, wait for approval before creating folders or moving files

Markdown → HTML Sync Pattern

All md→HTML sync scripts live in ~/apps/cc/, named sync-{name}-html.py. They share the same dark theme base (#1a1a2e, SF Pro, collapsible sections) but each has its own layout suited to the content.

Active syncs:

Source	Script	Output
~/apps/cc/CLAUDE.md	sync-claudemd-html.py	Google Drive/2 Areas/Claude/CLAUDE.html (primary) + ~/.claude/projects/-Users-ojhurst-apps/memory/claude-md.html (mirror)
~/apps/cc/shortcuts.md	sync-shortcuts-html.py	~/apps/cc/shortcuts.html
~/apps/cc/todo.md	sync-todo-html.py	~/apps/cc/todo.html
~/.claude/.../memory/capabilities.md	sync-capabilities-html.py	~/apps/cc/capabilities.html

Auto-sync rule: Whenever you edit ANY source file that has an HTML companion (see table above), you MUST:

1. Regenerate the HTML immediately using the corresponding sync script
2. Open the HTML in the browser with a yellow highlight pointing to the change — so James sees exactly what was added/modified. Use the custom #hl= hash (NOT Chrome’s #:~:text= which renders purple):

   open "file:///path/to/output.html#hl=URL%20encoded%20snippet%20of%20changed%20text"

3. Announce it verbally — e.g., “I updated CLAUDE.md, so I’ve regenerated and opened the HTML version. The change is highlighted.”

This is automatic — don’t ask, just do it every time.

Opening URLs — Refresh, Don’t Duplicate

When opening anything in the browser, always use bash ~/apps/cc/open-html.sh instead of bare open. It finds the existing Chrome tab and refreshes it. Only opens a new tab if one doesn’t exist. Works with local files, web URLs, and localhost.

Browser Guide Overlay

When walking James through a multi-step browser task (account setup, config wizards, form filling), inject a step-by-step overlay directly into the active Chrome tab:

bash ~/apps/cc/overlay/inject-guide.sh '{"title":"Task Name","steps":[
  {"text":"Step 1 description","status":"completed"},
  {"text":"Step 2 description","status":"active"},
  {"text":"Step 3 description","status":"pending"}
]}'

• Statuses: pending, active, completed
• The overlay is draggable, minimizable, and has a close button
• To update steps, re-inject with updated statuses (it replaces the previous overlay)
• To close: bash ~/apps/cc/overlay/inject-guide.sh close
• Data is baked into the DOM (no fetch/server needed, avoids mixed-content issues on HTTPS pages)

Cross-Repo Content Creation

• When screenshot triage leads to content creation/edits in another repo (e.g., themarketingshow), follow that repo’s CLAUDE.md post-creation SOPs before moving on:
  • Ask about CTAs and affiliate links
  • Run entity-based propagation
  • ALWAYS open the page in the browser for user review BEFORE committing/pushing — never push sight-unseen
• Don’t skip monetization steps just because the work started from a different workflow
• This applies to ALL content changes, not just new articles — edits to existing pages get reviewed too

Auto-Open Changed Pages with Highlights

• When you change a page, open it with yellow highlighting on the change. HTML dashboards: #hl=URL%20encoded%20text. Localhost/production: Chrome’s #:~:text=.
• Proactively open every affected page — don’t wait to be asked. If you edited 3 pages, open all 3.
• Before opening localhost, ensure the dev server is running. Start it if needed.
• The rule: if James would want to see it, open it with the change highlighted before he has to ask.

Images from Conversation — Clipboard Grab

• When the user pastes/attaches an image and you need the file, run bash ~/apps/cc/recipes/clipboard-image.sh /path/to/destination.png
• Always verify the saved file with Read to confirm it matches what the user shared

Conversation Capture

• When the user shares a screenshot of a conversation (Messenger, iMessage, WhatsApp, etc.), determine: is this an action item or reference info?
  • Action item → Extract the task, add to To-Do List (1 Projects/To-Do List.docx), embed the screenshot for context
  • Reference info → Save details to the appropriate file in 3 Resources/, grab the screenshot from clipboard if useful for visual context
• Always propose file names and locations before saving
• Always include an “Added: M/D/YYYY” date stamp on every to-do item

Accessing Google Docs

• Native Google Docs (.gdoc) sync as tiny shortcut files — can’t be read locally
• To read a Google Doc, use the export URL: https://docs.google.com/document/d/{DOC_ID}/export?format=txt
• This only works if the doc is set to “Anyone with the link can view”
• If you get a 401, ask the user to update the link permissions
• To get the local Drive file’s Google Doc ID: xattr -l "/path/to/file.gdoc" → look for com.google.drivefs.item-id

Key Documents

• Command Center Index: file:///Users/ojhurst/apps/cc/index.html — Master dashboard linking to all dashboards, HTML files, and tools. Open this first when looking for anything.
• Infrastructure Guide: ~/apps/cc/infrastructure-guide.md / .html — All machines, SSH aliases, VNC, cross-machine sync, VPS details
• Shared Secrets (JSON source of truth, as of 2026-04-15):
  • ~/apps/cc/secrets/secrets.json — authoritative JSON store with per-entry metadata (category, description, source URL, created date)
  • ~/apps/cc/secrets/shared-secrets.env — generated mirror, kept in sync for legacy bash scripts. Never hand-edit.
  • CLI: python3 ~/apps/cc/secrets/secrets_cli.py {get NAME | env | sync | add NAME VALUE | list}
  • Adding a new secret: ALWAYS use secrets_cli.py add (never echo >> shared-secrets.env) — the env file is regenerated on every sync and direct writes will be lost.
  • Both files are gitignored in the cc repo and distributed across machines via secrets-sync.sh (scp), not Drive.
• Free Time Checklist (Personal SOP): https://docs.google.com/document/d/1ZS8pHTHKXLIVkCuUFGV6rlVElXPq18lq3x9Kqp_xE4Q/export?format=txt
  • When user says “I have free time” or “what should I work on?”, pull this and walk through it
• To-Do List: 1 Projects/To-Do List.docx (local, editable via python-docx)
  • Google Docs URL: https://docs.google.com/document/d/1y18ttAS_hR6FMw5Zfw4bk5i4SujVsyp8/edit

YouTube — Unlisted Video Sweep (SOP)

Anytime you interact with James’s YouTube channel programmatically (API calls, uploads, updates, transcript pulls, etc.), check the last 20 videos for any that are still unlisted. The upload script defaults to --privacy "unlisted", so videos can slip through.

• Use the YouTube Data API via OAuth (~/.youtube-upload/token.json) to list recent uploads with privacy status
• Flag any unlisted videos and ask James if they should be switched to public
• This is a background check — do it silently alongside whatever the main task is, and report findings

Voice First — “Check the Logs”

When James says “check the logs”, see the full SOP in ~/apps/voice-first/CLAUDE.md. Supabase project ref: hpdxjdffuwyjdfyvyfoe, PAT in memory files.

Gmail — Default to the API-Key CLI, Not the MCP Server

When James says “search my Gmail”, “check my inbox for X”, “pull up the email about Y”, or any Gmail read/search operation, default to the local CLI at ~/apps/gmail-helper/gmail.py, not the mcp__claude_ai_Gmail__* tools. Deterministic enforcement: a PreToolUse hook (~/apps/cc/hooks/gmail-mcp-guard.sh) blocks search_threads and get_thread MCP calls and prints the CLI commands instead.

• Search / list: python3 ~/apps/gmail-helper/gmail.py inbox --limit 30
• Grep inline: python3 ~/apps/gmail-helper/gmail.py inbox --limit 50 | grep -i 'business profile'
• Read full body: python3 ~/apps/gmail-helper/gmail.py read <message_id>
• Act on it: archive, trash, mark-read, unsubscribe (same CLI)

Why: the CLI uses the same OAuth token as every other local Gmail script (scope gmail.modify), runs entirely on this machine, and can actually archive/trash — the MCP read tools cannot. MCP tools for labels/drafts (label_thread, create_draft, list_labels) are still allowed when those actions are actually needed. Full SOP: Gmail Search and Triage.

Session Continuity

Auto-compaction is DISABLED. autoCompactEnabled: false is set in ~/.claude.json. Compaction only happens when James manually runs /compact. This is intentional — automatic compaction was wiping behavioral context (voice rules, checkpoint tracking) mid-session without warning. James controls when context gets compressed, not the system.

Automated safety net: Hooks are defined in ~/.claude/settings.json (under the "hooks" key). Scripts live in ~/apps/cc/hooks/. A PreCompact hook fires before context compaction and reminds you to save. A SessionStart hook with compact matcher fires after compaction to verify nothing was lost. These are the last line of defense — don’t rely on them alone.

PARANOID CHECKPOINTING — Treat every response like your memory is about to be wiped. Your context can vanish at any moment — compaction, session crash, Ctrl-Z. Act accordingly:

1. Save after EVERY substantive exchange. Not every 5 turns — every single one where work was done, a decision was made, or context was established. If James told you something important, write it down NOW.
2. What to save (every time):
   • ~/apps/cc/memory/last-session.md — current task, what just happened, what’s next, key decisions, files modified, any context a fresh session would need to pick up seamlessly
   • .claude/checkpoints/{task-name}.json — structured checkpoint: {phase_completed, next_phase, files_modified, key_decisions, remaining_work, context_notes}
3. The test: If James hits Ctrl-Z right now and starts a new session, can the next Claude pick up exactly where you left off with zero questions? If not, you haven’t saved enough.
4. Don’t ask, just save. This is not optional. Don’t wait for a natural pause. Don’t bundle it with other work. Save immediately after every meaningful exchange.
5. Announce it briefly: “Checkpoint saved.” — that’s it. No fanfare, just confirmation.

Session start: Check .claude/checkpoints/ for any incomplete tasks and offer to resume them. Task complete: Move its checkpoint to .claude/checkpoints/completed/.

File Organization

• PARA structure lives in Google Drive: /Users/ojhurst/Library/CloudStorage/GoogleDrive-ojhurst@gmail.com/My Drive/
  • 1 Projects/ — Active projects with a goal & deadline
  • 2 Areas/ — Ongoing responsibilities
  • 3 Resources/ — Reference material by topic
  • 4 Archive/ — Completed/inactive

How to update this page

The canonical source is ~/.claude/CLAUDE.md. To publish changes here:

1. Edit ~/.claude/CLAUDE.md (the live file Claude reads each session)
2. Copy the updated content into src/content/docs/super-claude-md.md on this repo
3. Bump build.txt and commit with Build X: super-claude-md sync
4. Push — Cloudflare Pages auto-deploys

A future iteration may extend sync-claudemd-html.py to also write this page automatically. For now it is a manual snapshot.