CCGM (Claude Code God Mode) is the modular system that replaced it. Every capability is a self-contained module you can install independently. Pick what you want, skip what you don't. Install with one command. It works across Claude Code CLI, VS Code, Cursor, the macOS Claude app, and any other editor with Claude Code support.

Why modular over monolithic? A monolithic config forces you to fork if you want to diverge, then you're maintaining your own version indefinitely. Conditional config (if statements in one file) mixes concerns and makes dependencies invisible. CCGM's approach: each module is a git-tracked directory with explicit dependencies declared in a manifest. Install only what you need. Read each module's README independently. Update CCGM and your personal additions stay intact.

The Problem with Monolithic Config

The original claude-dotfiles repo was a flat dump of everything into ~/.claude/. One giant CLAUDE.md with hundreds of lines of instructions. Hooks that assumed specific directory structures. Commands that referenced hardcoded paths. If you wanted to share it with someone, they had to fork the whole thing and strip out anything personal.

The deeper problem was coupling. The multi-agent coordination system depended on session logging, which depended on a specific log repo structure, which assumed you had multiple clones of every repository. A solo developer who just wanted better git workflow rules was pulling in an entire parallel agent infrastructure.

Each capability needed to be self-contained (installable without unrelated dependencies), documented (its own README explaining what it does and why), configurable (template variables for paths, usernames, and preferences), and composable (able to declare dependencies on other modules). CCGM is the result.

Architecture and Installation

CCGM is a Git repository with 35 modules organized into 5 categories. An interactive installer reads module manifests, resolves dependencies, expands templates, and places files into ~/.claude/.

ccgm/
├── start.sh                    # Interactive installer
├── update.sh                   # Pull latest and re-apply
├── uninstall.sh                # Remove only CCGM-installed files
├── presets/                    # Named module collections
├── lib/                        # Installer internals
├── modules/                    # 35 self-contained modules
├── docs/                       # 8 reference documents
└── tests/                      # Validation tests

The installer handles everything: prerequisite checks (Claude Code, jq, Python 3, gh CLI, gum), module selection via presets or individual checkboxes, dependency resolution via topological sort, configuration prompts for username and preferences, template expansion, file installation (copy or symlink), and settings merge. It records what it installed in a manifest so updates and uninstalls only touch CCGM-managed files.

git clone https://github.com/lucasmccomb/ccgm.git && cd ccgm && ./start.sh

Other install modes:

./start.sh --preset standard      # Skip the selection menu
./start.sh --scope project        # Install to .claude/ instead of ~/.claude/
./start.sh --link                 # Symlink instead of copy (for CCGM developers)

For AI agents installing programmatically:

CCGM_NON_INTERACTIVE=1 CCGM_USERNAME="github-user" ./start.sh --preset standard

CCGM places four types of files into ~/.claude/:

Rules shape how Claude thinks about code, handles git, debugs problems, and coordinates with other agents. Commands are explicit actions you invoke with /command-name. Hooks fire automatically on Claude Code events and can approve, deny, or modify behavior.

Presets

Four presets handle different needs. Start here to decide what to install, then read the module details that follow.

The installer resolves dependencies automatically. Select xplan and it pulls in multi-agent and session-logging without you needing to know they're required.

The Module System

Every module lives in modules/{name}/ and contains a module.json manifest, a README.md, and one or more content files. The manifest declares what to install, where to put it, and what configuration to prompt for.

{
  "name": "autonomy",
  "displayName": "Autonomy",
  "description": "Claude as a fully autonomous engineer",
  "category": "core",
  "scope": ["global", "project"],
  "dependencies": [],
  "files": {
    "rules/autonomy.md": {
      "target": "rules/autonomy.md",
      "type": "rule",
      "template": false
    }
  },
  "tags": ["autonomy", "core"],
  "configPrompts": []
}

File types: rule (loaded at session start), command (becomes a /slash-command), hook (triggered by events), config (merged into settings.json), doc (reference material, not auto-loaded).

Some modules use template variables (__HOME__, __USERNAME__, __CODE_DIR__) that are expanded during installation. Rule files never use templates because they should work for anyone without substitution.

Core Modules

Six core modules form the foundation. Rules tell Claude what to do; hooks (covered later) make sure it actually does it.

global-claude-md

Installs a slim ~/.claude/CLAUDE.md that serves as the root configuration reference. Instead of packing hundreds of lines of instructions into one file, it points to the actual rule files, commands, hooks, and settings where behavior is defined. This prevents the context waste of loading the same instructions twice (once from CLAUDE.md, once from the rule file) and eliminates maintenance drift between duplicated rules.

identity

Two foundational context files that give Claude a persistent identity layer surviving across sessions and context resets:

• soul.md defines the AI's personality, philosophy, reasoning principles, communication style, and boundaries
• human-context.md defines who you are - your background, goals, domain expertise, working style, and life intentions

Together they transform generic AI sessions into a working relationship with a consistent, aligned collaborator. The installer includes an interactive personalization step where you define both files during setup. Design principles: concision beats comprehensiveness (1-3 pages per file), declarative values beat procedural rules ("I value simplicity" works better than "never use complex abstractions"), and stable identity over current tasks (the memory system handles evolving details).

autonomy

The philosophical core. Configures Claude as a fully autonomous Staff-level engineer who executes tasks end-to-end instead of describing steps for you to follow.

The rule establishes one principle: do it, don't describe it. If Claude can accomplish something from the command line, it should do it immediately. Run npm install yourself. Fix failing builds yourself. Debug fully yourself.

It also defines clear boundaries for when to ask: credentials Claude doesn't have, third-party dashboard actions requiring a browser session, ambiguous product decisions, and destructive actions on shared systems. Everything else, just do it.

git-workflow

Six rules extracted from real mistakes:

1. No AI attribution - never add Co-Authored-By trailers or "Generated with Claude Code" footers. The human is the author and the one accountable for the code; AI is a tool.
2. PR template detection - check the repo root, .github/, and the org's .github repo for PR templates before creating PRs.
3. Sync before history changes - always git fetch before rebase, filter-branch, or reset. Running history-altering commands on a stale branch and force-pushing overwrites the remote.
4. Rebase by default - use rebase instead of merge for feature branches. Linear history, clean diffs.
5. Never stash - commit instead. Stashes are invisible and easy to forget.
6. Return to main after merge - checkout main and pull after PRs are merged.

settings

A base settings.json with 900+ pre-configured tool permission entries. The allow list covers safe operations (git status, npm commands, file operations in safe paths). The deny list blocks dangerous commands (force push to main, rm -rf /, dropping databases). A configurable default mode lets you choose between ask (confirm before risky tools) and dontAsk (auto-approve everything not denied).

hooks

Ten Python hook scripts that enforce the rules, plus an orphaned process detector. Each hook is covered in The Hook System below.

Commands and Skills

CCGM installs up to 30 slash commands and skills across 15 modules. Here are the ones that matter most, grouped by what they do.

Daily Workflow (commands-core)

These keep you in the terminal without context-switching to GitHub's UI for routine operations.

/commit - Stage, verify (lint, type-check, tests, build), and commit. Issue number extracted from branch name automatically.

/pr - Verify, rebase, push, detect PR templates, create PR with Closes #{issue}.

/cpm - The full cycle in one command: commit, PR, squash-merge, close issue, return to main.

/gs - Git status dashboard: branch, sync state, working directory, open PRs, recommended next action.

/ghi - Create a GitHub issue with type labels and structured body.

Research and Ideation

These commands handle the upfront discovery phase before you write code. /research is fast and requires no setup; /deepresearch produces deterministic, reproducible results but requires local infrastructure (Docker, Ollama, ~40GB model). Use /research for quick exploration, /deepresearch when consistency matters, and /ideate when the idea itself isn't clear yet.

/research - Zero-dependency research using parallel Claude agents with WebSearch, WebFetch, GitHub CLI, and Reddit. Spawns up to 7 agents that each investigate from a different angle. Works out of the box.

/ideate - Structured ideation framework. Takes a half-formed idea and runs a Socratic interview to reach 95% clarity across 7 dimensions. Can delegate to /deepresearch for market validation mid-interview, then hand off to /xplan for execution planning.

/deepresearch - Local-first pipeline that replaces parallel subagents with Ollama + SearXNG + a single Sonnet API call. Covered in its own section.

Quality and Review

These analyze code and writing after the work is done, catching issues before they ship.

/audit - Codebase audit across 8 categories (security, dependencies, code quality, architecture, TypeScript/React, testing, documentation, performance) using parallel agents. Supports --fix for auto-remediation.

/editorial-critique - 8-pass editorial review of long-form writing: prose craft, AI-tell detection, argument architecture, conciseness, data accuracy, structure and pacing, impact, and grammar. Produces a scored report (80 points max) with a prioritized findings list. --fix applies changes automatically.

/design-review - 6-pass visual design review. Takes screenshots at desktop, tablet, and mobile, extracts DOM structure and computed styles, then analyzes spacing, typography, responsive behavior, visual hierarchy, accessibility (WCAG AA), and component consistency. Produces a scored report with exact CSS selectors and property values. --fix applies the CSS changes.

/debug - Structured root-cause debugging: reproduce, hypothesize, instrument, diagnose, fix, verify. Runs on Opus. Invoked automatically when you ask Claude to fix a bug.

Brand and Documentation

/brand - Full naming pipeline: word exploration via 4 parallel agents (Datamuse, ConceptNet, Big Huge Thesaurus, etymological sources), 150-250 candidate generation across 6 categories, verification through domain availability, USPTO/WIPO trademark screening, app store searches, and social handle checks.

/brand-check - Deep verification of a single name across 10+ TLDs, trademarks, app stores, and social handles.

/docupdate - Documentation audit: README accuracy, TOC vs headings, onboarding flow vs prerequisites, package lists vs installed dependencies. Works in any project type.

Orchestration

These coordinate multi-step and multi-agent work. /startup initializes each session (pulls logs, checks git status, shows the tracking dashboard). /xplan handles the full lifecycle of a new feature or project. /mawf handles ad-hoc multi-agent work without the full planning overhead.

/xplan - Interactive planning and execution framework. Built around three human gates: after discovery, you confirm the concept; after research and planning, you approve the technical direction; after peer review by security, architecture, and business logic agents, you launch execution across parallel agent clones. Supports --light to skip the interactive phases.

/mawf - Multi-Agent Workflow. Takes unstructured input ("Fix the login bug, add dark mode, update the API docs"), parses into issues, plans dependency waves, spawns parallel agents, monitors progress, merges results.

/startup - Session initialization. Derives agent identity, pulls session logs, reads cross-agent activity, checks git status, queries the tracking dashboard, and presents a session dashboard. Runs automatically at session start.

Other Commands

• /pwv - Playwright visual verification
• /walkthrough - step-by-step guided mode
• /promote-rule - promote repo rules to global
• /cws-submit - Chrome Web Store submission walkthrough
• /ccgm-sync - sync local config changes back to CCGM repo
• /user-test - browser-based user testing
• /onremote - run commands on a configured remote server
• /workspace-setup - create multi-agent workspace directories
• /reflect - run the self-improving reflection checklist
• /consolidate - memory maintenance pass (deduplicate, clean stale entries)
• /xplan-status - check progress on a running xplan
• /xplan-resume - resume an interrupted xplan
• /log-init - lightweight session log initialization

The Hook System

Rules are instructions in markdown files that shape Claude's thinking. Hooks are Python scripts that intercept events and enforce constraints at runtime: blocking dangerous operations, prompting for required context, or automating approval for safe commands. Together they create guardrails that work even when Claude deviates from the rules.

Claude Code supports four hook types:

CCGM installs 13 hooks across 3 modules (10 from hooks, 2 from self-improving, 1 from session-logging):

Git Safety

enforce-git-workflow.py (PreToolUse:Bash) - The most critical hook. Blocks commits directly to protected branches (main, master, develop, staging, production, and custom branches). Blocks commits without the #N: issue prefix. Blocks pushes to protected branches. Claude will happily commit directly to main if you don't stop it; in a multi-agent setup, an unprotected main branch is a disaster. Escape hatches exist for non-issue commits (sync: prefix) and emergencies (ALLOW_MAIN_COMMIT=1).

check-migration-timestamps.py (PreToolUse) - Validates Supabase migration file timestamps before commits. Duplicate timestamps break supabase db push because the CLI can't distinguish the files. Catching this before commit prevents hard-to-debug migration state issues.

Workflow Adherence

enforce-issue-workflow.py (UserPromptSubmit) - Detects implementation requests (keywords like "update", "fix", "add", "create") and injects a reminder: check for an existing issue, create a branch, commit with issue prefix, create a PR.

auto-startup.py (SessionStart) - Triggers /startup at the beginning of each new session. Only fires on fresh starts, not resume or context compaction.

Permissions

auto-approve-bash.py (PreToolUse:Bash) - Enforces Bash command permissions from settings.json. Ensures consistent permission behavior across all Claude Code environments (CLI, VS Code, Cursor).

auto-approve-file-ops.py (PreToolUse) - Enforces path-based read/edit/write permissions using glob pattern matching.

Multi-Agent Coordination

agent-tracking-pre.py (PreToolUse:Bash) - Warns when a branch creation command is about to claim an issue already claimed by another agent.

agent-tracking-post.py (PostToolUse:Bash) - The engine of multi-agent issue tracking. Records branch creation (claim), first commit (in-progress), PR creation (pr-created), merge (merged), and issue close (closed) in a tracking CSV. Uses git commit + pull --rebase + push for concurrency; different-row edits auto-resolve since each agent modifies only its own rows.

Meta-Learning

reflection-trigger.py (PostToolUse:Bash) - Fires after gh pr merge and gh issue close commands, injecting a reminder to run the self-improving reflection checklist before moving to the next task. This is the integration point between the self-improving module and the development workflow.

