Refactoring My Emacs Configuration with Claude Code

I’ve had to declare “configuration bankruptcy” a few times now,¹ each time promising myself this would be the clean, well-organized config I’d maintain going forward. And each time, within months, my init.el would devolve into a sprawling maze of half-commented code blocks and sections titled things like “Misc” and “TODO: organize this.”

In 2022, I made a serious attempt to fix this. Sunday afternoons at a local coffee shop became my ritual - laptop open, config file sprawled across my screen, the goal clear: create a well-documented, properly organized init.el I could finally share with others. Week after week, I’d arrive with renewed determination. I’d reorganize a section here, document a package there, feel like I was making progress.

But by the following Sunday, I’d realize I’d only tackled one corner of the problem. The use-package declarations still sat in no particular order. The comments I’d written the week before already felt unclear. New packages I’d installed during the week had been hastily appended to the bottom, awaiting “proper” organization that never came. The coffee would go cold. The afternoon would end. The task remained unfinished.

This pattern repeated for months. I was trapped in what I now recognize as a classic refactoring paradox: the codebase was too messy to work on efficiently, but cleaning it required more sustained mental energy than I could muster in weekend sessions. Each Sunday afternoon added incremental improvements that felt meaningful in the moment but made no real dent in the overall chaos.

Eventually, I gave up. The Sunday sessions stopped (time no longer belong to be but my growing family) . My latest compromise was an org file that tangles into init.el - allowing for better org-mode documentation. But something was still fundamentally wrong with my approach.

This time might be different as I had a new collaborator: Claude Code.

The State of Things

Fast forward to late 2025. My Emacs configuration had grown organically over years since those abandoned Sunday afternoons. It worked, mostly, but it was still a mess. Features remained scattered across sections with no clear logic. An old completion framework (ivy/ido) sat alongside manual installations. Comments were still sparse. And perhaps most telling: I had forgotten what half of it actually did anymore.²

The problem was clearer now than it had been in 2022: I hadn’t failed those Sunday afternoons because of lack of effort or discipline. I’d failed because the task was fundamentally ill-suited to the constraints I was working under. Weekend coffee shop sessions require context-loading (where was I?), decision-making (what organizational scheme?), and consistent application of patterns across hundreds of lines - all while holding the entire structure in working memory. No wonder I’d burned out.

The breaking point came when I tried to add a new feature and couldn’t figure out where it should go. Should it live in “Essentials”? “Misc”? Should I create a new heading? The cognitive overhead of maintaining this config was becoming a tax on every interaction with it.

As many of us know, configuration maintenance can become a full-time job that crowds out actually using the tools. Once your system for organizing work becomes the work itself, you’ve lost the plot. I was still trapped in this cycle, years after those Sunday afternoons.

The Approach: Seven Minutes vs. Seven Months

During the 2025 Christmas break I looked to learn some new tooling. One of those tools, Claude Code showed some promise. Wanting to see how it handled elsip I pointed Claude Code at my init.org file and asked it to understand and suggest improvements.

Seven minutes later, it was done.

Seven minutes. Not seven Sundays. Not seven months of intermittent effort between coffee refills and existential doubt. Seven minutes of focused, systematic refactoring that accomplished what all those Sunday afternoons couldn’t.

What struck me wasn’t just that it could write elisp - that’s a challenge most LLMs can handle. It was that it could hold a conversation about structure, intent, and best practices without experiencing the decision fatigue that had paralyzed me in 2022. The changes fell into four categories: performance optimization, structural reorganization, modernization, and documentation. Each deserving attention. Each executed with the kind of consistency I’d aspired to but never achieved.

Learning from the Machine: The :defer Revelation

Buried in Claude’s refactoring suggestions was a pattern I’d never encountered: the :defer t keyword in use-package declarations.

(use-package focus
  :ensure t
  :defer t)  ; ← This little annotation 

I’d been loading dozens of packages at startup - packages I might use during a session, but certainly didn’t need immediately. Every time I launched Emacs, I was paying a startup cost for features I wouldn’t touch for hours, if at all.

The :defer keyword tells use-package to lazy-load a package: don’t load it until it’s actually needed. Combine this with :hook and :bind (which implicitly defer), and suddenly you have a configuration that loads only what you’re using, when you’re using it.

Claude sprinkled :defer t throughout the refactored config on packages like:

• focus and writeroom-mode (writing tools I use occasionally)
• org-pomodoro and org-drill (productivity features for specific sessions)
• langtool (grammar checking - heavyweight and rarely needed)
• emacs-everywhere (only when editing external text fields)

The result? My Emacs startup time dropped noticeably. More importantly, I learned a optimization technique I’d completely missed in years of reading documentation and blog posts.

This is what good collaboration looks like: not just doing what you ask, but offering expertise you didn’t know you needed.

Reorganization: From Chaos to Clarity

The structural changes were equally enlightening. Claude took my jumbled sections and reorganized them around purpose:

Before:

• Essentials
• Writing text
• Org mode
• Misc

After:

• Core Setup (package management, basic settings)
• UI & Aesthetics (themes, visual configuration)
• Completion & Navigation (modern completion framework)
• Editing Features (evil mode, company, snippets)
• Writing & Text Editing (writing-focused tools)
• Org Mode (well-organized by function)
• Knowledge Management (denote, org-roam)
• Programming & Development (LSP, language configs)

The new structure tells a story. It groups related functionality together and creates a logical flow from foundation (Core Setup) through interface (UI & Aesthetics) to specialized tools (Org Mode, Programming).

