New machine. Install Claude Code. And then: Claude knows nothing. The development rules encoded in the global CLAUDE.md, the reference guides, the statusline displaying token consumption in real time, the plugins — all of it stayed on the old machine.
The bad news: none of this syncs automatically. The good news: everything lives in files. A single prompt can rebuild the complete environment in minutes — provided you prepared that prompt in advance.
What lives in ~/.claude/
The Claude Code global environment is concentrated in one folder: ~/.claude/. What you'll find there:
-
CLAUDE.md— global instructions: how to work, which rules apply across all projects -
settings.json— technical configuration: permissions, statusline, hooks -
hooks/— scripts executed on Claude Code events -
commands/— custom slash commands (/audit-memory, etc.) -
memory/— global memories -
projects/<cwd>/memory/— per-project memories
This folder is neither versioned nor synced by default. Change machines, and the folder disappears. Everything you built over sessions goes with it.
Reference files you store there — development guides, language-specific best practices — aren't auto-loaded. Claude reads them only when explicitly asked. They don't survive a machine change without manual intervention either.
The global CLAUDE.md: the rules of the game
~/.claude/CLAUDE.md is loaded in every session, across all projects. This is where you encode what must apply everywhere: how Claude should work, which restrictions are active, how commits should be written, how automatic memory works.
It's also the hardest file to reconstruct from memory — because every rule it contains came from a concrete experience. A commit convention encoded after discovering what you didn't want in messages. A restriction on .env files added after an incident. A context economy principle that took weeks to calibrate.
The structure that works well in practice:
- Automatic memory rules (when to save, what to avoid)
- Security restrictions (forbidden files, git limits)
- Commit conventions (what you don't want to see in messages)
- Design principles (YAGNI, the 4 questions before a refactor)
- Model delegation mode (what Opus handles directly, what it delegates)
- Context economy (max file size to read directly, when to delegate)
Target: under 100 lines. Beyond that, the file starts loading irrelevant context for most tasks. Rarely-useful sections (Go best practices, detailed development guide) go into separate files referenced as plain text.
Reference files
Some knowledge is too voluminous for the main CLAUDE.md but too specific for a project CLAUDE.md. The solution: reference files in ~/.claude/, read on demand.
Concrete examples:
-
DEVELOPPEMENT-PROPRE.md— core principles: YAGNI, robustness/testability/simplicity triangle, code review checklist, anti-patterns to avoid -
go-best-practices.md— Go-specific patterns with code examples: error handling, concurrency, PostgreSQL, table-driven testing, structured logging
The global CLAUDE.md only contains a reference line:
Development Guide: `~/.claude/DEVELOPPEMENT-PROPRE.md`
Go Best Practices (patterns, code examples): `~/.claude/go-best-practices.md`
Claude reads these files when relevant to the task. The rest of the time, they take no context space.
The statusline: scraping token usage in real time
Claude Code supports a configurable statusline in ~/.claude/settings.json. A second file, settings.local.json (not versioned), handles tool permissions — what can run without confirmation, what's blocked. Keeping them separate avoids exposing your permissions in a shared repo.
{
"statusLine": {
"type": "command",
"command": "bash /home/YOUR_USER/.claude/hooks/statusline.sh"
}
}
The script displays in the Claude Code bar information that isn't available natively: context consumption as a percentage, remaining token estimate, current git branch.
🌿 main │ 🤖 Sonnet 4.6 │ 🟢 Ctx: ▓▓░░░░░░ 34% │ ⏱ 46% → 19h00 (3h20m) │ 📅 ~59% (Mon 14h)
The script scrapes the /usage endpoint in background via tmux, caching results for 5 minutes in ~/.claude/usage-exact.json. Requirements: bash 4+, jq, tmux, python3. The full script is available on GitHub.
Without this script, the only consumption indicator is the progress bar in the interface — no percentage, no estimate.
Plugins
Claude Code supports a plugin (skills) system that enriches sessions with specialized workflows. They install via:
claude plugins install <plugin-name>
Plugins that genuinely change how you work:
- superpowers — structured brainstorming, implementation plans, systematic debugging, TDD, code review
- frontend-design — interface generation with production quality
- code-simplifier — automatic review of changed code to detect over-engineering
They reinstall with a single command. The only prerequisite is having the list of plugins you were using — hence the value of noting it down before switching machines.
Memories: what rebuilds itself vs. what doesn't
Project memories (~/.claude/projects/<cwd>/memory/) don't always need to be manually migrated. They age quickly — project type memories especially. Reopening a project in a fresh environment is an opportunity to let them rebuild naturally, session by session, with up-to-date information.
What's worth migrating first: global memories (~/.claude/memory/). These are cross-project preferences — the user profile (technical level, knowledge domains), feedback that applies to all projects (expected response style, communication rules). This information takes time to rebuild because it comes from experience accumulated across multiple projects.
For feedback memories especially: each rule encodes a past correction. "Don't summarize what we just did at the end of the message" — Claude needs to be corrected several times before it makes it into a memory. On a new environment without that memory, you start those corrections from scratch.
The bootstrap prompt
The real solution to this problem isn't syncing files — it's having a bootstrap prompt that recreates everything from scratch. A document containing:
- The exact content of
~/.claude/CLAUDE.md - The content of each reference file
- The
settings.jsonconfiguration - The statusline script
- The plugin list
- The global memories to restore
Give this document to Claude on the new environment with the instruction "recreate all of this." Claude creates the files, configures the settings, installs what it can install. In 10 minutes, the environment is functional. The associated CLAUDE.md context below is that document — it contains the exact content of all three ~/.claude/ files, the memories to restore, and the verification checklist.
The advantage over file sync: it's an opportunity to review and update. A bootstrap prompt maintained over time reflects the actual current state of what you want — not a frozen snapshot of the old machine.
The associated CLAUDE.md context at the bottom of this page contains a complete concrete example: the global CLAUDE.md, settings.json configuration, plugin list, and a post-installation verification checklist.
Conclusion
Everything Claude knows about how you want to work lives in files. Those files don't sync, don't back up, and don't survive a machine change without conscious intervention.
The discipline required: treat ~/.claude/ like dotfiles — something you version, maintain, and know how to restore completely from scratch. The associated CLAUDE.md context below contains the complete bootstrap prompt.
📄 Associated CLAUDE.md