precompact-reflection.py (PreCompact) - Fires before context compaction, prompting Claude to capture any unwritten patterns from the session before context is compressed and observations are lost.

Advisory

ccgm-update-check.py (PreToolUse) - Checks once per day whether CCGM has upstream updates.

port-check.py (PreToolUse:Bash) - Warns about dev server port conflicts. Reads port assignments from .env.clone, checks lsof. Advisory only, never blocks.

orphan-process-check.py (PreToolUse) - Detects orphaned test worker processes left behind by crashed test runs. Warns before they accumulate and consume resources.

Workflow Modules

Where core modules and commands handle individual tasks, workflow modules coordinate work across sessions, agents, and time.

session-logging

Structured logging system for tracking work across sessions. Each agent gets a unique ID derived from its directory name (e.g., lem-fyi-0 becomes agent-0). Logs are markdown files stored in a dedicated git repo, updated at mandatory trigger points: after commits, PR creation, PR merge, issue close, and before context compaction. The /startup command pulls logs, reads other agents' activity for cross-agent awareness, queries the tracking dashboard, and presents a session dashboard. This is what lets an agent pick up where it (or another agent) left off in a previous session.

multi-agent

Enables parallel development with multiple Claude Code instances on the same repo. Two organization models: the workspace model provides isolated groups of 4 clones with a coordinator agent per workspace, and the flat clone model puts all clones as siblings in one directory. The workspace model isolates sets of clones under a workspace parent so each coordinator only sees its own clones; the flat model is simpler but all agents can see all clones.

Port allocation gives each clone unique dev server ports via port-registry.json and .env.clone, preventing collisions when multiple agents run servers simultaneously. The tracking CSV records which agent claimed which issue, with automatic status transitions: claimed -> in-progress -> pr-created -> merged / closed. The tracking hooks handle all CSV writes automatically.

xplan

The planning and execution framework, bridging "I have an idea" to "I have a running codebase." It enforces three human gates: after discovery you confirm the concept is worth building, after research and planning you approve the technical approach, and after peer review by security, architecture, and business logic agents you launch execution. The full phase list covers discovery interview, deep research, research synthesis, optional naming, tech stack validation, scope negotiation, dependency wave planning, peer review, and parallel execution across clones. Each gate prevents the system from over-investing before you've validated the direction. The --light flag skips the interactive phases for automated execution.

remote-server

SSH access to a configured remote machine. The /onremote command lets Claude run health checks, view logs, restart services, and execute maintenance tasks on the remote server without interactive shell sessions.

self-improving

Meta-learning system with automated triggers. After completing significant tasks, Claude reflects on what went well, what surprised it, and what it would do differently, then writes reusable patterns to memory files that persist across sessions.

Unlike the earlier version (which was just a passive rule), this module is now integrated into the development workflow through hooks and cross-module references. The reflection-trigger.py hook fires after PR merges and issue closes, injecting a reminder to run the reflection checklist. The precompact-reflection.py hook captures unwritten patterns before context compaction. The session-logging module's mandatory triggers include a reflection step after every PR merge. The systematic-debugging module feeds debugging patterns to memory after three-strike situations. And common-mistakes is a living document - the reflection loop can add new anti-patterns when it identifies ones that caused significant wasted time.

Two commands: /reflect runs the full reflection checklist inline, and /consolidate runs a memory maintenance pass (deduplication, contradiction resolution, stale entry cleanup).

subagent-patterns

Methodology for decomposing tasks and delegating to subagents. Covers when to use subagents, how to write specs (objective, context, constraints, deliverable), dispatch patterns, and a two-stage review process (spec compliance, then code quality).

Pattern Modules

Workflow modules coordinate agents. Pattern modules shape how each agent thinks about problems, regardless of tech stack.

code-quality

Covers dependency minimization (prefer built-in, then library, then framework), migration validation (quote PostgreSQL reserved keywords, use idempotent patterns), build verification (pre-push only, not after every change), and living document maintenance (update README.md after merges that change capabilities).

The core principle is change-philosophy.md: when modifying an existing system, don't patch it. Redesign it into the solution that would have existed if the change had been a foundational assumption from the start. This prevents technical debt from accumulating as special cases. The result should look like it was always designed this way.

systematic-debugging

Four-phase root cause investigation: investigate (read the error, reproduce consistently), analyze (find patterns, check recent changes), hypothesize (form testable theories), implement (fix the root cause, not symptoms). Includes a three-strike rule: if three approaches fail, step back and reassess your understanding rather than continuing to guess.

test-driven-development

Strict red-green-refactor TDD. Write a failing test first, make it pass with the simplest code, then refactor. The module rejects common rationalizations: "This is too simple to test" (simple code has simple tests), "I'll add tests after" (tests written after implementation prove nothing about correctness), "The types guarantee correctness" (types catch type errors, not logic errors).

verification

Evidence-before-claims. Never assert that something works without fresh proof. Plan the verification command, execute it fresh, read the full output including exit codes, evaluate whether the output supports the claim, report honestly.

common-mistakes

Eight anti-patterns extracted from real mistakes: shallow directory exploration in monorepos, dependency blindness (branching without checking open PRs), ESLint Fast Refresh violations, suggesting already-tried solutions, premature solutions without full context, git multi-clone confusion, Cloudflare Pages vs Workers confusion, and CF Pages without Git integration.

frontend-design

Principles for distinctive interfaces. Intentional typography (not just Inter by default), cohesive color systems with semantic tokens, consistent spacing scales, purposeful animation. What to avoid: purple-to-blue gradients, overly rounded cards, default framework styles.

browser-automation

Tool selection hierarchy: CLI tools first (curl, gh, wrangler), then MCP servers, then API calls, then WebMCP, then browser automation last. Reserve browser automation for things that genuinely require visual verification.

Tech-Specific Modules

Each of these captures best practices for a common stack, preventing mistakes specific to that ecosystem.

cloudflare - Pages vs Workers selection, Git integration requirements. Prevents the mistake of creating a Workers project for a static site.

supabase - Current API key terminology (publishable key, not "anon key"; secret key, not "service_role key"), circuit breaker prevention for the connection pooler, migration workflow.

mcp-development - Building MCP servers: TypeScript recommended, stdio for local transport, {service}_{action}_{resource} naming, input schema design with Zod, testing with MCP Inspector.

shadcn - shadcn/ui patterns: composition over custom, semantic theming (bg-primary not bg-blue-500), form architecture, accessibility.

tailwind - Tailwind CSS v4: CSS-first configuration with @theme, OKLCH color system, CVA for variants, dark mode with @custom-variant. Includes the v4 cursor: pointer gotcha where buttons lose their pointer cursor because v4's preflight dropped the override.

The Statusline

CCGM includes a statusline script that displays live session metrics at the bottom of your terminal:

🧠 O-4.6 | code main | ctx:8% | 5h:62% ███░░ 2h26m | 7d:79% ████░ 3d8h

Model with tier emoji (🧠 Opus, 🐢 Sonnet, ⚠️ Haiku) and abbreviation, current directory and git branch, context window usage, 5-hour rate limit with bar and reset countdown, and 7-day rate limit with bar and reset countdown. Color-coded: green under 60%, yellow under 85%, red above 85%.

lem-deepresearch: The Companion Pipeline

lem-deepresearch provides the /deepresearch command as a companion to CCGM. It was extracted from CCGM into its own repo because it requires local infrastructure (Docker, Ollama with a ~40GB model, a Python venv) that not every CCGM user will want.

Why a Local Pipeline?

CCGM already includes /research, which spawns parallel Claude subagents and requires zero setup. It's fast and works everywhere. But each agent consumes a full context window, results vary between runs, and agents researching independently sometimes produce conflicting conclusions because they work from different sources with no reconciliation step.

lem-deepresearch trades setup complexity for consistency. It uses a deterministic local-first pipeline: local tools handle the cheap, parallelizable work (query generation, web search, fact extraction), and a single Sonnet API call handles the expensive step (synthesis). Same input produces the same output every time. The tradeoff is infrastructure: Docker, Ollama with a 72B parameter model (~40GB), and a Python venv.

The Pipeline

Topic
  -> Ollama (qwen2.5:72b, local): Generate 3-7 diverse search queries
  -> SearXNG (Docker): Run parallel searches across Google, Bing, DuckDuckGo
  -> Ollama (local): Extract facts from search results
  -> Anthropic Sonnet (single API call): Synthesize into research.md

Query generation uses a 72B parameter local model with temperature 0.7 for diversity, with a fallback to simple topic variations if generation fails. Parallel web search runs all queries concurrently via httpx.AsyncClient, getting up to 5 results per query from 3 engines. SSRF protection validates every URL against blocked networks (RFC 1918, loopback, link-local) and fails closed on DNS errors. HTML is stripped before any content reaches a model. Fact extraction filters by relevance and deduplicates across results. Synthesis produces a structured document with sections, citations, and source attribution.

Three depth presets: Standard (5 queries, ~6 min), Full (7 queries, ~8 min), Lite (3 queries, ~4 min).

Integration

lem-deepresearch installs to ~/.claude/commands/deepresearch.md and ~/.claude/bin/deepresearch-cli.py. It integrates with /xplan (xplan delegates its research phase to /deepresearch via --plan-dir) and with /ccgm-sync (edits to the command locally sync back to the lem-deepresearch repo).

Installation:

git clone https://github.com/lucasmccomb/lem-deepresearch.git && cd lem-deepresearch && ./install.sh

The original problem was a monolithic config that forced you to take everything or nothing. CCGM solves that: 35 modules across 5 categories, each installable independently with explicit dependencies. Start with the minimal preset, add capabilities as you need them, and update without losing your personal additions. The README has the full module catalog, and every module has its own README with manual install instructions if you prefer to cherry-pick.

Both CCGM and lem-deepresearch are MIT licensed.

I shipped the automation that collects data from GitHub, Spotify, Garmin, YouTube, and Cloudflare, feeds it to Claude, and generates these week-in-review posts. It's scheduled via launchd for Sunday evenings, sends me an email when it's done, and publishes to the site. The irony of writing about the system that's writing this isn't lost on me.

What I built