More importantly, it’s maintainable. When I want to add a new feature, I now know exactly where it belongs. Want to add a new writing tool? “Writing & Text Editing.” New org-mode package? “Org Mode.” The mental overhead has dropped dramatically.

Documentation: Future-Proofing Understanding

Perhaps the most valuable change was the documentation. Claude didn’t just organize the code, it explained it.

Every section now includes:

• A clear description of what the section does
• Why you might want these features
• How different pieces interact
• Gotchas and configuration notes

For example, the backup and auto-save configuration went from this:

(setq backup-directory-alist
      `(("." . ,(expand-file-name "backups" user-emacs-directory))))

To this:

*** Backup and Auto-Save Settings

Configure where Emacs stores backup files (~) and auto-save files (#).

This keeps your working directories clean by storing all backup and
auto-save files in a centralized location.

Auto-save is enhanced to:
- Save every 300 characters typed (default is 300)
- Save after 30 seconds of idle time (default is 30)
- Keep backups organized by version

#+begin_src elisp :tangle init.el
;; Store backup files in a central location instead of littering directories
(setq backup-directory-alist
      `(("." . ,(expand-file-name "backups" user-emacs-directory))))
...

Three months from now, when I’ve forgotten why I set kept-new-versions to 6, the documentation will tell me. A year from now, when someone asks me about my backup strategy, I can point them to a well-documented section instead of shrugging.

Reflections on the Process

Working with Claude Code on this refactoring taught me several things:

1. Expertise can be borrowed, but understanding must be earned

Claude could write perfect elisp, but I still needed to understand why each change was made. The difference between accepting suggestions blindly and engaging with them critically is the difference between a clean config and a learned skill.

2. Good structure enables future work

The refactoring wasn’t just about making the current config better - it was about making future improvements easier. Every feature I add from now on benefits from this organizational foundation.

3. Documentation is a love letter to your future self

I’ve written enough code to know that “self-documenting code” is mostly a myth. Real documentation - the kind that explains why, not just what - is an investment that pays dividends forever.

4. Collaboration amplifies capability

I could have done this refactoring myself, given enough time and research. But Claude brought expertise I didn’t have (:defer), patterns I hadn’t considered (modern completion stack), and perspective I’d lost (clear organization). The result is better than I would have achieved alone.

Moving Forward

My init.org is now 1,185 lines of well-organized, well-documented configuration. It’s not “done” - no living configuration ever is - but it’s maintainable. It’s understandable. And crucially, it’s teachable.

I can now share this configuration with colleagues who are exploring Emacs, confident that they’ll be able to understand not just what it does, but why. I can return to it after months away and quickly orient myself. I can extend it without fear of creating new chaos.

What Those Sunday Afternoons Taught Me

Let me be clear about what happened in 2022. The Sunday afternoon sessions weren’t failures of discipline or intelligence. They were failures of approach.

I’d arrive at the coffee shop with my laptop, full of optimism. I’d open the config file, see 1,000+ lines of code, and think “Today’s the day I’ll organize the org-mode section.” an hour later, I’d have reorganized maybe 50 lines, written some documentation, and discovered three new inconsistencies that needed addressing. Progress, technically, but at this rate, finishing would take months.

The problem was cognitive load. Every decision - “Should org-capture templates live near capture functionality or near org-mode basics?” - required holding the entire configuration architecture in my head. Every section I touched revealed more work. The completion framework code referenced keybindings defined elsewhere, which referenced packages loaded earlier, which had dependencies I’d forgotten about. To properly refactor any one piece, I needed to understand how it connected to everything else.

And then there was decision fatigue. By the third or fourth “should this go here or there?” judgment call, my brain started taking shortcuts. “I’ll just put it in Misc for now.” “I’ll document this later when I understand it better.” The very shortcuts I was trying to eliminate would creep back in, driven by mental exhaustion rather than laziness.

I’d leave the coffee shop feeling like I’d accomplished something, but knowing deep down I’d barely scratched the surface. The next Sunday, I’d have to rebuild my mental model of the config structure before I could make more changes. Context-switching tax, every single week.

This is why the seven-minute Claude Code refactoring isn’t just about speed - it’s about suitability. An AI doesn’t experience decision fatigue. It doesn’t need to context-load. It holds the entire 1,185-line structure in “mind” simultaneously and applies organizational patterns with perfect consistency. It doesn’t get distracted by an interesting package configuration or spend ten minutes deciding whether “Utilities” or “Tools” is the better section name.

What took me weeks of intermittent effort across months took Claude minutes of focused processing. Not because I’m slow or Claude is fast (though I am, and it is), but because systematic pattern-based refactoring across large files is fundamentally better suited to AI assistance than human weekend sessions.

Those Sunday afternoons weren’t wasted. They taught me what I needed: not more willpower, but a different approach to the problem. Sometimes the lesson isn’t “try harder.” It’s “use different tools”.

This is what good tools - whether they’re text editors or AI assistants - should do: not just help you accomplish a task, but help you learn and grow in the process.

If you’re sitting in a coffee shop right now, weekend after weekend, trying to tame your own configuration chaos: I see you. I was you. Sometimes the answer isn’t another Sunday afternoon. Sometimes it’s asking whether you’re using the right tools for the job.

And speaking of growth: I should probably go add :defer t to a few more packages.

Have you refactored a major configuration recently - or spent months trying? What did you learn in the process? I’d love to hear about it - feel free to reach out.