Skip to content

Dotfiles — A Jumpstart for Claude Code + Codex + Antigravity

Docs site

📖 Browsable docs: everything in this repo is also published as a searchable site at jckeen.github.io/dotfiles — rebuilt on every push to main.

A one-command setup that gets you from a blank machine to a coordinated Claude Code, Codex, and Gemini-powered Antigravity environment with sane defaults, safety hooks, multi-session tooling, and a 24-agent pack of code reviewers and subject-matter experts. Built for macOS and Windows (via WSL2 + Ubuntu), with Linux supported as a side effect.

This is opinionated — it's how I (and now hopefully you) switch between Claude Code, Codex, and Antigravity day-to-day. Clone it, run ./setup.sh, and skip months of trial-and-error.

Get started: 

git clone https://github.com/jckeen/dotfiles.git && cd dotfiles && ./setup.sh

Best practices sourced from Boris Cherny (creator of Claude Code), the official Claude Code docs, and hard-won experience across thousands of agent sessions.

What you get (and why it matters)

After setup, you don't have to remember much. Open a terminal and:

  • cc / cx / agy — the three launchers share project selection, fast-forward-only repo sync, and runtime health checks. cc safely publishes approved Claude memory paths; cx reapplies portable Codex defaults and reconnects opted-in Remote Control; agy launches the Gemini-powered Antigravity CLI. Ordinary checkouts fast-forward; linked worktrees are fetched, never pulled. Repository and Claude memory sync failures warn and continue with local state. Required runtime health checks still stop the launch on failure.
  • A live status line — model name, context-bar (green/yellow/red), git branch, lines added/removed, session cost in USD. You always know how warm your context is, what branch you're on, and what the session has cost — without asking.
  • 18 slash commands that cover the whole loop — /kickoff (new project), /review (quality + security), /simplify (de-engineer), /fix-issue (GitHub issue end-to-end), /handoff (clean session transition), /changelog, /log-error, /commit-push-pr, /claude-server, /decompose, /orchestrate (full-lifecycle max-effort mode), /autonomous-run (pick the loop primitive, stop condition and cap for unattended work), /branch-hygiene, /jj (jujutsu driver), /session-retro (improve your own skills), /drift-sweep (doc-contract bootstrap + drift audit), /antigravity-review (Gemini second-opinion review gate), /review-gates (which review lane a change needs, handoff payload, verdict persistence). Type the verb, get the workflow.
  • A 24-agent pack — reviewers (qa-lead, security-reviewer, frontend-architect, backend-architect, ux-reviewer, growth-strategist, trust-safety, perf-accessibility, and more), utility agents, and six sme-* subject-matter experts you delegate questions about Claude Code tooling newer than the model's training. Each runs in its own isolated context and reports back without polluting your main session. Three-phase orchestration (Product → Architecture → Launch) for serious reviews.
  • Safety hooks that can't be forgotten — auto-format on edit (prettier, black, rustfmt, gofmt), conventional-commit enforcement, push notifications when Claude is waiting on you, and a StripProjectPermissions hook that prevents per-project permission creep from overriding your global allowlist.
  • Multi-session tooling — open 3, 5, or 8 Claude sessions across different projects in a single Windows Terminal window via cc-pane/cc-tab/cc-multi (bash) or ccgrid/cctab/ccpane (PowerShell). Each session gets the full cc treatment — repo sync, tab colors, health check.
  • Agent-neutral helpers — wsl6 opens a 3×2 grid of plain WSL shells (no Claude/Codex coupling) for ad-hoc multi-shell work.
  • Auto-hygiene — a daily systemd timer cleans stale branches across every repo in ~/dev/, surfaces drift at every Claude/Codex session start, and bootstraps the canonical 8 GitHub auto-merge settings on every newly-created or cloned repo.
  • Public-safe Codex parity — portable workflows live once under agents/skills/ and are exposed to Codex, Claude where applicable, and Antigravity. Codex selects them with /skills or $skill-name (for example $orchestrate); Claude keeps its /skill-name syntax. agents/skill-coverage.tsv and CI require every workflow to be explicitly shared or runtime-specific, so a new Claude skill cannot silently disappear from the other-agent layer. Codex auth, sessions, sqlite state, and live config.toml stay local.
  • Cross-platform symlink hygiene — setup.sh is idempotent and runs the same on macOS and WSL. Edit ~/.claude/agents/foo.md and the change is in your repo automatically (it's a symlink). dotfiles-update keeps everything in sync with one command.

Why this exists: Claude Code and Codex are powerful but the defaults aren't tuned for serious daily work — context bloats, sessions vanish without handoffs, branches pile up, agent reviews are ad-hoc, and you re-discover the same gotchas every project. This repo encodes the "second-day knowledge" that makes the tools actually compound. If you're going to spend hundreds of hours in these CLIs, spend the first 10 minutes setting up properly.

Quick Start

Pick your platform. Each path leaves you with the same end state: the agent services you choose (Claude Code, Codex, and/or Antigravity — all three by default) installed, shared workflows wired, runtime-specific hooks and integrations checked, and multi-session helpers ready. See Choosing agent services.

🪟 Windows (WSL2 — recommended)
Claude Code runs *much* better in WSL2 than directly on Windows: native Linux filesystem (~10x faster I/O than `/mnt/c/`), full POSIX tooling, and our PowerShell helpers (`wsl6`, `ccgrid`, etc.) bridge nicely between Windows Terminal and WSL. **Prerequisites** — install these once, in PowerShell as Administrator (skip any you already have): 
# 1. WSL2 + Ubuntu (reboot if it's a fresh WSL install)
wsl --install -d Ubuntu

# 2. PowerShell 7 (preferred — Windows ships with PS 5.1, but PS 7 is faster
#    and is what you should be using day-to-day)
winget install --id Microsoft.PowerShell --source winget

# 3. Windows Terminal (preinstalled on Windows 11; install on 10)
winget install --id Microsoft.WindowsTerminal --source winget
> **Why PowerShell 7?** PS 5.1 is end-of-life maintenance only and uses `Documents\WindowsPowerShell\` for its profile. PS 7 is the modern, cross-platform Core build, uses `Documents\PowerShell\`, and is faster on every workload. `setup.sh` wires our helpers into **both** profiles so you're covered either way, but you should default to PS 7. **Inside WSL** (open Ubuntu from the Start menu, or `wsl` from any terminal): 
# Clone this repo into the Linux filesystem (NOT /mnt/c/ — that's ~10x slower)
mkdir -p ~/dev && cd ~/dev
git clone https://github.com/jckeen/dotfiles.git
cd dotfiles

# Run setup — auto-detects WSL, installs everything, prompts where it matters
./setup.sh

# Authenticate (do these once)
gh auth login          # GitHub CLI — choose HTTPS + browser
claude                 # Sign in to Claude (or 'claude auth login' if it doesn't prompt)
ccw                    # Optional: sign in a second (work) Claude account — see CLAUDE-GUIDE
codex login            # Optional: sign in for Codex CLI
jules login            # Optional: sign in for the Jules CLI (cloud routine lane)
You're done. Open a new PowerShell 7 window and try `wsl6`, or run `cc` inside WSL.
🍎 macOS
**Prerequisites** — install these once if you don't have them: 
# 1. Xcode Command Line Tools (gives you git, clang, etc.)
xcode-select --install

# 2. Homebrew (everything else installs through this)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
**Then:** 
mkdir -p ~/dev && cd ~/dev
git clone https://github.com/jckeen/dotfiles.git
cd dotfiles

# Run setup — auto-detects macOS, installs Node/bun/gh/jq via brew if missing
./setup.sh

# Authenticate
gh auth login
claude
codex login            # Optional
jules login            # Optional
> **Why macOS?** Native Unix toolchain, no VM overhead, excellent terminal options (Terminal.app, iTerm2, Ghostty, Warp — pick your favorite). The setup script handles macOS-specific things (osxkeychain credential helper, brew package install, zsh `.bash_aliases` sourcing) automatically.
🐧 Linux (native, not WSL) 
mkdir -p ~/dev && cd ~/dev
git clone https://github.com/jckeen/dotfiles.git
cd dotfiles
./setup.sh
gh auth login
claude
codex login            # Optional
jules login            # Optional
> **Node.js first:** unlike macOS, `setup.sh` does not auto-install Node on > Linux — if `node` is missing it prints install options and exits. Install it > before running setup, e.g. > `curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - && sudo apt install -y nodejs`.

Setup-script flags (all platforms)

./setup.sh             # default: install the selected services (asks on first run), prompting only where it matters
./setup.sh --check     # read-only audit of all symlinks; exits non-zero if broken
./setup.sh --repair    # audit + recreate any broken/missing symlinks
./setup.sh --dry-run   # show what would change without writing anything
./setup.sh --services claude,codex   # manage only these agent services (saved for reruns)
./setup.sh --select-services         # re-ask which services to manage (e.g. to add one later)
./setup.sh --show-services           # print the effective selection and where it came from

Choosing agent services

setup.sh manages up to three agent services: Claude Code (claude), Codex (codex), and Antigravity (antigravity, alias agy). Each is an independent choice.

  • First interactive run: setup asks about each service (default yes), then asks you to confirm the selection.
  • Noninteractive: pass --services claude,codex (or all), or set DOTFILES_SERVICES=claude,codex. The flag wins when both are set. --yes with neither keeps the saved selection, or all three when none is saved.
  • Where it is saved: $XDG_CONFIG_HOME/dotfiles/services (default ~/.config/dotfiles/services), a machine-local file outside the repo holding one line like services=claude,codex. A real run writes it; --dry-run only says it would.
  • Reruns (including dotfiles-update) reuse the saved selection without asking. To add a service later, rerun with --select-services or a longer --services list.
  • Existing installs (migration): with no saved selection, setup manages all three services, which is what it did before selection existed. The first real run records that as the saved selection, so nothing changes unless you opt out.

A service you don't select is skipped everywhere setup acts: its installer, sign-in prompt, links, hooks, integrations (for Codex, also the codex Claude plugin), the post-setup audit and --check/--repair, and the completion hints. Deselecting never deletes anything: existing config, sessions, and credentials for that service stay where they are, and setup just stops managing them. The ~/.claude/scripts tooling and ~/.claude/dev-dir are shared by every launcher and review gate, so they are linked whichever services you pick. The cc/cx/agy launchers are unchanged: running one still checks and heals its own runtime's links.

setup.sh refuses to run from a linked git worktree (agents create these for review branches): every managed link resolves against the checkout that runs it, so links would dangle once the worktree is removed. Run it from the main checkout, or set DOTFILES_ALLOW_LINKED_WORKTREE=1 to link a worktree on purpose. --check stays read-only and works anywhere.

./setup.sh --help      # usage and flag reference

The launchers run their health checker with --heal --strict. Healing creates missing managed links and removes only exact obsolete fable-mode skill links and the retired Claude FABLE.md link when their original source is gone. It preserves custom files, unexpected targets, restored bundles, and symlinked ancestors. Running a checker without a repair flag is read-only.

Public repo safety: this dotfiles repo is public. Don't commit Codex/Claude auth tokens, generated sessions or memories, sqlite state, logs, caches, private memory, account IDs, private MCP endpoints, personal identity notes, or client/project details. Private state lives in claude-memory and codex-memory (separate private repos — see below). CI runs secret and personal-data checks on every PR; the canonical required-check policy lives in docs/BRANCH_PROTECTION.md.

Private memory (optional): if you keep a private claude-memory repo under ~/dev/, setup.sh calls its bootstrap.sh to symlink your Claude Code settings.json (MCP servers, permissions, plugins) into ~/.claude/. Claude Code only runs hooks and the status line that settings.json registers, so without the repo setup.sh copies claude/settings.example.json (the hooks and the status line, nothing private) to ~/.claude/settings.json. It never overwrites an existing file. Skills, agents, and the global claude/CLAUDE.md are symlinked either way.

WSL filesystem rule: Always clone repos under ~/dev (Linux filesystem), not /mnt/c/ (Windows mount). File I/O on the native Linux filesystem is ~10x faster. The setup script auto-configures your shell to cd ~/dev on startup.

Try it now

After setup, run these to see what you've got:

cc                    # pulls all your repos, then launches Claude
cx                    # pulls repos, reconnects enabled Remote Control, launches Codex
agy                   # pulls repos, checks Antigravity config, launches Gemini/Antigravity
dotfiles-update       # pull latest dotfiles + re-run setup (idempotent — safe anytime)
projects              # list everything under ~/dev/
sessions              # show active Claude sessions and their cwds

Once inside Claude: - Type /review to run a code quality check on your last few commits - Type /simplify after writing code to remove unnecessary complexity - Ask "Run the qa-lead agent on this project" to spawn an isolated review - Watch the status line — it shows context %, git branch, cost, and lines changed

Windows (PowerShell 7) users — open a fresh PowerShell 7 window and try:

Command What it does
wsl6 Opens a Windows Terminal tab with a 3×2 grid of plain WSL shells (agent-neutral)
ccprojects Lists projects available under your WSL ~/dev/
ccgrid dotfiles atlas stringer One new tab, three split panes, each running cc <project> inside WSL
cctab dotfiles atlas One tab per project, each running cc <project> inside WSL
ccpane dotfiles Splits the current Windows Terminal window with cc dotfiles

These are auto-installed by setup.sh on WSL (it asks "Install into your PowerShell profile(s)? [Y/n]" — answer Y). The installer wires both PS 5.1 and PS 7 profiles, so the helpers work in whichever you prefer. If you missed the prompt or installed before this fix, just run dotfiles-update from WSL. Manual install, distro/dev-dir overrides, and more: docs/WINDOWS.md.

What this installs and configures

setup.sh installs CLI tools, wires the public and private layers for each selected runtime (all three unless you choose fewer), and configures platform-specific bits (audio on WSL, credential helpers per OS, etc.). Expand below for the full inventory.

📦 Tools installed (gh, git, node, jq, tmux, claude, codex, agy, jules, bun)
| Tool | Purpose | Install method | |------|---------|---------------| | `gh` | GitHub CLI | Homebrew (macOS) / apt (Linux) | | `git` | Version control | Homebrew / apt | | `node` | Node.js LTS | Homebrew / NodeSource | | `jq` | JSON processing (used by hooks) | Homebrew / apt | | `tmux` | Detachable sessions for the opt-in `cct` launcher | Homebrew / apt | | `claude` | Claude Code CLI | SHA-256-pinned official native installer | | `codex` | OpenAI Codex CLI | npm | | `jules` | Google Jules CLI — the cloud routine lane (ADR-0009, paused 2026-10-19); `jules login` for interactive use, an API key file for the daily dispatcher | npm | | `agy` | Google Antigravity CLI (Gemini agent runtime) | SHA-256-pinned official installer; release payload checksum-verified by the vendor installer | | `bun` | Runtime for `*.hook.ts` hooks | Pinned GitHub release (`BUN_VERSION` in `setup.sh`), SHA-256-verified against the release's `SHASUMS256.txt` | WSL also gets: `pulseaudio-utils`, `libasound2-plugins`, `alsa-utils` (for audio routing).
⚙️ Files & symlinks configured (CLAUDE.md, hooks, skills, agents, aliases…)
Public Claude config pieces are **symlinked** from this repo to `~/.claude/`, so edits in either location stay in sync. The global instructions live in this repo and are symlinked into `~/.claude/`; private settings (MCP servers, permissions, plugins) come from `claude-memory`. Codex is stricter: only public-safe guidance and skills are symlinked into `~/.codex/`; live `~/.codex/config.toml` stays local because Codex stores machine-specific project trust there. An optional private `codex-memory` bootstrap can merge explicitly portable defaults without replacing that local state. | What | Files | Purpose | |------|-------|----------| | **Claude instructions** | `claude/CLAUDE.md` | Global rules Claude follows in every session (symlinked into `~/.claude/CLAUDE.md`; generated from `agents/canon/` per ADR-0007 — edit the sources, not the file) | | **Settings** | `~/dev/claude-memory/settings.json` | Private permissions, MCP servers, plugins (symlinked into `~/.claude/` by claude-memory's `bootstrap.sh`) | | **Settings template** | `claude/settings.example.json` | Public `hooks` + `statusLine` registrations; `setup.sh` copies it to `~/.claude/settings.json` when neither that file nor `claude-memory` exists (never symlinked, never overwrites). The hooks it omits are listed in `claude/settings-optout.txt`; a full private setup adds `"CHECK_HOOKS_REQUIRE_ALL": "1"` to its settings `env` to require every hook | | **Agent Pack** | `claude/AgentPack.md` | 24-agent pack: review orchestra plus subject-matter experts (loaded on-demand, not symlinked) | | **Status line** | `claude/statusline.sh` | Shows model, context %, git branch, lines changed, session cost | | **Commit hook** | `claude/hooks/conventional-commit.sh` | Enforces `type: description` commit message format | | **Format hook** | `claude/hooks/format-on-edit.sh` | Auto-formats files after edits (prettier, black, rustfmt, gofmt) | | **Notification hook** | `claude/hooks/ntfy-awaiting-input.sh` | Sends push notification when Claude needs input | | **Permission guard** | `claude/hooks/StripProjectPermissions.hook.ts` | Strips project-level permission overrides on SessionStart | | **Other hooks** | `claude/hooks/*` | Worktree guard, symlink repair, plugin/hygiene drift, stale-SHA warning, handoff reminder, pre-merge Codex harvest — full wired-state table in [CLAUDE-GUIDE → Hooks](guide.md#hooks) | | **Plugin manifest** | `claude/plugins.txt` | Read by `setup.sh` (§3b) and `sync-plugins.sh` to auto-install plugins (`plugin@marketplace`, one per line) at **user scope**; a `--scope project` or `--scope local` install belongs to that checkout and never satisfies a manifest entry; deliberately not symlinked (listed in `claude/nolink.txt`) | | **Skills** | `claude/skills/*/` | Claude slash commands (see below); each skill directory is one symlink at `~/.claude/skills/`, so supporting files (`references/`, `scripts/`, `assets/`, `.claude-plugin/`) deploy with it | | **Subagents** | `claude/agents/*.md` | 24 specialized agents (reviewers, utilities, subject-matter experts) | | **Shell aliases** | `.bash_aliases` | `cc`, `pull-all`, worktree shortcuts; launchers re-source this file when it changed since the shell started | | **Codex guidance** | `codex/AGENTS.md` | Public-safe global Codex working rules (generated from `agents/canon/` per ADR-0007) | | **Cloud-agent brief** | `AGENTS.md` (repo root) | The short working contract an agent reads from the checkout itself when it has no session history — Jules, a Codex cloud task (generated from `agents/canon/` per ADR-0007) | | **Routine catalog** | `agents/routines/*.md` | Standing prompts for the cloud routine lane, one file per routine, with a frontmatter contract the dispatcher enforces (ADR-0009) | | **Shared agent skills** | `agents/skills/*/SKILL.md` | Agent-neutral workflows, directory-linked into Codex's documented `~/.agents/skills/` user scope (with legacy `~/.codex/skills/` links retained for older clients) | | **Codex config examples** | `codex/*.toml.example` | Templates only; live `~/.codex/config.toml` stays local | | **Antigravity guidance** | `antigravity/GEMINI.md` | Public-safe global Antigravity (agy) rules (symlinked into `~/.gemini/config/GEMINI.md`; generated from `agents/canon/` per ADR-0007) | | **Antigravity permissions** | `antigravity/permissions.json` | Curated allow/ask/deny rules plus `toolPermission: proceed-in-sandbox` and `enableTerminalSandbox: true`. `setup.sh` merges it into the machine-local `~/.gemini/antigravity-cli/settings.json` via `claude/scripts/agy-apply-permissions.py` (never symlinked: that file also holds `trustedWorkspaces` and prompt-saved grants). `check-antigravity.sh` warns on drift; `agy-apply-permissions.py prune` resets accreted grants to the baseline after a backup. A `retired` array lists grants the baseline has withdrawn: because the merge is additive, `apply` deletes each one from the live `allow` list and `check` fails while any remain, so revoking a grant reaches machines that already installed it. `ask` and `deny` are never touched, so an operator-added restriction is never retired away | | **Antigravity skills** | `agents/skills/*/` (shared) | The same agent-neutral workflow set, dir-symlinked into `~/.gemini/config/skills/` | | **Git config** | `.gitconfig` + `.gitconfig.local` | Identity, editor, credential helper (per-platform) | | **Audio** | `.asoundrc` (WSL only) | ALSA → PulseAudio routing |
🖥️ Platform-specific behavior (what differs across macOS / WSL / Linux)
| Feature | macOS | WSL | Linux | |---------|-------|-----|-------| | Package manager | Homebrew | apt | apt | | Shell config | `.zshrc` | `.bashrc` | `.bashrc` | | Credential helper | osxkeychain | Git Credential Manager (Windows) | git-credential-store | | Audio | Built-in | ALSA → PulseAudio | N/A | | Git safe.directory | Not needed | Auto-configured for `/mnt/c/` | Not needed |

Daily use

The day-to-day reference is CLAUDE-GUIDE.md — the cheat sheet for slash commands, hooks (with their wired-state), keyboard shortcuts, shell commands, worktree/multi-session helpers, autonomous scripts, stop-hook templates, and the golden rules. What follows is the short version.

The commands you'll actually type

Command What it does
cc [project] Sync repos + memory, health check, heal plugin drift, launch Claude
cx [project] Same ergonomics for Codex; reuses a listening shared server when Remote Control is enabled and otherwise launches locally; optional user service handles automatic startup
cc-multi <p1> <p2> … Multiple projects, one Windows Terminal tab each, fully synced
cct [project] cc inside a named tmux session, so the process and its Remote Control link survive a closed terminal
rc-start [--hold] Starts claude remote-control in a detached tmux session rc (with bun on its PATH), from ~/dev (RC_START_DIR overrides). The session ends when Remote Control exits (logged to ~/.local/state/rc-start.log), so running it again restarts it. --hold blocks, so the wsl.exe of a Windows boot task keeps WSL running
dotfiles-update Pull latest dotfiles + re-run setup (idempotent — safe anytime)
/handoff Capture session state before /clear or stopping
/orchestrate Full-lifecycle max-effort mode — worktrees, parallel agents
/autonomous-run Unattended or looping work — picks /loop, /goal, a workflow or /schedule, sets the stop condition and cap
/fix-issue N GitHub issue end-to-end: investigate → test → fix → PR

Most other slash commands auto-invoke when their triggers match — you rarely type them. Full table: CLAUDE-GUIDE.

The loop

Plan → Build → Verify → Simplify → Review → Log → Handoff

Each step is a mode or slash command — see CLAUDE-GUIDE → The Workflow, including the push-time Codex review gate that blocks on critical findings.

Going wider

  • Worktrees & multi-session — za–ze/z0 jump between worktrees, wt-claude <name> spawns Claude in a fresh one, cc-pane/cc-tab/cc-multi fan out across Windows Terminal (from inside Claude: ! cc-pane <project>). Tables in CLAUDE-GUIDE; the PowerShell side (wsl6, ccgrid, cctab, ccpane, manual install, distro overrides) lives in docs/WINDOWS.md.
  • The 24-agent pack — spawn by name ("Use the qa-lead agent on this feature"), in groups, or as a three-phase full review (Product → Architecture → Launch). /review and /simplify use them automatically. Roster and orchestration: claude/AgentPack.md.
  • Safety hooks — run automatically, can't be forgotten like CLAUDE.md rules: conventional-commit enforcement, project-gated format-on-edit, session-start symlink repair, permission-creep stripping, plugin drift detection. The canonical wired-state table is in CLAUDE-GUIDE → Hooks; files in claude/hooks/.
  • Status line — model, context bar (green/yellow/red), branch, lines changed, session cost. If the bar runs red: /handoff, then /clear.

The private memory repos

This public dotfiles repo pairs with up to three separate private repos — claude-memory, plus optional codex-memory and agy-memory — that hold things that don't belong in public: Claude Code settings, auto-memory, archived personal context, and Codex/Antigravity preferences. All are optional; without them you still get skills, agents, git config, and cc/cx scaffolding. The hooks and status line come with a settings.json that registers them: without claude-memory, setup.sh copies the public claude/settings.example.json into ~/.claude/settings.json when no file is there yet.

📁 The claude-memory private repo — structure, contract, how to create your own
`claude-memory` holds: 1. Your **Claude Code settings** (`settings.json`) — private permissions, MCP servers, and enabled plugins. 2. Your **persistent Claude memory** (`dev/memory/`) — auto-memory files (`MEMORY.md` + `feedback_*.md`) Claude Code writes to `~/.claude/projects/`. Without this repo they only exist locally and vanish on machine rebuild. `sync-memory` publishes only `*/memory/**` paths and refuses any file whose *name* looks credential-like (`auth`, `oauth`, `session`, `cache`, `log`, `credential`, `token`, `secret`, `.env`, `.key`, `.pem`); name memory files after the topic, not the mechanism, or the sync aborts and names the file. 3. **Archived personal context** (`identity/`) — identity and steering notes kept for reference. These are no longer live-linked into Claude; they're retained as an archive. 4. **Project notes** (`stringer/`, `trnn/`) — durable per-project context. 5. Your **personal identity & preferences** (`CLAUDE.md`) — imported by the public `claude/CLAUDE.md` via `@~/dev/claude-memory/CLAUDE.md`, so identity loads globally while staying out of the public repo. 6. The `bootstrap.sh` script that symlinks `settings.json` into `~/.claude/`. **Minimum structure:** 
~/dev/claude-memory/
├── bootstrap.sh                   # idempotent; runs at end of setup.sh — links settings.json
├── settings.json                  # symlinked into ~/.claude/settings.json
├── CLAUDE.md                      # personal identity, imported by public claude/CLAUDE.md
├── dev/
│   └── memory/                    # Claude auto-memory (MEMORY.md + feedback_*.md)
├── identity/                      # ARCHIVED personal identity/steering notes (not live-linked)
├── stringer/                      # project notes
└── trnn/                          # project notes
`bootstrap.sh` symlinks `settings.json` into `~/.claude/` (no voice server, no `.env` checks). `setup.sh` calls it automatically when the repo is present. **Creating your own** — deliberately hand-crafted, no generator: 
# Create the skeleton
mkdir -p ~/dev/claude-memory/dev/memory
cd ~/dev/claude-memory

# Your Claude Code settings: start from the public template, which
# registers the hooks and the status line, then add your own
# permissions, MCP servers and plugins.
cp ~/dev/dotfiles/claude/settings.example.json settings.json

# A minimal bootstrap.sh that symlinks settings.json into ~/.claude/
# (idempotent; re-run safe). It backs up a real file that is already there,
# such as the copy setup.sh made before this repo existed. setup.sh's health
# audit calls it with --check (even under --dry-run), so that mode only
# reports: exit 0 when the link is in place, 1 otherwise, writing nothing.
cat > bootstrap.sh <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
src="$(cd "$(dirname "$0")" && pwd)/settings.json"
dst="$HOME/.claude/settings.json"
if [ "${1:-}" = "--check" ]; then
  [ -L "$dst" ] && [ "$(readlink "$dst")" = "$src" ] && exit 0
  echo "settings.json is not linked to $src" >&2
  exit 1
fi
mkdir -p "$HOME/.claude"
if [ -e "$dst" ] && [ ! -L "$dst" ]; then
  mv "$dst" "$dst.backup.$(date +%s)"
fi
ln -sfn "$src" "$dst"
echo "linked $dst -> $src"
EOF
chmod +x bootstrap.sh

# Publish it private
git init && git add -A && git commit -m "init: claude memory"
gh repo create claude-memory --private --source=. --push
`check-claude.sh` verifies the memory symlink is healthy alongside everything else.
📁 The codex-memory private repo — structure, what never to commit
This public dotfiles repo only tracks reusable Codex guidance, skills, and examples. Anything personal or generated belongs in an optional private repo at `~/dev/codex-memory` for portable Codex memory and private instructions. Keep this separate from `claude-memory`; the tools have different runtime state and different config formats. **Minimum structure:** 
~/dev/codex-memory/
├── AGENTS.local.md              # private Codex preferences
├── MEMORY.md                    # durable private notes
├── config.defaults.toml         # portable top-level config choices
├── bootstrap.sh                 # safe merge into the local live config
├── merge_config.py              # validated atomic TOML merger
├── README.md
└── .gitignore
**Never commit these from `~/.codex/`:** - `auth.json` - `history.jsonl` - `logs_*.sqlite*` or `state_*.sqlite*` - `log/`, `sessions/`, `shell_snapshots/`, `memories/`, `cache/`, `.tmp/`, `tmp/` - live `config.toml` project trust entries - private MCP endpoints, token env values, account IDs, client names, or private project details `setup.sh` links public `codex/AGENTS.md` and complete shared skill bundles from `agents/skills/*/` into `~/.agents/skills/`, including references and UI metadata. Compatibility links remain under `~/.codex/skills/` for older Codex clients. It also links `AGENTS.local.md` and `MEMORY.md` into `~/.codex/` when the private repo exists. When that repo provides `bootstrap.sh`, setup runs it and `cx` reapplies it after repository sync. The bootstrap merges only the explicit keys in `config.defaults.toml`; it never copies or symlinks the whole live config, so machine-specific project trust and integrations remain local. `check-codex.sh` audits those nested links and warns when private/generated Codex files exist so you remember they are local-only.
📁 The agy-memory private repo — structure, what never to commit
Same pattern for Antigravity (`agy`): the public repo tracks only `antigravity/GEMINI.md` (global rules); anything personal belongs in an optional private repo at `~/dev/agy-memory`. **Minimum structure:** 
~/dev/agy-memory/
├── GEMINI.local.md              # private Antigravity preferences
├── MEMORY.md                    # durable private notes
├── README.md
└── .gitignore
**Never commit these from `~/.gemini/antigravity-cli/`:** - `antigravity-oauth-token` - `conversations/`, `conversation_summaries.db*`, `history.jsonl` - `brain/`, `knowledge/`, `implicit/`, `scratch/`, `log/`, `cache/`, `crashes/` `setup.sh` links public `antigravity/GEMINI.md` into `~/.gemini/config/GEMINI.md`, dir-symlinks the shared workflow skills (`agents/skills/*`, the agent-neutral set) plus the Antigravity-only skills (`antigravity/skills/*`, e.g. `browser-verify`) into `~/.gemini/config/skills/`, links `antigravity/hooks.json` (session-start handoff injection), seeds a local `mcp_config.json` from `antigravity/mcp_config.json.example` (Playwright + GitHub MCP; the GitHub token resolves at launch via `gh auth token`, never stored), and links `GEMINI.local.md` and `MEMORY.md` from the private repo when it exists. `check-antigravity.sh` verifies all of it and warns about local-only runtime state.

Customizing (forking this repo)

What to edit, keep private, and leave alone
This repo is designed to be forked and adapted. Here's what to edit vs. leave alone: **Edit these only with public-safe content:** - `claude/AgentPack.md` — add, remove, or modify review agents - `agents/canon/` — the instruction sources (ADR-0007): shared cross-agent rules in `CANON.md`, per-tool voice in `fragments/`. Every instruction file named in that script's target map — including the root `AGENTS.md` — is generated from here by `claude/scripts/gen-instruction-files.sh`; never edit them directly - `agents/routines/*.md` — the cloud routine lane's standing prompts (ADR-0009); `claude/scripts/jules-dispatch.sh --dry-run` shows what a day would dispatch - `agents/skills/*/SKILL.md` — reusable agent-neutral workflows (Codex + Antigravity) - `codex/config.toml.example` — example Codex config only - `.bash_aliases` — your shell shortcuts **Keep private:** - `~/dev/claude-memory` — personal Claude memory, settings, and archived context - `~/dev/claude-memory/settings.json` — private Claude permissions, MCP servers, and plugins - `~/dev/codex-memory` — personal Codex memory and private instructions - live `~/.codex/config.toml` — machine-specific project trust and local settings **Leave these (the framework):** - `claude/hooks/*.sh` and `*.ts` — hooks (add new ones, but keep the defaults) - `claude/skills/*/SKILL.md` — slash commands (add new ones as needed) - `claude/agents/*.md` — subagent definitions - `setup.sh` — cross-platform installer - `claude/statusline.sh` — status line display

Architecture decisions

The why behind structural changes lives in docs/adr/ as Architecture Decision Records, and the current backlog lives in ROADMAP.md + GitHub Issues. This repo uses a four-layer record model — Issues track what's next, CI-gated PRs are the unit of change, ADRs capture the reasoning, and the CHANGELOG records what shipped. ADRs are numbered NNNN-kebab-title.md and append-only: a decision that no longer holds is superseded by a new record rather than edited away. Start with ADR-0001, or copy 0000-template.md to write a new one.

Repo Structure

Deliberately coarse — visible top-level entries only, with one-line purposes, so a rename inside a directory can't silently rot this diagram. Hidden root files are omitted as policy, not oversight: .github/ holds the CI gates, .doc-contract declares the doc tiers (ADR 0005), and the rest are shell, git, and audio config wired by setup.sh. Run ls -A (or browse the docs site) for the real inventory.

dotfiles/
├── setup.sh                # Cross-platform bootstrap — installs tools, wires every symlink
├── check-claude.sh         # Health checks (also check-codex.sh, check-antigravity.sh)
├── git-hygiene.sh          # Repo/branch hygiene (also gh-bootstrap.sh, hygiene-status.sh, lib-symlinks.sh)
├── rc-start                # Remote Control in a detached tmux session (linked into ~/.local/bin)
├── README.md               # This file (also CLAUDE-GUIDE.md, CHANGELOG.md, ROADMAP.md, LICENSE)
├── mkdocs.yml              # Docs-site config for the published Pages site
├── docs/                   # ADRs, Windows deep-dive, branch-protection notes
├── claude/                 # Claude Code layer — CLAUDE.md, hooks, skills, agents, scripts, statusline
├── codex/                  # Public-safe Codex layer — AGENTS.md, config example, Codex-only skills
├── antigravity/            # Public-safe Antigravity (agy) layer — GEMINI.md, hooks, agy-only skills
├── agents/                 # Agent-neutral shared skills + the cloud routine catalog
└── windows/                # PowerShell helpers — wsl6, ccgrid/cctab/ccpane

Sources

Want to understand the reasoning behind these choices? Read the CHANGELOG.