lem-fyi (#212, #210, #208, #206, #204): The WIR automation went through four iterations Sunday night. First pass: botched .env quoting broke the API tokens. Second: week calculation ran a day early because I forgot launchd executes on system timezone. Third: moved from 6 PM to 7 PM after realizing I'm rarely done working by six. Fourth: fixed code fence stripping in the markdown output - Claude's responses were bleeding through triple backticks. Also added user-library-read scope to the Spotify OAuth helper so the pipeline can actually fetch listening history (#204).

The site itself got a visual refresh. Redesigned the blog index to match the prose content width (#202), fixed Week in Review header spacing that was driving me nuts (#203), and reverted the three-state theme toggle back to a simple light/dark that syncs with system preference (#195, #192). The info icon on the home page now matches the LEM logo color (#190).

Published two posts: one about where tax dollars actually go during tax season (#188), another about shrinking clipboard screenshots by 70% before pasting into AI coding tools (#185).

lem-work (#526, #524, #503): Updated the 15-minute chat product to $5 and moved it first in the list (#526). Set GOOGLE_CALENDAR_ID for scheduling availability (#524). Restricted coach routes to owner email only (#503) - no reason to expose those endpoints publicly. The rest was dependency bumps: Resend 4.5.2 to 6.9.3, Stripe, Hono, Lucide icons.

Multi-agent work: Heavy weeks on ccgm, rootstead, sightagent, and supersam. Shipped milestones #1 (Foundation), #2 (Database Schema), and #4 (Search Pipeline) across those projects. Hit usage limits on Wave 3 agents - learned to plan for manual fallback when the token budget runs dry. Ran into pre-push hook failures from pre-existing TypeScript errors in a few repos, had to --no-verify a couple times. PNPM 10's interactive approve-builds doesn't work in non-TTY environments - switched to pnpm.onlyBuiltDependencies in package.json instead.

What I consumed

Only 90 minutes of music this week - unusual for me. Aleksi Perälä for idm/ambient focus, blink-182 and Turnstile when I needed energy, Matchbox Twenty for post-grunge nostalgia. Daniel Avery's "Illusion Of Time" and Moby's "Go" on repeat for deep work sessions.

One YouTube like: Islestead's video on making firewood without fuel or machines. Pure craft.

Illusion Of TimeDaniel Avery, Alessandro Cortini

GoMoby

Kick in the Door - 2008 RemasterThe Notorious B.I.G.

When God ComesCraig Mack

How I moved

Three workouts Thursday: 16 minutes of miscellaneous movement, 31 minutes on the elliptical (average HR 131), 31 minutes of strength training. Sleep was solid - 7.7 hours average, resting heart rate at 54 bpm. Only 22,759 steps for the week, though. Need to walk more.

Reach

10,318 page views across all sites. lem.fyi saw decent traffic to the AI-enabled SWE system post (78 views) and the Claude setup guide (41 views). The tax dollars post engagement page got 27 views - people were commenting. lem.work and lem.photo both got hammered with WordPress admin login attempts (808 and 446 views respectively on /wp-admin/index.php). Those sites don't run WordPress. Nice try.

Closing

The meta-loop of building the system that documents the building is satisfying in a way I didn't expect. I've tried weekly reviews before and always quit after a few entries - too much friction. Automating the collection and drafting removes 90% of that. I still edit the output, but starting from Claude's draft instead of a blank page changes everything. The system works because it lowers the activation energy enough that I'll actually keep doing it.

The evidence tells a different story. The federal government loses more to uncollected taxes, documented fraud, and systemic waste than the entire safety net costs, every single year. These programs cost a fraction of the budget and are a lifeline for historically disenfranchised communities.

The analysis below contextualizes the cost of these programs using data from CBO, GAO, IRS, CMS, USDA, and other federal sources. All figures are FY2024 unless otherwise noted.

The full budget at a glance

The federal government spent $6.75 trillion in FY2024:

What safety net programs actually cost

\*SNAP per-person figure reflects average monthly benefit per participant, not total program cost (which includes administrative expenses) divided by participants.

That's $221 billion combined. TANF's federal block grant has been frozen at $16.5 billion since 1996 with no inflation adjustment, which equates to a 40% cut in purchasing power by CBPP's estimate as of 2021.

Where the money actually disappears

Here's where the real gaps are. Every item below is documented by federal auditors, inspectors general, or official government data.

The tax gap: $606 billion per year

The IRS estimates a net $606 billion gap between taxes owed and taxes actually collected (tax year 2022), after accounting for late payments and enforcement recoveries. The gross gap before those recoveries is $696 billion. Both figures have nearly doubled since 2001.

77% is underreported income, concentrated in business income lacking third-party reporting: sole proprietors, pass-throughs, and partnerships. The GAO and CRS have flagged this as a persistent, structural problem on the GAO High-Risk List for years.

The tax gap is uncollected revenue, not direct spending, so the remedies differ. But the net tax gap is nearly 3x the entire safety net, every single year.

Government-wide fraud and improper payments

In 2024, the GAO published its first-ever government-wide fraud estimate: the federal government loses between $233 billion and $521 billion annually to fraud, or 3-7% of average annual obligations. Even the low-end estimate exceeds the entire safety net. This excludes tax fraud (that's the tax gap above) and state-level fraud.

Separately, the GAO reported $162 billion in improper payments in FY2024. The largest components:

Most improper payments aren't fraud. 68% of Medicare errors and 74% of Medicaid errors involve missing documentation: systemic process failures, not criminal activity. But the dollars are real.

Defense spending: $1.2 trillion and no accountability

The FY2024 NDAA authorized $886 billion for national defense. The actual national security footprint is larger:

All figures FY2024. National security includes DOD, DOE nuclear, intelligence, and VA. Safety net is SNAP, TANF, WIC, Section 8, LIHEAP, Pell Grants, Head Start, and school lunch.

The DOD's annual budget was 3.8x more than all eight safety net programs combined. The full national security footprint reaches 5.4x the safety net cost.

The Department of Defense is the only federal agency that has never passed a financial audit. Required to be audit-ready since 1990, the DOD wasn't audited until FY2018. It has failed every one since.

In the most recent audit (November 2024), the DOD could not adequately document 63% of its $3.8 trillion in assets. This doesn't mean $2.4 trillion is missing or stolen; it means accounting systems are so poor that auditors cannot verify whether these assets exist, are properly maintained, or are allocated efficiently. The GAO found $10.8 billion in confirmed fraud between FY2017 and FY2024. DOD financial management has been on the GAO High-Risk List every year since 1995.

The F-35 Joint Strike Fighter will exceed $2 trillion in lifetime costs according to the GAO, with sustainment costs alone up 44% since 2018. Over a decade behind schedule, the military now plans to fly the jets less than originally intended.

In FY2024, the DOD awarded $456.2 billion in contracts. Lockheed Martin alone received $50.7 billion, more than TANF, Head Start, WIC, and LIHEAP combined.

Boeing paid $615 million for misusing competitor data; KBR paid $579 million for kickbacks on military contracts. In FY2023, the DOJ recovered $2.68 billion in False Claims Act settlements. This is just what gets caught.

Systemic waste

Legacy IT: $83 billion per year on maintenance. The federal government spends approximately $105 billion annually on IT. Of that, $83 billion (79%) maintains existing systems, not modernization. The Treasury Department still runs systems dating to the late 1960s. GAO identified 11 legacy systems most in need of modernization: 8 use outdated languages like COBOL, 4 run on unsupported hardware, and 7 have known cybersecurity vulnerabilities.

93.6% of federal IT projects costing more than $10 million have experienced cost overruns, schedule delays, or both. Since 2010, GAO has made over 1,800 IT management recommendations. 463 remain unimplemented. IT management has been on the GAO High-Risk List since 2015.

77,000 empty federal buildings. Across 24 surveyed agencies, federal buildings average an 80% vacancy rate. The federal government owns or leases 77,000 buildings that are empty or underutilized. The deferred maintenance backlog has doubled from $171 billion in FY2017 to $370 billion in FY2024. Annual operating costs: approximately $7 billion.

Federal real property management has been on the GAO High-Risk List since 2003. GSA identified 45 properties for disposal saving $106 million annually in operations and $3 billion in deferred maintenance. That's 45 out of 77,000.

Year-end spending sprees. Federal agencies operate under "use it or lose it" budgeting: unspent funds at the end of the fiscal year get returned, creating a predictable spending surge every September. Government-wide, agencies spend approximately 16.5% of annual budgets in the final month (vs. the expected 8.3%), with 8.7% in the final week alone.

Quality suffers: contracts initiated during the last week of the fiscal year are at least 2.3x more likely to receive lower quality scores. The GAO first flagged this pattern in 1978. Nearly half a century later, nothing has changed.

Duplicative programs. Every year since 2011, the GAO publishes a report on duplication, overlap, and fragmentation across federal programs. The 2025 report identified $100 billion or more in potential savings from unimplemented recommendations.

Of 26 federal homelessness programs across multiple agencies, only 2 had conducted a program evaluation in the prior 5 years. The government also operates 163 STEM education programs across 13 agencies ($3 billion/year) and 47 employment and training programs across 9 agencies, with the GAO finding substantial overlap in populations served and services offered.

Since 2011, implemented GAO recommendations have saved $725 billion in cumulative financial benefits. Hundreds of recommendations remain open.

Who needs these programs, and why

The budget math is clear: waste dwarfs the safety net. But there's a second problem with the "cut benefits" argument. It assumes these programs are charity. The evidence shows they're not.

Some people think that safety net recipients just need to work harder. 55% of SNAP households with children already work. Their jobs don't pay enough to cover food. As for the claim that benefits discourage work: SNAP already requires able-bodied adults without dependents to work or participate in job training to maintain eligibility.

Federal policy created these conditions, and they have compounded across generations.

The wealth gap is a policy outcome

The Federal Reserve's 2022 Survey of Consumer Finances (the most recent available) found median household wealth of $284,310 for white families and $44,100 for Black families. For every $100 in wealth a white family holds, a Black family holds $15.

Federal housing policies enacted between the New Deal and the Fair Housing Act built this gap. From 1934 to 1968, the FHA required racial segregation in federally insured housing. The Home Owners' Loan Corporation graded neighborhoods by race, marking Black neighborhoods as "hazardous" in red, the origin of the term "redlining." Of the $120 billion in federal housing subsidies between 1934 and 1962, only 2% reached nonwhite families. After WWII, only 0.7% of Black veterans obtained home loans under the GI Bill, compared to millions of white veterans. Banks refused mortgages in Black neighborhoods. Suburban developments like Levittown were restricted to white buyers by deed covenant.

These exclusions didn't end with the Fair Housing Act. Predatory lending in the 1990s and 2000s disproportionately targeted Black and Hispanic neighborhoods, and disparities in post-2008 foreclosure recovery widened the gap further.

Homeownership rates today: 75.1% for white families, 44.2% for Black families. That 31-point gap stems directly from decades of federal subsidies for white homeownership and systematic exclusion of everyone else.

Poverty rates reflect compounding disadvantage

The Census Bureau reports poverty rates of 18.4% for Black Americans and 7.7% for white Americans. Wage gaps relative to white men tell the same story: Black men earn 84.6 cents per dollar; Hispanic men earn 75.8 cents. The gap compounds for women: Black women earn 74 cents, Hispanic women earn 64 cents.

These gaps persist across every metric the "bootstrap" narrative cites. Bertrand and Mullainathan (2004) found that a white-sounding name on a resume generated 50% more callbacks, equivalent to roughly 8 additional years of experience. Kline, Rose, and Walters (2022) confirmed the pattern persists: across 83,000 applications to Fortune 500 firms, identical resumes with Black-sounding names received 2.1% fewer callbacks.

Mobility is not equal

Even Black boys raised in the top 1% of household income earn less in adulthood than white boys raised at the median. Economist Raj Chetty's research on intergenerational mobility found that Black children's income falls approximately 13 percentiles below white children at every parental income level.

This gap appears in 99% of Census tracts, even after controlling for parental education, marital status, and wealth. The structural barriers persist today, not as relics of the past.

So who uses safety net programs?

Black Americans, roughly 13% of the U.S. population, account for 25.7% of SNAP recipients, 45% of Housing Choice Voucher holders, approximately 30% of TANF recipients, and 29% of Head Start enrollees. 72% of Black college students receive Pell Grants, compared to 34% of white students.

Federal policy locked these communities out of mortgages, hiring, education, and wealth building for decades. These programs exist to begin addressing the damage. The cost of that entire effort, all eight programs serving tens of millions of people, is 3.3% of the federal budget.

Safety net spending generates economic returns

Low-income recipients spend benefits immediately at local stores, and that money flows to distributors, farmers, and their employees. The USDA's Economic Research Service found that every $1 in SNAP benefits generates approximately $1.54 in GDP during economic downturns.

The CBO has published fiscal multiplier analyses showing where different types of spending land:

These multipliers measure GDP impact, not direct federal revenue returned. But the pattern is clear: providing financial assistance to people who will immediately spend it generates more economic activity than tax cuts for those likely to save. A dollar of SNAP benefits does more for GDP than a dollar of corporate tax relief.

The math doesn't add up

Eliminating every safety net program would mean 42 million people losing food assistance, 2.3 million families losing housing vouchers, 30 million children losing school lunch, and 6.3 million students losing Pell Grants. The savings: 3.3% of the federal budget.

The net tax gap alone is nearly 3x that. The government's own fraud estimate equals the entire safety net. The Pentagon cannot account for 63% of its assets.

Some argue that waste is harder to eliminate than cutting benefits. That's partly true: tax enforcement requires IRS funding (which has historically been defunded), IT modernization requires upfront capital, and reducing contractor fraud requires litigation. It seems more logical to focus on recouping some of the massive fraud, waste, and overspending rampant throughout the federal budget than to try to save a few percent of the total budget by defunding programs that help Americans in need.

"Pull yourself up by your bootstraps" requires boots. When the federal government systematically excluded communities from mortgages, education, and wealth building for decades, these programs became the response. Cutting them doesn't fix the budget. It abandons the people our policies already failed.

The fix: intercept the clipboard and compress the PNG before you paste it. I built a small macOS utility that does this automatically, reducing most screenshots by 50-80% with no visible quality loss.

The problem

macOS screenshots are saved as lossless PNGs. This is great for archival quality but wasteful for AI context windows. When you paste a screenshot into Claude Code (or any tool that sends images to an API), the full uncompressed PNG gets transmitted.

A typical macOS screenshot of a code editor or browser window is 150-400KB. After lossy PNG compression, that same image is 40-100KB, and you can't tell the difference.

Why pngquant, not JPEG

The obvious thought is "just convert to JPEG." But JPEG is a bad format for screenshots. It uses DCT-based compression designed for photographs with smooth gradients. Sharp edges (text, UI borders, icons, code) get smudgy compression artifacts. To keep text crisp at JPEG quality 95+, you barely save any space.

pngquant takes a different approach. It reduces the color palette of a PNG from millions of colors to an optimally chosen subset (up to 256 colors per channel). This works perfectly for screenshots because they're mostly flat UI colors, text, and simple gradients. The output stays as PNG, so edges remain pixel-perfect.

pngquant gives you JPEG-level file size reduction while keeping PNG-level sharpness. For screenshots of code, terminals, and UIs, it's the right tool.

The solution

I wrote a bash script that runs as a background daemon on macOS. It watches the clipboard for new images, compresses them with pngquant, and replaces the clipboard content with the optimized version. The whole thing is invisible once running.

Prerequisites

Install two Homebrew packages:

brew install pngpaste pngquant

• pngpaste reads image data from the macOS clipboard and saves it as a PNG file
• pngquant performs lossy PNG compression with configurable quality

The script

Create ~/bin/clipboard-optimize (or wherever you keep personal scripts):

#!/bin/bash
set -euo pipefail

CONFIG_DIR="$HOME/.config/clipboard-optimize"
ENABLED_FILE="$CONFIG_DIR/enabled"
PID_FILE="$CONFIG_DIR/daemon.pid"
LOG_FILE="$CONFIG_DIR/clipboard-optimize.log"
TEMP_DIR="${TMPDIR:-/tmp}/clipboard-optimize"

mkdir -p "$CONFIG_DIR" "$TEMP_DIR"

log() {
  echo "[$(date '+%H:%M:%S')] $*" >> "$LOG_FILE"
}

The script uses ~/.config/clipboard-optimize/ for state: a toggle file, PID file, and log.

Clipboard change detection

The first challenge is knowing when the clipboard changes. My initial approach was hashing the clipboard contents with md5, but macOS doesn't round-trip PNGs faithfully. Writing a 61KB optimized PNG to the clipboard and reading it back with pngpaste produces an 82KB file with a different hash, creating an infinite re-optimization loop.

The fix is NSPasteboard.changeCount, which macOS increments every time the clipboard changes. You can access it from bash via osascript:

get_change_count() {
  osascript -e 'use framework "AppKit"' \
    -e "return (current application's NSPasteboard's generalPasteboard()'s changeCount()) as integer" 2>/dev/null
}

This returns an integer that only changes when something actually modifies the clipboard. After we write back the optimized image, we capture the new count, so the daemon knows to skip it.

The optimization function

optimize_clipboard() {
  local raw="$TEMP_DIR/raw.png"
  local opt="$TEMP_DIR/opt.png"

  # Extract image from clipboard (fails if no image present)
  if ! pngpaste "$raw" 2>/dev/null; then
    return 1
  fi

  local original_size
  original_size=$(stat -f%z "$raw")

  # Skip tiny images (< 10KB) — not worth optimizing
  if [[ $original_size -lt 10240 ]]; then
    rm -f "$raw"
    return 1
  fi

  # Lossy compression: quality 85-100, max effort, strip metadata
  if ! pngquant --quality=85-100 --speed 1 --strip --force \
       --output "$opt" "$raw" 2>/dev/null; then
    rm -f "$raw" "$opt"
    return 1
  fi

  local opt_size
  opt_size=$(stat -f%z "$opt")

  # Only replace if we saved more than 5%
  local threshold=$(( original_size * 95 / 100 ))
  if [[ $opt_size -ge $threshold ]]; then
    rm -f "$raw" "$opt"
    return 1
  fi

  # Write optimized PNG back to clipboard
  osascript -e "set the clipboard to (read (POSIX file \"$opt\") as «class PNGf»)" 2>/dev/null

  local saved_kb=$(( (original_size - opt_size) / 1024 ))
  local orig_kb=$(( original_size / 1024 ))
  local opt_kb=$(( opt_size / 1024 ))
  local pct=$(( (original_size - opt_size) * 100 / original_size ))

  log "Optimized: ${orig_kb}KB -> ${opt_kb}KB (saved ${saved_kb}KB, ${pct}%)"
  echo "Optimized: ${orig_kb}KB -> ${opt_kb}KB (-${pct}%)"

  rm -f "$raw" "$opt"
  return 0
}

Key decisions in the flags:

• --quality=85-100 keeps quality high. pngquant will skip the optimization entirely if it can't meet the minimum quality of 85, so you never get a bad-looking result.
• --speed 1 uses maximum compression effort (slower but smaller output). Since we're only compressing one image at a time, the extra milliseconds don't matter.
• --strip removes PNG metadata (color profiles, timestamps, etc.) for additional savings.
• The 5% threshold prevents replacing the clipboard when pngquant can barely improve on the original.

The daemon loop

daemon_loop() {
  log "Daemon started (PID $$)"
  echo $$ > "$PID_FILE"

  local last_count
  last_count=$(get_change_count)

  trap 'log "Daemon stopped"; rm -f "$PID_FILE"; exit 0' SIGTERM SIGINT

  while true; do
    if [[ -f "$ENABLED_FILE" ]]; then
      local current_count
      current_count=$(get_change_count)

      if [[ "$current_count" != "$last_count" ]]; then
        if optimize_clipboard; then
          # Our write incremented changeCount - capture the new value
          last_count=$(get_change_count)
        else
          last_count="$current_count"
        fi
      fi
    fi
    sleep 1
  done
}

The daemon polls every second. It only attempts optimization when the clipboard changeCount has changed and the enabled toggle file exists. After a successful optimization, it captures the new changeCount (which was incremented by our osascript clipboard write) so it doesn't try to re-optimize the same image.

Command interface

The script supports four modes via the first argument:

case "${1:-}" in
  daemon) cmd_daemon ;;    # Start background daemon
  stop)   cmd_stop ;;      # Stop running daemon
  status) cmd_status ;;    # Show status and recent optimizations
  *)      cmd_oneshot ;;   # Optimize current clipboard image (default)
esac

The cmd_daemon function starts the loop in the background with disown, and cmd_stop sends SIGTERM to the PID stored in the PID file.

Shell aliases for toggling

Add these to your ~/.zshrc (or ~/.bashrc):

# Clipboard screenshot optimizer
clipopt() { clipboard-optimize; }
clipopt-on() {
  touch ~/.config/clipboard-optimize/enabled
  clipboard-optimize daemon
}
clipopt-off() {
  rm -f ~/.config/clipboard-optimize/enabled
  clipboard-optimize stop
}
clipopt-status() { clipboard-optimize status; }

Make sure ~/bin is in your PATH:

export PATH="$HOME/bin:$PATH"

Usage

One-shot mode (optimize whatever's on the clipboard right now):

$ clipopt
Optimized: 201KB -> 61KB (-69%)

Daemon mode (auto-optimize every screenshot you copy):

$ clipopt-on
Starting clipboard-optimize daemon...
Daemon running (PID 79214)

Check status:

$ clipopt-status
Optimization: ENABLED
Daemon: RUNNING (PID 79214)
Total optimizations: 47

Recent:
[14:23:01] Optimized: 312KB -> 89KB (saved 223KB, 71%)
[14:25:44] Optimized: 187KB -> 52KB (saved 135KB, 72%)
[14:31:12] Optimized: 95KB -> 41KB (saved 54KB, 56%)

Turn it off:

$ clipopt-off
Daemon stopped

Results

In my first test, the script compressed a 201KB screenshot down to 61KB, a 69% reduction. Across a typical coding session, here's what I've seen:

The visual quality is indistinguishable from the originals. Text remains crisp, colors are accurate, and UI elements look identical. The compression works by reducing the color palette intelligently, not by blurring or introducing artifacts.

Gotchas I ran into

macOS clipboard doesn't round-trip PNGs. When you write a PNG to the clipboard via osascript and read it back with pngpaste, you get a different binary representation. The image looks the same, but the file size and hash are different. This broke my initial hash-based change detection and caused an infinite loop where the daemon kept re-optimizing the same image every second. The NSPasteboard.changeCount approach solved this cleanly.

pngquant exits non-zero when quality can't be met. If the input image can't be compressed to meet the --quality minimum, pngquant returns exit code 99. The script handles this gracefully by checking the return code and skipping the replacement.

The daemon needs disown. Starting the loop with & alone isn't enough because the background process is still attached to the shell session. disown detaches it so it survives terminal closure.

Next steps

A few improvements I'm considering:

• launchd integration to start the daemon at login instead of manually running clipopt-on
• Notification Center alerts for each optimization (currently logs only)
• Configurable quality via environment variable or config file
• Stats tracking for total bytes saved across sessions

If you work with AI coding assistants and paste a lot of screenshots, this is an easy win. The whole setup takes about five minutes and runs invisibly in the background.

What I built

lem-fyi had its biggest week yet - 54 commits across 32 merged PRs. The headline was issue #63: a complete engagement system with likes, comments, Google OAuth, Cloudflare Turnstile bot prevention, Claude API content moderation, and Resend email notifications. Comments support editing, deleting, likes, and single-level replies (#132). The moderation defaults to review on API failure rather than reject - false negatives beat false positives on a personal blog.

The Preact-to-React migration (#128) was mechanical but tricky. React requires charSet (camelCase) and object-style style props where Preact accepted strings. The admin SPA stays on Preact with its own tsconfig to avoid type conflicts.

That migration enabled the real goal: a shared design system. Created @lem/ui (#127) as a standalone package with CSS custom properties, Tailwind v4 preset, and shared React components (Logo, SideNav, BottomNav, ThemeToggle). Wired it into both lem.fyi (#134) and lem-work (#307), cutting ~200 lines from each site. One gotcha: esbuild doesn't respect @jsxImportSource pragmas for files in symlinked packages, so the shared components use classic import React from 'react'.

Post page styling got a full pass (#129) - tighter letter-spacing on headings, rounded code blocks and callouts, responsive font sizes. The TOC went through three iterations (#70, #75, #79) before landing on a flex-based layout visible down to 1024px with a mobile collapsible fallback. Nav styling matched lem.work pixel-for-pixel (#91) after I discovered the root font size difference (18px vs 16px) was inflating all rem-based values by 12.5%.

Also shipped: Stripe donations (#61), floating action buttons (#95), email notifications for likes and comments (#94), Spotify and YouTube embed support for WIR posts (#121, #122), and a blog post on managing multiple GitHub accounts with direnv (#50).

darkly-suite spent the first half recovering from a Chrome Web Store rejection. Red Potassium flagged the listing for missing subscription disclosure - all features require a paid plan but the description didn't say so (#554). What followed was a compliance marathon: 14 PRs fixing descriptions (#583, #585, #587, #589), trimming test instructions to the 500-char CWS limit (#593), and applying the same fixes to Sheets (#601). Gmail Darkly bumped to 1.0.1 for resubmission (#580).

The second half pivoted to building a screenshot harness for CWS listing images. Six issues (#609-#614) delivered a mock framework with realistic Gmail, Sheets, and Docs page replicas, a Playwright + Sharp pipeline for automated capture and compositing, and per-extension YAML configs for screenshot generation. The mock pages render real-looking UIs with toolbars, sidebars, and content areas that show dark mode applied.

Subscription UX improved: warning banners for canceled and past-due subscriptions (#577, #582), a restore purchase flow for license recovery after reinstall (#564), and a redesigned side panel with collapsible sections (#572).

lem-work got a consulting booking feature (#301, #304) with Stripe payments and Google Calendar integration, renamed from "Consulting" to "Meet" with a General Inquiry meeting type. The CareConnect provider portal got its showcase page (#287) with deployment to Cloudflare (#290) and live demo links. Portfolio pages shipped for lem.work itself (#264) and eluketronic (#257).

The headshot got an easter egg: hover reveals a silly photo (#275), mousedown shows a no-glasses variant (#277), with mobile touch support (#281) and a question mark cursor hint (#279). The About page was redesigned (#185) with Spotify recently-played integration (#189).

What I consumed

No Spotify or YouTube data collected this week - the polling system wasn't wired up yet. That changes next week.

Closing

181 commits, 92 PRs, three repos. The engagement system and shared design system were the big wins. The CWS rejection felt like a setback but forced a proper compliance review that'll prevent future rejections. The screenshot harness means never hand-crafting store listing images again. Next week: get the journal automation actually running (it wasn't), and tackle the about page.

That system runs on my personal Mac. Then I needed to use GitHub Copilot on a Windows VM for work, and the question became: how much of this workflow translates?

The answer is most of it. Not all of it, and not one-to-one, but the core ideas carry over surprisingly well. This post walks through the translation and what I learned along the way.

Why not just use Claude Code on both?

My employer provides a Windows VM with GitHub Copilot Enterprise. The work happens there. Claude Code is a terminal-native tool that runs best on macOS/Linux. Even if I could run it on the VM, Copilot is what the team uses, and there's value in working within the same tool ecosystem as your coworkers.

But the workflow patterns I've built, the commit conventions, the session logging, the quality gates, those aren't Claude-specific ideas. They're development workflow ideas that happen to be implemented in Claude Code. Translating them to Copilot was about carrying the workflow forward, not the tool.

The mapping

Here's the high-level translation table. Each Claude Code concept has a Copilot equivalent, though the implementation details differ.

Global instructions: CLAUDE.md to copilot-instructions.md

In Claude Code, ~/.claude/CLAUDE.md is a single markdown file that gets loaded into every conversation. It contains everything: commit conventions, code standards, error handling patterns, common mistakes to avoid, security rules. One file, always present.

My initial translation split this across two mechanisms: inline JSON instruction arrays in VS Code user settings, and a copilot-instructions.md file per repo. The settings approach looked like this:

{
  "github.copilot.chat.codeGeneration.instructions": [
    { "text": "Never add AI attribution to git commits or PR descriptions." },
    { "text": "Use functional React components with TypeScript interfaces for props." }
  ],
  "github.copilot.chat.commitMessageGeneration.instructions": [
    { "text": "Format: {issue_number}: {brief description}. Never include AI attribution." }
  ]
}

This seemed nicer than Claude Code's approach - instructions scoped to specific Copilot behaviors (code generation, commit messages, reviews, PR descriptions) instead of one big file where the model has to figure out what applies.

Then I actually set it up on the VM. VS Code immediately flagged every one of these with deprecation warnings: "Use instructions files instead." The github.copilot.chat.*.instructions inline settings are deprecated in favor of the instruction file system. All those carefully structured JSON arrays? Unnecessary. The same rules belong in .github/copilot-instructions.md and .github/instructions/*.instructions.md.

This was a good lesson in the gap between documentation and reality. The settings API still technically works, but VS Code actively warns against it. The instruction files are the correct path forward.

copilot-instructions.md (.github/copilot-instructions.md) is where all the rules actually live. Git workflow documentation, session logging protocols, code standards with examples, commit conventions, the full "common mistakes to avoid" section. This file lives in each repo and is loaded automatically when Copilot operates in that workspace. It's the direct equivalent of CLAUDE.md.

Slash commands: commands/ to prompts/

Claude Code's slash commands live in ~/.claude/commands/ as markdown files with YAML frontmatter. They use ! prefix syntax to execute shell commands inline when the command is invoked, which means the command can pre-load git state, issue lists, and other context before Claude even starts thinking.

Copilot's equivalent is .prompt.md files in .github/prompts/. These appear in the / autocomplete menu in Copilot Chat when you're in Agent mode. The frontmatter is slightly different:

---
agent: 'agent'
tools: ['#runInTerminal', '#readFile', '#editFiles']
description: 'Stage all changes and commit with conventional format'
---

The tools array explicitly declares which capabilities the prompt needs. #runInTerminal lets it execute shell commands, #readFile lets it read files, #editFiles lets it make changes, and #codebase lets it search across the project.

Here's how the nine Claude Code commands mapped:

The biggest behavioral difference is how context gets loaded. In Claude Code, the /startup command runs shell commands with ! prefix and injects the output directly into the conversation context before Claude processes anything. The model sees the git status, open issues, and log files as pre-loaded data.

In Copilot, the prompt file is just instructions. It tells the agent "run git status", "run gh pr list", "run gh issue list". The agent then executes these as sequential steps, which means it takes longer and the model processes each result individually rather than seeing everything at once.

For most commands this difference doesn't matter. For /startup, which gathers context from five or six different sources, it's noticeably slower. But the end result is the same: the agent has a full picture of the project state.

VS Code settings: what actually goes in settings.json

With the inline instruction arrays removed, settings.json becomes much cleaner. It handles the behavioral configuration that applies globally across all workspaces - things that aren't project-specific rules, but rather how VS Code and Copilot should behave.

Here's what survived the setup process:

Copilot behavior settings:

Editor settings that affect the Copilot workflow:

Context exclusion settings:

A few things I learned during setup:

• chat.instructionsFilesLocations was supposed to point at .github/instructions/, but VS Code rejected the schema format. Turns out .github/instructions/ is auto-scanned by default - the setting is unnecessary.
• editor.defaultFormatter: "esbenp.prettier-vscode" fails validation if the Prettier extension isn't installed. Comment it out until you install it, or install it first.
• Extension dependencies are real. Four extensions are needed for full functionality: GitHub Copilot, GitHub Copilot Chat, Prettier, and ESLint. The settings file should document these prerequisites (ours now does).

The full settings reference with every setting explained is in the copilot-configs README.

Conditional instructions: something Claude Code doesn't have

Copilot has a feature that Claude Code doesn't: .instructions.md files in .github/instructions/ that apply conditionally based on file glob patterns.

---
name: 'React TypeScript Standards'
applyTo: '**/*.{tsx,ts}'
---
## Component Patterns
- Always use functional components with TypeScript interfaces
- Never export components and non-components from the same file

---
name: 'SQL Migration Standards'
applyTo: '**/migrations/**/*.sql'
---
## Reserved Keywords
Always double-quote: position, order, user, offset, limit, key, value, type...

This is genuinely useful. In Claude Code, the React conventions, the SQL migration rules, and the Go patterns all live in the same CLAUDE.md file. The model gets all of them regardless of what file it's working on. With Copilot's instruction files, the React rules only load when you're editing .tsx files, and the SQL rules only load when you're in a migration directory.

I created two instruction files to start: react-typescript.instructions.md for TypeScript/React conventions, and sql-migrations.instructions.md for Supabase migration patterns. Adding more is straightforward.

Enforcement hooks: Python hooks to Husky

This is where the translation gets lossy.

Claude Code's enforcement hooks are Python scripts that intercept tool calls at the PreToolUse and UserPromptSubmit layers. They run before Claude executes any action, and they can block it, modify it, or inject context. Four hooks in my setup:

• enforce-git-workflow.py - blocks commits on main, enforces issue-number prefixes in commit messages, blocks pushes to main
• enforce-issue-workflow.py - detects work-request prompts and injects a "create an issue first" reminder
• auto-approve-bash.py - reimplements the permission allow/deny list at the hook layer (workaround for a Claude Code bug)
• auto-approve-file-ops.py - same for file read/write/edit operations

Copilot doesn't have a hook/interception system. There's no way to run code before Copilot executes a command, and there's no way to programmatically block actions based on content inspection.

The workaround is Husky git hooks, which operate at the git level rather than the AI level:

Pre-commit (.husky/pre-commit):

#!/bin/sh
BRANCH=$(git branch --show-current)
if [ "$BRANCH" = "main" ]; then
  echo "ERROR: Cannot commit on main. Create a feature branch first."
  exit 1
fi

Commit-msg (.husky/commit-msg):

#!/bin/sh
MSG=$(cat "$1")
if ! echo "$MSG" | grep -qE "^[0-9]+:"; then
  echo "ERROR: Commit message must start with issue number."
  echo "  Format: {issue_number}: {description}"
  exit 1
fi

These cover the two most important enforcement rules (no commits on main, issue-number prefix in messages). But they miss the subtler ones. The enforce-issue-workflow.py hook that detects work-request verbs and reminds Claude to check for issues first? That has no Copilot equivalent. The permission deny list that blocks rm and git reset --hard? That's in the instructions as soft guidance, not hard enforcement.

The tradeoff is clear: Husky hooks enforce rules at the git boundary, where they catch mistakes regardless of whether a human or AI made them. Claude Code hooks enforce rules at the AI boundary, which catches mistakes earlier but only applies to AI-initiated actions.

Session logging and multi-agent coordination

The session logging system and multi-agent coordination protocols are workflow documentation, not tool-specific features. They translate as reference docs that Copilot reads when instructed to.

In Claude Code, log-system.md and multi-agent-system.md live in ~/.claude/ and are referenced by the slash commands. The /startup command reads agent logs, checks cross-agent state, and creates new log entries. The logging triggers (after every commit, after PR creation, after merge) are enforced by instructions in CLAUDE.md.

In Copilot, these same documents live in docs/ and are referenced by the prompt files. The /startup prompt instructs the agent to pull logs, read today's log, check other agents' logs, and create a new entry if needed. The logging triggers are documented in copilot-instructions.md.

The implementation is softer. Claude Code's hooks can't force the model to update logs, but the tight integration between commands and instructions makes it reliable in practice. With Copilot, it's entirely instruction-based, so compliance depends on the model following the prompt. In my experience, both tools follow logging instructions consistently once the prompts are well-written.

One adaptation for the Windows environment: all paths in the docs reference both Unix-style (~/code/agent-logs/) and Windows-style (C:\code\agent-logs\) conventions, since Copilot on Windows might use either depending on whether it's running in PowerShell or Git Bash.

The setup.sh approach

The original Claude Code setup uses a setup.sh script that symlinks config files and generates settings.json with path expansion. The copilot-configs repo takes a different approach: placeholder replacement.

All config files use {{PLACEHOLDER}} tokens for values that vary per user:

• {{GITHUB_USERNAME}} - your GitHub handle
• {{FULL_NAME}} - your name for attribution
• {{LOG_REPO_NAME}} - the name of your agent logs repo

The setup script prompts for these values (auto-detecting from gh CLI and git config where possible), then does a find/sed across all .md and .json files to replace every placeholder. It can also create the agent logs repo on GitHub.

git clone https://github.com/lucasmccomb/copilot-configs.git
cd copilot-configs
./setup.sh

Or non-interactively:

./setup.sh --github-user octocat --full-name "Octo Cat" --log-repo my-agent-logs

This makes the configs genuinely portable. Someone can fork the repo, run setup, and have a complete Copilot workflow configured in under a minute. The placeholder approach is simpler than the symlink/template system I use for Claude Code, but it works well for a repo that's meant to be forked and customized rather than centrally managed.

What didn't translate

Some things are Claude Code-specific and have no meaningful Copilot equivalent:

The permission system is the most significant loss. Claude Code's deny list blocks destructive operations (rm, git reset --hard, DROP TABLE) at the tool level. In Copilot, these are documented as "don't do this" in the instructions. The model generally respects them, but there's no hard gate.

Key differences in practice

After using both systems side by side, a few practical differences stand out:

Context loading is explicit in Copilot. Claude Code automatically reads referenced files, loads the CLAUDE.md hierarchy, and ingests MCP server data. Copilot requires you to explicitly reference context with #file, #codebase, or #changes. This means you need to be more intentional about what the model sees, which is both a feature (less noise) and a limitation (more manual work).

Agent mode is opt-in. In Claude Code, the model always has access to tools. In Copilot, you need to open Agent mode specifically (Ctrl+Shift+I instead of Ctrl+I) and the / commands only appear there. Default chat is ask-only with no tool access.

Model switching is per-chat. Claude Code switches models with a --model flag. Copilot uses Ctrl+Alt+. to cycle through available models within a chat. Different models are better at different tasks, and Copilot makes it easy to switch mid-conversation.

The instruction hierarchy is different. Claude Code loads CLAUDE.md files from root to working directory, creating a three-tier inheritance (global, workspace, project). Copilot has user settings (global), copilot-instructions.md (per-repo), and .instructions.md files (per-file-type). The layering is flatter but more granular at the file level.

The result

The copilot-configs repo is public. It contains:

• .github/copilot-instructions.md - global rules translated from CLAUDE.md
• .github/prompts/ - 9 prompt files (commit, pr, gs, startup, sync, new-issue, walkthrough, cpm, audit)
• .github/instructions/ - 2 conditional instruction files (React/TypeScript, SQL migrations)
• .vscode/settings.json - user-level Copilot behavior settings (with a full reference guide in the README)
• .copilotignore - context exclusion rules
• docs/ - log system, multi-agent system, and GitHub repo protocols
• setup.sh - one-command personalization

The workflow I've built over months with Claude Code now has a Copilot equivalent that captures maybe 80% of the functionality. The missing 20% is mostly the enforcement layer (hooks, permissions, tool-call interception) and the deeper MCP integration. For day-to-day development work, the Copilot version covers what matters: consistent commit conventions, session continuity, quality gates, and a standardized workflow that any new project can adopt immediately.

The translation process itself was instructive. Several assumptions I made from reading Copilot documentation didn't survive contact with reality - deprecated settings, schema mismatches, extension dependencies. The best way to validate any AI tool configuration is to actually set it up and watch what VS Code complains about. Documentation lags behind the tool.

If you're using Claude Code and need to work with Copilot (or vice versa), the concepts transfer. The specific files and syntax are different, but the underlying ideas (global instructions, scoped commands, enforcement at boundaries, session logging for continuity) are tool-agnostic. Build the workflow first, then implement it in whatever tool your environment requires.

Introduction

I use Claude for 99% of my research and general questions these days and it's become incredibly useful to me. This is a guide that covers:

• how to install the Claude desktop app on an Apple computer
• how to create a Claude account using your existing Google account
• how to enter a prompt
• tips on how to write prompts
• tips on how to use the Claude desktop app

Prerequisites

This guide requires you to have:

• an Apple computer running macOS (ideally the latest version)
• a Google account (ideally you are logged in to said Google account in your browser)
• a web browser (ideally Google Chrome)
• 10-20 minutes of available time (depending on how tech savvy you are)

Instructions

Step 1: Download the Desktop app from claude.ai

Go to claude.ai/login. You can either download the Desktop app or continue on web. I recommend downloading the Desktop app.

Click the "Download desktop app" button

Step 2: Open the installer

You're then going to install the Desktop app like you would any other app. The Claude.dmg install program will likely be saved in your Downloads folder or on your Desktop. It might even appear in the upper right of Chrome where you can double click it to open it.

Find where the downloaded Claude.dmg file was saved and double-click it to open it

Step 3: Drag Claude to Applications

Once you find the Claude.dmg installer program, double click on it and you should see a Finder window pop up that looks like this:

Click and drag the Claude program into your Applications folder. It will take 30-60 seconds to add it to your Applications. You can then close that window.

Step 4: Eject Claude installer (optional but recommended)

Eject the installer application from your Desktop by right clicking on it with your mouse (or two finger tap/click with trackpad or "control" + click) and selecting "Eject Claude" or by dragging it to the Trash in the Dock.

Step 5: Open Claude from Applications

You now have Claude installed as an application on your computer. Go into Applications using a Finder window, scroll to Claude and double click on it to open it.

Step 6: Allow Claude to open

You will likely see a popup like the one below. This is safe. This program will not have control of your computer. The only thing Claude will have access to is the information you put into it unless you manually give it access to other applications.

Click "Open"

Step 7: Get Started

You're then going to see the Get Started window.

Click "Get Started"

Step 8: Sign in with Google

From there you're going to be prompted to sign in. I recommend using Google. Google sign-in is one of the most secure authentication methods and prevents having to create new passwords.

Click "Continue with Google"

Step 9: Continue with Google in Chrome

A new Chrome window will open that looks like the one below.

Click "Continue with Google"

Step 10: Select your Google account

Another Google Authentication window will appear that looks like the one below.

Select the account you want to sign in with

Step 11: Authorize Claude

You'll then see a "Sign in to Claude" window appear. Again, this is safe. You're only giving Claude access to your basic Google profile information, not your emails, contacts, or any of your private data. This is simply using your Google account to authenticate for login and it is safe.

Click "Continue"

Step 12: Accept the terms

You'll then be returned to the Claude desktop app interface where you'll see the following screen.

Check the "I agree..." checkbox and click "Continue"

Step 13: Choose a plan

You'll then see the "Choose a plan" screen appear. I recommend starting with a Free plan and if you end up wanting more features you can always upgrade.

Click "Use Claude for free"

Step 14: Welcome screen

You'll then see a welcome screen explaining a few things.

Toggle "Help Improve Claude" off at the bottom Click "I understand"

Step 15: Enter your name

Enter your name in the following screen.

Step 16: Select your interests

On the "What are you into?" screen select which options that you think fit your needs most. For you, I would recommend: Life stuff and Design & creativity.

Once you have the options selected, click "Let's go"

Step 17: Start your first conversation

You'll then see a "Where should we start?" screen.

Click "I have my own topic" on the bottom right

Step 18: Select Quick Chat options

I would keep the two default options in this screen selected. I use the menu bar shortcut often and am working on getting used to the double-option shortcut.

Select the options you want to use and click "Continue"

Step 19: Start your first chat with Claude!

We've reached the finish line for getting up and running with Claude as a desktop app. Ask Claude about whatever is on your mind. I use Claude for all of my questions, research, guidance, advice and even just processing my thoughts.

If you're not sure the best ways to use Claude, ask Claude. AI agents like Claude are the most powerful tools that humans have created for the purpose of acquiring general knowledge. It has access to almost all of documented human knowledge and it can explain things for any level of understanding. Ask it anything!

Here's an example use case that might be helpful. A family member of mine recently messaged me with the following question:

I have a bunch of family photos that I want to digitize. They're all in different print sizes up to 11x14. I'm thinking about ordering a scanner but not sure which one to get. I also don't know what the best way to digitally store the scanned photos would be. Would you be able to recommend a good scanner that can do batch scanning for lots of photos and what the best storage option would be? I have an iCloud account that I backup my iPhone photos to and have also used Google Photos. Batch upload would be helpful. I also want to be able to create photo books with the digitized images.

Here's exactly what I would do to answer that question:

1. Open Claude
2. Copy the text of that message and paste it into the Claude prompt
3. Add a couple notes to the end of the prompt that I think would be helpful:
   • "Give me a high level overview of how I should think about configuring this process. There has to be a lot of documentation available online explaining how people have done this. What are the major things that I want to pay attention to? What are the scanner specifications that I should be concerned with? What are the image storage options that I should be concerned with? Explain everything thoroughly so that someone without much technological know-how can understand."
   • "The scanner and storage option should both be relatively easy to use for someone who is not necessarily technologically savvy. Both processes should not be overly complex."
   • "I want the scans of the images to be high quality but I also want to be able to do batch scanning and not have to place every image into a scanner individually."
   • "I don't want to spend more than $1000 on the scanner and more than $20/month for image storage. Give me a range of options within these price points and the pros and cons of each."
   • "Again, make sure to explain things thoroughly and do in-depth research to find the best options and systems that make the most sense."
   • "I will be using a MacBook Pro laptop with an external monitor as my main machine for this process."

When I'm writing prompts into AI agents I try to write as clearly as possible and identify key areas that I want the agent to research and think about. I ask the agent to explain things to me in plain terms. If I don't know anything about something that I'm researching I start from that point of view and ask the agent to explain things to me from a high level, break down the main concepts so that I can understand them and use that foundation to guide my thinking and the path of the conversation. If you don't understand something that Claude told you, ask Claude to explain it in simpler terms ("Explain this to me like I'm 10 years old"). Curiosity is your friend here. Claude will not judge you for not knowing something. Claude's purpose is to help you figure anything out. Use it!

Once you've finished entering the prompt into the text area, hit the return key or press the arrow button on the right side of the text area. Claude will begin researching.

Step 20: Utilizing Claude's output

After entering that prompt regarding photo print digitizing, Claude spent about 3 minutes researching options for scanners and photo storage and then created a .docx document for me with all of the information.

I can now download that file or add it to my Google Drive to share it using the buttons in the upper right corner of the window.

Here's the document that Claude created for me: Family Photo Digitization Guide

Let's say that I review the document and want Claude to explain something more or I want to clarify a feature that I want the scanner to have or I realized a constraint with the scanning process that I forgot to mention in the original prompt. I would simply type into the prompt:

I realized I forgot to mention X, does that change your recommendation at all?

Tips

• Use "Return + Shift" to add a line break in the prompt area without sending the prompt.
• If you accidentally sent a prompt and want to stop Claude from answering it, hit the stop button in the bottom right of the prompt area or hit the "Esc" key.

• Click the "Open sidebar" button at the top left of the screen to view your recent chats, create a new chat or use other features of Claude.

• Quickly create a new chat by pressing "Command + Shift + O".
• If you upgrade to a paid plan, you can use better models for more complex tasks. Unless you're asking Claude to process complex data or research a very complex process of some kind, the latest model that's provided with the Free plan should be sufficient for your needs. If you find that it's not performing to your desired ability I would try upgrading to see if that improves Claude's responses.

• Claude is multi-modal, meaning that it can consume and analyze images and files in addition to plain text. Use the "+" button on the bottom left of the prompt input to upload images or files in order to provide additional context with your prompt. Claude can summarize documents and analyze screenshots. Here's a guide for how to take screenshots.

• Ask Claude to save research to files so you can share the files with people and for yourself to easily reference later on. Save them to a "Claude docs" directory somewhere on your computer where you can easily find them.

Conclusion

You now have all recorded human knowledge just a prompt away. For more information on how to use Claude, I recommend checking out this course created by Anthropic, the creators of Claude: Claude 101. Claude is an incredibly powerful tool and is an excellent introduction to using AI for everyday problems.

Use it!

Questions, comments, concerns?

Reach out to me here: luke@lem.fyi

Thanks for reading and hopefully this is helpful!

I wanted something that just works: cd into a directory and have the right GitHub identity loaded automatically. Here's how I set that up with direnv.

The Problem

I have two GitHub accounts: lucasmccomb (personal) and a work account. Each has its own SSH key, its own gh auth token, and its own set of repos. The challenge is making sure that when I'm working in ~/code/work/, everything - git pushes, gh CLI commands, API calls - routes through the correct account without me thinking about it.

Git's built-in includeIf can handle some of this, but it only covers git config values (name, email, signing key). It doesn't touch the gh CLI, which uses its own auth system. I needed a solution that sets the entire shell environment per directory.

The Pieces

The setup has three layers:

1. SSH host aliases — route git push to the correct SSH key
2. direnv .envrc files — set GH_TOKEN and other env vars per directory
3. gh auth with multiple accounts — provide the tokens that direnv exports

SSH Config

SSH doesn't natively support "use this key for this directory." But it does support host aliases. By defining a custom hostname that maps to github.com with a specific key, you can control which identity git uses based on the remote URL.

# ~/.ssh/config

# Personal (lucasmccomb)
Host github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519

# Work
Host github-work
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_work
  IdentitiesOnly yes

The IdentitiesOnly yes line is important — it tells SSH to only offer the specified key, not every key in the agent. Without it, SSH might try your personal key first and succeed (or fail confusingly) before reaching the work key.

With this config, a repo cloned as git@github-work:org/repo.git will always use the work key, while git@github.com:lucasmccomb/repo.git uses the personal key. The hostname in the remote URL is what determines the identity.

direnv

direnv is a shell extension that loads and unloads environment variables based on .envrc files as you navigate directories. It's the glue that makes all of this automatic.

At the workspace root (~/code/), I have an .envrc that sets the default (personal) account:

# ~/code/.envrc
export GH_TOKEN="$(gh auth token --user lucasmccomb)"
export GH_ACCOUNT="lucasmccomb"

In the work directory, a second .envrc overrides it:

# ~/code/work/.envrc
export GH_TOKEN="$(gh auth token --user work-username)"
export GH_ACCOUNT="work-username"

direnv inherits from parent directories, so subdirectories of ~/code/work/ get the work token, while everything else under ~/code/ gets the personal token.

The GH_TOKEN environment variable is what the gh CLI and GitHub API clients check first — before any stored auth. By exporting it, every gh pr create, gh issue list, or API call in that shell session uses the correct account.

GH_ACCOUNT is a custom variable I set for my own tooling. Some of my scripts and hooks reference it to know which account context they're running in.

gh CLI Multi-Account Auth

The gh CLI supports multiple authenticated accounts. You register each one:

gh auth login --hostname github.com --user lucasmccomb
gh auth login --hostname github.com --user work-username

Once both are registered, gh auth token --user <account> returns the token for that specific account - which is exactly what the .envrc files call.

How It Comes Together

Here's what happens when I open a terminal and navigate:

~/ $ cd code/work/my-project
direnv: loading ~/code/work/.envrc
direnv: export +GH_ACCOUNT +GH_TOKEN

~/code/work/my-project $ gh api user --jq .login
work-username

~/code/work/my-project $ cd ~/code/lem-fyi-repos/lem-fyi-0
direnv: loading ~/code/.envrc
direnv: export ~GH_ACCOUNT ~GH_TOKEN

~/code/lem-fyi-repos/lem-fyi-0 $ gh api user --jq .login
lucasmccomb

No manual switching. No remembering which account is active. The directory determines the identity.

For git operations, the SSH host alias in the remote URL handles key selection independently. So git push in a work repo uses the work SSH key, and gh pr create in the same repo uses the work token - both automatically.

Setup Steps

If you want to replicate this:

1. Generate a separate SSH key for each account:

ssh-keygen -t ed25519 -C "personal@example.com" -f ~/.ssh/id_ed25519
ssh-keygen -t ed25519 -C "work@example.com" -f ~/.ssh/id_ed25519_work

2. Add each public key to the corresponding GitHub account (Settings > SSH Keys).

3. Configure SSH host aliases in ~/.ssh/config (as shown above).

4. Authenticate both accounts with gh:

gh auth login  # First account
gh auth login  # Second account (select "Login with a different account")

5. Install direnv and add the shell hook:

brew install direnv

# Add to ~/.zshrc (or ~/.bashrc):
eval "$(direnv hook zsh)"

6. Create .envrc files at the appropriate directory levels:

# Default account at workspace root
echo 'export GH_TOKEN="$(gh auth token --user personal-username)"' > ~/code/.envrc
echo 'export GH_ACCOUNT="personal-username"' >> ~/code/.envrc

# Override for work directory
echo 'export GH_TOKEN="$(gh auth token --user work-username)"' > ~/code/work/.envrc
echo 'export GH_ACCOUNT="work-username"' >> ~/code/work/.envrc

7. Allow the .envrc files:

direnv allow ~/code/.envrc
direnv allow ~/code/work/.envrc

8. Clone work repos using the SSH alias:

git clone git@github-work:org/repo.git

Why Not includeIf?

Git's conditional includes (includeIf) are the commonly recommended approach. You add something like this to ~/.gitconfig:

[includeIf "gitdir:~/code/work/"]
    path = ~/.gitconfig-work

This works well for git-specific config (user.name, user.email, signing key). But it has limitations:

• It only affects git config values — not shell environment variables
• The gh CLI ignores it entirely
• GitHub API clients, CI scripts, and other tooling that read GH_TOKEN aren't covered
• It doesn't compose well when you need the same directory to affect multiple tools

direnv solves this at a lower level. By setting environment variables, it works with any tool that reads from the environment — which is most of them.

That said, you can combine both approaches. Use direnv for GH_TOKEN and includeIf for git author identity if you want per-directory commit emails without setting them per-repo.

Gotchas

A few things I ran into:

• direnv needs explicit allow: Every time you create or edit an .envrc, you must run direnv allow. This is a security feature — it prevents untrusted repos from injecting env vars into your shell.
• Token refresh: gh auth token returns the currently stored token. If a token expires or gets revoked, you'll need to re-authenticate with gh auth login for that account.
• Existing clones: If you have repos already cloned with git@github.com:... URLs that should use a different account, update the remote: git remote set-url origin git@github-work:org/repo.git.
• SSH agent confusion: If you use an SSH agent with multiple keys loaded, the agent may offer keys in an unpredictable order. IdentitiesOnly yes in the SSH config prevents this by forcing SSH to use only the specified key.

This is one of those setups that takes 15 minutes to configure and then you never think about it again. The right account is always active, in every tool, based purely on where you are in the filesystem.

What I built

lem-fyi got its journal pipeline. Issue #1 (Blog MVP) closed after 20 PRs. The markdown build runs on Cloudflare Pages, pulls weekly data from GitHub/Spotify/YouTube/Analytics, feeds it to Claude, and outputs entries like this one. I redesigned the theme toggle (#21), fixed the TOC (#18), and added RSS/Atom feeds (#14). The site went from static placeholder to functional blog in 10 commits and 12,872 lines.

darkly-suite hit two milestones: Chrome Web Store compliance audit and OAuth-gated Stripe checkout. The compliance work (#304, #113) meant scrubbing host permissions, rewriting privacy forms to avoid ======= (pre-commit hook saw them as merge conflicts), and testing distribution flows with placeholder extension IDs. The checkout flow (#402, #411, #416) requires Google OAuth before payment so Stripe can prefill the customer's email. Chrome Identity isn't available in content scripts, so the subscribe page generates throwaway tokens instead of using the extension's token. I chose prefill over lock after weighing tradeoffs - standard SaaS pattern, lets users edit if needed.

Admin tooling improved: membership sorting by email and sign-up date (#445), email notifications via Resend for business events (#397, #409), and endpoint cleanup (#443). The status endpoint no longer falls back to email lookup - token + product + status is enough. Lifetime licenses correctly show stripe_subscription_id as NULL since one-time payments don't create subscriptions.

Multi-agent sessions landed 9 milestones across darkly-suite and lem-fyi. One gotcha: branch name collision between agents on issue #300 required renaming to 302-docs-distribution-test. Another: landing-suite has local copies of FAQ/Footer/Pricing alongside @darkly/landing-shared versions - both needed updates but grep only caught shared ones initially.

lem-photo got minor about page edits (#1068, #1066). Two commits, twelve lines changed.

59-day commit streak still going. 100 commits to darkly-suite this week.

What I consumed

Girl Talk topped the week - plunderphonics for deep focus during the compliance audit. The Durutti Column and The Who rounded out the rock mood. Aleksi Perälä's IDM came in when I needed to shift gears from OAuth debugging.

Watched a magnetic induction water heater build (Greenhill Forge) and an island floor installation (Islestead). Both scratched the same itch: people making physical things with their hands while I push pixels.

Still HereGirl Talk

OtisThe Durutti Column

Baba O'RileyThe Who

UK74R1406090Aleksi Perälä

How I moved

59,675 steps for the week - 13,740 on Sunday alone. Six workouts: two strength sessions, an elliptical day, and three shorter sessions including a sauna. Sleep averaged 6.4 hours with a resting heart rate of 52. Not my best sleep week - two nights didn't register - but the consistency held.

Reach

712 page views across all sites. lem.fyi's AI-enabled SWE system post pulled 78 views. darklysuite.com got 438 views, mostly landing page and admin dashboard traffic. lem.photo stayed quiet at 54 views, mostly API endpoints.

Closing

This was a week of systems. The journal pipeline writes itself now. The OAuth checkout flow handles real money. The compliance audit clears the path to Chrome Web Store publication. All infrastructure work - the kind that compounds.

This post is a comprehensive walkthrough of what I've built, how it works, and what I've learned.

The Foundation: claude-dotfiles

Everything starts with a single GitHub repository: claude-dotfiles. This repo is the single source of truth for my entire Claude Code development workflow. It contains global instructions, enforcement hooks, slash commands, MCP server configs, plugin settings, and workflow documentation, all version-controlled and deployable to any machine.

What's in the repo

claude-dotfiles/
├── CLAUDE.md                    # Global instructions (~627 lines)
├── settings.json                # Hooks, permissions, plugins (template)
├── mcp.json                     # MCP server configs (template)
├── .claudeignore                # Template ignore file for repos
├── github-repo-protocols.md     # Full repo lifecycle guide (16KB)
├── multi-agent-system.md        # Multi-agent coordination
├── log-system.md                # Session logging documentation
├── commands/                    # 9 slash commands
│   ├── startup.md
│   ├── commit.md
│   ├── pr.md
│   ├── sync.md
│   ├── new-issue.md
│   ├── gs.md
│   ├── promote-rule.md
│   ├── dotsync.md
│   └── walkthrough.md
├── hooks/                       # 4 Python enforcement hooks
│   ├── auto-approve-bash.py
│   ├── auto-approve-file-ops.py
│   ├── enforce-git-workflow.py
│   └── enforce-issue-workflow.py
├── log/                         # Log analysis utilities
├── setup.sh                     # First-time setup script
└── sync-config.sh               # Reverse-sync config changes

One-command deployment

The setup.sh script handles everything:

1. Creates ~/.claude/ if it doesn't exist
2. Backs up any existing settings.json
3. Creates symlinks for files that don't need path templating (CLAUDE.md, commands/, hooks/, docs)
4. Generates settings.json and mcp.json from templates using sed "s|__HOME__|$HOME|g" to expand real paths
5. Optionally enables GitHub Repo Protocols (toggled by symlink presence)
6. Adds GITHUB_TOKEN to ~/.zshrc if missing
7. Checks prerequisites (gh CLI, TypeScript LSP)

The key design decision here is the split between symlinked files and generated files. Files like CLAUDE.md and commands/ are identical across machines, so they're symlinked directly. But settings.json and mcp.json contain absolute paths (/Users/lem/code/...), so they use __HOME__ placeholders in the repo and get generated with real paths at setup time.

Reverse sync

When I modify settings locally (add a new permission, configure a new hook), I run /dotsync, which calls sync-config.sh. This script reads the live ~/.claude/settings.json, replaces the real home path back to __HOME__, compares to the repo version, writes if changed, and pushes to GitHub. On another machine, a git pull plus re-running setup.sh applies the updates.

Standardized .claudeignore

Every repo gets the same .claudeignore template. It excludes node_modules/, dist/, lock files, IDE configs, binary/media files, .env files, and Supabase temp directories. This keeps Claude's context window clean and focused on actual source code.

The Permission System

The settings.json file contains an exhaustive permission configuration with approximately 860 allow entries and 13 deny entries.

The deny list

The deny list is the safety layer. It blocks destructive operations at the tool level:

rm, rmdir                          # File deletion
git reset --hard                   # Destructive git resets
git push --force, git push -f      # Force pushes
git clean                          # Working tree cleaning
git branch -D                      # Force-delete branches
docker rm, docker rmi              # Container/image deletion
docker system prune                # Docker cleanup
kubectl delete                     # Kubernetes resource deletion
DROP, TRUNCATE, DELETE FROM        # Destructive SQL

The philosophy: AI agents should never be able to accidentally destroy work. These operations require explicit human confirmation.

The allow list

The allow list covers essentially every CLI tool I use: git, gh, npm/yarn/pnpm/bun, cargo/rustup, python/pip, docker, kubectl, terraform, supabase, wrangler, aws/gcloud/az, psql/mysql/redis-cli, ffmpeg, and hundreds more. The breadth eliminates permission prompts for legitimate development commands while the deny list catches the dangerous ones.

The bug that inspired the hooks

Claude Code has known bugs (GitHub issues #15921 and #13340) where the VSCode extension ignores settings.json permissions entirely, and piped commands bypass the allow list. I documented this in a bug report and built a workaround: Python hooks that re-implement the permission logic at the tool-use interception layer, where they're reliably enforced regardless of the client.

Enforcement Hooks

Four Python scripts intercept Claude Code's tool calls at different layers. They're the governance framework that ensures AI agents follow the same workflow rules as human developers.

enforce-issue-workflow.py (UserPromptSubmit)

Fires on every user prompt. It detects work-request verbs (update, fix, add, create, implement, build, change, modify, refactor, etc.) and filters out questions (starts with what/why/how, ends with ?, contains explain/describe/list).

When a work request is detected, it injects a workflow reminder into Claude's context:

STOP - Before making ANY code or file changes, you MUST:
1. CHECK: Does a GitHub issue exist for this work?
2. CREATE BRANCH: git checkout -b {issue-number}-{description}
3. IMPLEMENT: Make your changes
4. COMMIT & PR with issue-number prefix

This hook is toggled by the presence of ~/.claude/github-repo-protocols.md as a symlink. Remove the symlink and the hook becomes a no-op. This lets me disable the full issue-tracking workflow for quick experiments without modifying any code.

enforce-git-workflow.py (PreToolUse:Bash)

Intercepts every git commit and git push command. It enforces three rules:

1. No commits on main: Must use a feature branch. The hook detects the current branch and blocks if it's main or master.
2. Commit message format: Must match ^\d+: (issue number prefix like 42: Fix the login bug). Parses the message from -m or --message flags. Skips validation for heredoc-style messages (can't parse them reliably), merge commits, and amend-without-new-message.
3. No pushes to main: Detects if the push target resolves to main (handles HEAD, explicit main, no refspec).

There's an allowlist (DIRECT_TO_MAIN_REPOS) that exempts the dotfiles repo itself, and an emergency bypass via ALLOW_MAIN_COMMIT=1 environment variable.

auto-approve-bash.py (PreToolUse:Bash)

The workaround for the settings.json permission bug. This hook reads all Bash(pattern) entries from ~/.claude/settings.json at runtime. For each incoming Bash command, it checks the deny list first (higher priority), then the allow list. Pattern matching handles :* suffix (prefix match), * suffix (prefix match), and startswith fallback.

If a command matches a deny pattern, it returns permissionDecision: deny with a user-readable reason. If it matches an allow pattern, it returns permissionDecision: allow. If no match, it exits silently and falls through to Claude's default permission system.

auto-approve-file-ops.py (PreToolUse:Read/Edit/Write)

Same rationale as the Bash hook, same bug. Loads Read(...), Edit(...), Write(...) path patterns from settings. Normalizes paths, handles ** glob as prefix match, falls back to fnmatch. Currently auto-approves all file operations within ~/code/**, ~/.claude/**, and /tmp/**.

Slash Commands

Nine custom slash commands standardize the most common development workflows. Each is a markdown file in commands/ with frontmatter specifying description, allowed-tools, and optional argument-hint. They use ! prefix syntax to execute shell commands inline at invocation time.

/startup (Session Initialization)

The most complex command at ~250 lines. It runs at the beginning of every Claude Code session and bootstraps the agent's context:

Section 0: Checks if the current directory is a git repo. If not, offers alternatives.

Section 1 (Session Logging): Pulls the latest logs from the centralized log repo. Derives agent identity from the working directory suffix (lem-work-2 -> agent-2). Checks for today's log file. If the log repo has uncommitted changes older than 60 minutes, auto-commits and pushes them.

Section 2 (Git Status): Current branch, ahead/behind main, working directory cleanliness.

Section 3 (Open PRs): Lists all open pull requests for the current repo.

Section 4 (Open Issues): Lists issues by status: all open, in-progress, in-review. This gives the agent a clear picture of what work is available.

Section 5 (Dependencies): Checks if package.json exists, whether lock files are present, and if dependencies might be out of date relative to main.

After running all sections, it presents the agent with a prioritized recommendation of what to work on next.

/commit

Stages changes, runs lint/build verification, and commits with the enforced {issue_number}: {description} format. Reports the commit hash on success.

/pr

The full PR workflow: pre-flight cleanliness check, lint/build/test verification, rebase on origin/main, push with -u, check for PR template files in two locations (repo root and .github/), create the PR with gh pr create, update the issue label from in-progress to in-review, and report the PR URL.

/sync

Fetch origin and rebase the current branch on main. Handles uncommitted changes (offers to stash, commit, or abort). Reports any conflicts. Reminds about --force-with-lease for already-pushed branches.

/new-issue

Creates GitHub issues with the proper label taxonomy. Gathers title, type, and description. Maps types to labels (feature -> enhancement, bug -> bug). Supports a special human-agent type for tasks requiring manual intervention (env vars, account setup, etc.), which auto-assigns to the repo owner.

/gs

Quick git status overview: branch name, remote tracking, working directory status, sync status relative to main, last 5 commits, and open PRs. Summarizes the state and recommends the next action.

/promote-rule

Analyzes the current repo's CLAUDE.md for rules that should be promoted to the global config. Checks for explicit <!-- CANDIDATE:GLOBAL --> markers, detects implicit candidates (rules that are repo-agnostic), reads 2-3 other CLAUDE.md files to identify patterns, checks against the global config for duplicates, and presents findings in a table with a recommendation.

/dotsync

Runs sync-config.sh --dry first for a preview of what will change, then runs the actual sync. Reports what was updated and whether the changes were committed and pushed.

/walkthrough

Activates step-by-step guided mode for complex tasks. Identifies the task, breaks it into discrete steps, and presents one step at a time with a progress counter (Step N/Total). Waits for the user to confirm completion before proceeding to the next step. Never skips ahead.

The /audit Skill

Beyond slash commands, I've built a comprehensive codebase audit system as a Claude Code skill. The /audit command is a 7-phase self-healing system that launches 8 parallel agents, auto-fixes what it can, and creates GitHub issues for what needs human review.

Phase 1: Pre-Flight

In fix mode (the default), it verifies the working directory is clean and creates a checkpoint branch (audit-checkpoint-YYYYMMDD-HHMMSS) for rollback. If there are uncommitted changes, it stops and offers options.

Phase 2: Discovery

Detects monorepo structure (checks for apps/, packages/, workspaces, pnpm-workspace.yaml), identifies the tech stack (TypeScript, React, package manager), reads existing CLAUDE.md and ESLint configs, and determines the audit scope.

Phase 3: Parallel Audit (8 Agents)

Eight Task agents launch simultaneously, each covering a different category:

Each agent reports structured JSON with severity, file/line, description, auto-fixability status, and fix confidence level.

Phase 4: Classify

All findings are collected, deduplicated, and split into two queues: auto_fix_queue (high-confidence fixable) and human_review_queue (everything else).

Phase 5: Fix Cycle

For each auto-fixable finding, a Task agent implements the fix. Then the verification suite runs (lint, type-check, tests). If all pass, the fix is committed as an atomic commit (audit: {category} - {brief title}). If any verification fails, the fix is reverted with git checkout -- . and moved to the human review queue.

Phase 6: Summary

Displays results in a table by category and severity, with fix results (successfully fixed / failed verification / skipped for human review), a list of all commits made, and rollback instructions pointing to the checkpoint branch.

Phase 7: Issue Creation

Optionally creates GitHub issues for findings that need human review. Labels them with audit and needs-human-review. Groups findings by category into single issues. Checks for existing audit issues to avoid duplicates on re-runs.

Reference Files

The skill includes five reference documents that the audit agents consult:

• security-patterns.md: OWASP Top 10 mapping, regex patterns for detecting API keys (OpenAI sk-, GitHub ghp_, AWS AKIA), injection patterns, auth weaknesses, insecure configurations, severity guidelines
• architecture.md: Clean Architecture patterns, god object detection thresholds (>1000 lines, >20 methods), circular dependency detection via madge, feature-based vertical slice recommendations
• code-quality.md: Martin Fowler refactoring patterns, cyclomatic complexity thresholds (>10/function), cognitive complexity (>15), nesting depth (>4 levels), naming consistency
• fix-patterns.md: Implementation guides for each fix type with when-to/when-not-to guidance, verification commands by project type
• output-template.md: GitHub issue templates with severity-based sections, collapsible details for medium/low findings, rollback instructions

MCP Servers

Seven MCP (Model Context Protocol) servers are configured globally, giving Claude Code direct access to external services:

The MCP config uses __HOME__ placeholders in the dotfiles repo and gets expanded to real paths by setup.sh. This means the same config template works on any machine without modification.

Having Supabase as an MCP server is particularly valuable for debugging. Instead of using browser automation to diagnose database issues (slow, unreliable), I can run SQL directly, check logs, and apply migrations from within Claude Code. The debugging priority I've established is: Supabase MCP first for data issues, server logs for API issues, browser automation only as a last resort for UI issues.

Plugins

Fourteen Claude Code plugins extend the base functionality. Grouped by function:

Code Quality

• code-review: Multi-agent PR review that examines code changes across multiple dimensions
• pr-review-toolkit: Comprehensive review agents including a silent-failure hunter, code simplifier, comment analyzer, test analyzer, and type design analyzer
• security-guidance: Real-time security checks on file edits as they happen

Development

• feature-dev: Guided feature development with codebase analysis and architecture-focused planning
• frontend-design: Production-grade UI generation that avoids generic AI aesthetics
• typescript-lsp: TypeScript language server integration for type-aware code intelligence
• serena: Semantic code analysis and understanding

Integration

• github: GitHub platform integration (issues, PRs, branches, releases)
• supabase: Supabase project management and database operations
• playwright: Headless browser automation for E2E testing and screenshots
• figma: Figma design tool integration for implementing designs from Figma files
• greptile: Deep codebase search and understanding

Workflow

• hookify: Create custom Claude Code hooks from conversation analysis
• explanatory-output-style: Educational/explanatory output mode that provides insights about implementation choices

All plugins are pre-authorized in the permissions system. If a plugin is installed, the user has already decided to grant access. No per-operation permission prompts.

Multi-Agent Orchestration

This is the core of the system. Four Claude Code agents work in parallel on the same codebase without file conflicts, git collisions, or duplicated work.

Architecture

Each project that supports multi-agent work uses four independent clones:

~/code/{repo}-repos/
├── {repo}-0/           # Clone 0 (agent-0)
├── {repo}-1/           # Clone 1 (agent-1)
├── {repo}-2/           # Clone 2 (agent-2)
└── {repo}-3/           # Clone 3 (agent-3)

Each clone is a full, independent git repository with its own .git/ directory, branches, stash, reflog, and node_modules/. There are no shared resources between clones, which means:

• Full isolation: Each agent has its own git state, its own branches, its own stash. No cross-agent interference.
• Standard git workflows: Every git command works exactly as documented. No special rules or workarounds.
• Independent fetches: Each clone fetches on its own schedule. No shared object store to reason about.

Each agent runs in its own tmux pane, visible simultaneously. I manage all four from my phone via Blink terminal (iOS) through Mosh + Tailscale, which survives WiFi drops and device sleep.

The evolution from worktrees to clones

The original architecture used a bare git repo plus four worktrees. The theory was compelling: shared git object store, single fetch updates all worktrees, zero duplicated data. After several weeks of running this across four repos with four agents each, the theory fell apart.

What broke:

1. Branch locking was the killer issue. Worktrees can't have the same branch checked out in two places. This broke standard git checkout -b workflows. The enforce-git-workflow hook and issue-workflow hook both assumed standard branch creation. Agents would create a branch but commits would end up on the wrong branch because the worktree was locked to its parking branch.

2. Shared stashes were a liability. Worktrees share the reflog and stash through the bare repo. An agent stashing changes in one worktree could interfere with another agent's stash pop.

3. "Never checkout main" rule was confusing. Local main couldn't exist in bare repo worktrees. Every agent and every hook had to use origin/main everywhere. This constantly tripped up agents and broke workflow assumptions.

4. Storage savings were negligible. The bare repos were 2-9MB each. Duplicating across four clones adds at most 36MB total. node_modules/ (the real disk consumer) was already per-worktree anyway.

5. Single fetch was rarely useful. Agents fetch at different times. The shared-fetch advantage only matters if all agents need the same new commits simultaneously, which almost never happens.

6. Simpler mental model wins. A clone is a clone. Every developer and every AI agent understands it. Worktrees are a git power feature that adds cognitive overhead for agents that already have enough to track.

The migration was straightforward: about 10 minutes per project. Delete the bare repo, clone four times, copy over .env files and node_modules/. The slightly higher disk usage is worth the dramatically simpler mental model.

Agent identity

Agent number is derived automatically from the working directory name suffix:

AGENT_NUM=$(basename "$PWD" | grep -oE '[0-9]+$' || echo "0")

No configuration needed. The agent knows who it is from where it's running.

Issue claiming protocol

Before any agent writes a single line of code, it must claim the issue through a multi-check protocol:

1. Check GitHub labels: Skip if any agent-* or in-progress label exists

   gh issue view {number} --json labels --jq '[.labels[].name]'

2. Check sibling clone branches: Skip if any clone already has a branch starting with {issue-number}-

   for dir in $(find ~/code/{repo}-repos/ -maxdepth 1 -name "{repo}-[0-9]*" -type d); do
     echo "$(basename $dir): $(git -C $dir branch --show-current)"
   done

3. Label the issue immediately (before creating a branch):

   gh issue edit {number} --add-label "in-progress" --add-label "agent-{N}"

4. Verify labels applied before proceeding

Both checks must be clear. If there's a conflict (two agents try to claim simultaneously), the human supervisor resolves it. In practice, this hasn't been an issue because the label check and branch check together create a reliable mutex.

Git workflow

Standard git workflows apply. No special rules needed:

• Branch from main: git checkout main && git pull && git checkout -b {issue}-{desc} or directly git checkout -b {issue}-{desc} origin/main. Both work.
• After PR merge: Return to main: git checkout main && git pull && git branch -d {old-branch}
• Stashes are per-clone: Each agent has its own stash. No cross-agent interference.
• npm install is per-clone: Each has its own node_modules/.
• Env files are per-clone: .env and .env.local must be copied individually.

Session Logging System

The coordination layer that makes multi-agent work possible. Without it, agents would duplicate work, lose context between sessions, and have no awareness of what other agents are doing.

Architecture

A centralized git repo (lem-agent-logs) where every agent writes structured entries:

~/code/lem-agent-logs/
├── biotechstonks/
│   └── 20260203/
│       ├── agent-0.md
│       └── agent-1.md
├── darkly-suite/
│   └── 20260216/
│       ├── agent-0.md
│       ├── agent-1.md
│       ├── agent-2.md
│       └── agent-3.md
├── gmail-darkly/
│   └── 20260212/
│       ├── agent-0.md
│       ├── agent-1.md
│       └── agent-2.md
└── ... (14 projects tracked)

Each agent writes exclusively to its own file. This eliminates merge conflicts entirely. When multiple agents push to the log repo simultaneously, git pull --rebase resolves cleanly because the files never overlap.

Mandatory log triggers

The log must be updated immediately at each of these events:

1. After every git commit: Issue number, branch, what changed, decisions made, gotchas encountered
2. After creating a PR: Issue number, PR URL, mark #in-review
3. After PR merge: Mark #completed, commit and push the log repo
4. After closing an issue: Resolution summary, mark #completed, commit and push
5. Before context compaction: Current WIP state, uncommitted changes, next step (this preserves context when Claude's conversation gets too long and earlier messages are compressed)

Cross-agent awareness

At session start (/startup), every agent reads other agents' logs for today's date directory. This builds a "Cross-Agent Awareness" section that documents what each sibling is working on:

## Cross-Agent Awareness

- **Agent-1** (today): Working on issue #84, created PR #87. In-review.
- **Agent-2** (today): Idle on agent-2 branch.
- **Agent-3** (today): Working on issue #95 (bundle completion).

The agent uses this to avoid claiming issues that are already in flight, even if the GitHub labels haven't been updated yet.

Log file format

Real example from a session:

# agent-0 — 20260217 — darkly-suite

> Continued from previous session (20260216)

## Session Start

- **Time**: 2026-02-17 afternoon ET
- **Branch**: `main` (clean, up to date)
- **Previous session context**: Completed massive monorepo buildout...

## Work Log

### Issue #92 — Fix mini-panel white background in dark mode

- **Branch**: `92-fix-mini-panel-dark-mode` (from `origin/main`)
- **PR**: #93 — https://github.com/lucasmccomb/darkly-suite/pull/93
- **Merged**: PR #93 → `4f124a1` on main #completed

**Wrong fix (commit 1)**: Added settings-container class to mini-panel.
This broke layout because .settings-container has height: 100% and display: flex...

**Correct fix (commit 2)**: Added mini-panel to the CSS re-inversion rules.

**Lesson**: When working with filter-based dark mode, prefer CSS-only fixes over DOM class changes.

Key elements: continuation notes linking to previous sessions, issue/branch/PR references with URLs, status tags (#completed, #in-progress, #blocked), decision capture ("wrong fix / correct fix"), and lesson sections that preserve institutional knowledge across sessions.

Per-Project Configuration Layering

Claude Code loads all CLAUDE.md files in the directory hierarchy from root to working directory. This creates a three-tier inheritance system:

1. Global (~/.claude/CLAUDE.md): Universal rules that apply everywhere. No AI attribution in commits, PR template usage, git workflow, session logging, code standards, security, MCP tool permissions.

2. Workspace (~/code/CLAUDE.md): Describes the multi-project directory layout, repo shorthand references, git aliases.

3. Project ({repo}/CLAUDE.md): Project-specific build commands, tech stack, unique behaviors.

How projects specialize

Project files that say "global instructions are in ~/.claude/CLAUDE.md" are documenting what Claude Code already handles automatically. It's a human-readable reminder that these files intentionally contain only project-specific additions.

Quality Gates

Quality is enforced at multiple levels, from individual keystrokes to deployment.

Pre-commit (every commit)

A global git hook runs on every commit across all repos:

• gitleaks: Scans for accidentally committed secrets (API keys, tokens, passwords)
• lint-staged: Runs ESLint with --fix and TypeScript type-checking on staged files only

Pre-push (every push)

The most sophisticated gate. lem-photo's pre-push hook is 113 lines and mirrors the full CI pipeline:

1. Lint client workspace
2. Lint server workspace
3. Type-check client
4. Type-check server
5. Run client tests
6. Run server tests
7. Build client
8. Build server + verify server/dist/ is committed and up-to-date

A rapid mode (SKIP_CHECKS=1 git push) skips steps 1-6 but still builds both workspaces and verifies the server dist. The hook uses colored output and timing for each step.

Other projects adapt this pattern to their needs. nadaproof builds its shared package first, then runs the standard lint/type-check/test/build sequence. The darkly extensions run lint, type-check, tests, and webpack build.

CI/CD (GitHub Actions)

Where enabled, CI runs on PR events and push-to-main. The pipeline typically mirrors the pre-push hook exactly, ensuring that local and CI checks are identical. Some projects (lem-photo) have disabled CI to save GitHub Actions minutes and rely entirely on the pre-push hook.

Automated accessibility testing

All darkly extensions include WCAG AA contrast ratio tests that run programmatically across every theme preset and color pairing. The test computes relative luminance using the WCAG 2.1 formula and asserts >= 4.5:1 for body text and >= 3:1 for UI components. This catches accessibility regressions automatically across 78+ theme/color combinations.

Coverage thresholds

Test coverage is enforced at the framework level. lem-photo requires 60% coverage on the client and 70% on the server. Vitest fails the run if thresholds aren't met, which means the pre-push hook blocks the push.

Real Results

darkly-suite: Full monorepo in 2 days

Four agents working in parallel built an entire pnpm monorepo from scratch:

• 9 packages (shared core, 3 site packages, 4 extension packages, landing page)
• 4 Chrome extensions (Gmail, Sheets, Docs, bundle)
• Self-hosted payment system (Cloudflare Pages Functions + D1 + Stripe)
• 23 PRs merged across 2 days
• All tests passing, all extensions functional

The git log of the log repo shows the real-time coordination: four agents committing to the shared log repo within seconds of each other, each working on a different package, with git pull --rebase resolving cleanly because each agent writes to its own file.

Day 1 parallel streams:

• Agent-0: Scaffolded monorepo, created all 61 GitHub issues, coordinated merges
• Agent-1: Built site packages and individual extensions
• Agent-2: Built CSS prefix loader, webpack factory, bundle extension, CI
• Agent-3: Built landing page, payment APIs, D1 schema, marketing pages

gmail-darkly: 50 issues in a sprint

50 agent issues closed across 7 PRs, with 120+ tests passing. 18 PRs merged on day 1 alone. The extension shipped with self-hosted Stripe payments (no SDK, raw crypto.subtle HMAC-SHA256 for webhook verification), WCAG-validated themes, InboxSDK integration, and a full admin portal.

lem-photo: 2,267+ tests

The most tested project in the portfolio:

• ~1,388 client tests (Vitest + React Testing Library + MSW in strict mode)
• ~764 server tests (Vitest + Supertest)
• ~89 Playwright E2E tests with programmatic auth (two users: regular + admin)
• 26 Python pytest tests for the facial recognition microservice
• Coverage thresholds enforced (60% client, 70% server)

The Playwright setup authenticates via Supabase REST API directly (not through browser UI), serializes session state as JSON, and injects it into browser contexts via custom fixtures. This makes E2E tests deterministic and headless-friendly.

biotechstonks: AI pipeline processing 17 RSS feeds

A 4-agent n8n workflow running daily at noon:

• 4 Claude Opus instances processing different RSS feed categories in parallel (Reddit, News/PR Newswire, BioSpace, GlobeNewswire)
• 17 RSS feed tools across the 4 agents
• Structured output parsing (companies, topics, sectors, action classification)
• Deduplication via source_url unique constraint + upsert RPC
• JSONB tags with GIN indexes for flexible querying

How This Scales

The system I've built for personal use maps directly to a team environment.

The consultant starter kit

The claude-dotfiles repo becomes a team template. Fork it, swap in client-specific values (GitHub org, Supabase project, n8n instance), run setup.sh, and every developer has identical enforcement hooks, quality gates, slash commands, and MCP connections from day one. No manual configuration of individual repos.

Boilerplate project templates

A library of pre-configured project templates, each with CI/CD pipelines, test frameworks, pre-push hooks, and CLAUDE.md project instructions already baked in. A new client engagement starts with picking the right template (React + Express, Chrome Extension, n8n pipeline, etc.), spinning up the repo, and the quality infrastructure is already in place.

Multi-consultant coordination

The session logging system scales naturally. If three consultants are working on the same client project, they each write to their own log file in the same date directory. At session start, they read each other's logs for awareness. The same coordination layer that prevents my four personal agents from stepping on each other works across a team.

This could be adapted to integrate with external tools. An MCP server configured to update Jira tasks or Confluence docs as work progresses would give non-technical stakeholders visibility into what's happening without requiring them to read git logs.

Shared infrastructure

For MCP tooling, shared remote servers (GitHub, Supabase, n8n) rather than local instances. Onboarding a new team member is just connecting to existing infrastructure rather than rebuilding it from scratch.

The enforcement hooks as governance

The hooks ensure that AI agents follow the same workflow rules as human developers. No special treatment, no shortcuts. Every commit references an issue. Every push passes the full verification suite. Every destructive operation is blocked. This is the kind of policy layer that enterprises need when adopting AI in their development workflows.

Closing Thoughts

The most interesting thing about this system isn't any individual component. It's how they compose. The dotfiles repo makes the system reproducible. The hooks make it self-enforcing. The logging makes it observable. The clones make it parallel. And the per-project CLAUDE.md files make it adaptable.

A solo developer with four AI agents and the right infrastructure can produce output that would typically require a small engineering team. But the productivity multiplier isn't just about speed. It's about maintaining quality at scale through automated enforcement.

The system works not because the AI models are perfect, but because the infrastructure around them is designed to catch mistakes, prevent conflicts, and preserve context. That's the real lesson: AI enablement isn't about the models. It's about the workflow you design around them.