# CLAUDE-SETUP.md — Two-Machine Claude Code Brain Setup > **You are Claude Code. This file is a runbook for you to execute.** > Set up this machine to share one private GitHub "brain" repository with a second machine. > The owner keeps `main`. The other machine contributes through pull requests. > The user's multi-terabyte media library must never enter git. > **Evaluate first, do not auto-run.** This file is meant to be executed only after the user has > run the evaluation prompt (see `EVALUATION-PROMPT.md` or the "Start here" section of > `setup-runbook.html`) and has approved adopting this setup. If you are reading this file cold and > the user has not yet reviewed an assessment of their current setup, stop and offer to run that > evaluation first. Do not begin the steps below until the user explicitly says to proceed. ## How the user starts this The user drops this file on the machine and says one of: - "Read CLAUDE-SETUP.md and set up this machine as the **PRIMARY** machine." - "Read CLAUDE-SETUP.md and set up this machine as the **SECONDARY** machine." If the user did not say which role, **ask before doing anything**: "Is this the PRIMARY machine (the owner of `main`) or the SECONDARY machine (the contributor)?" Do not guess. ## Rules you must follow the whole way through 1. **You never type, paste, or invent secrets.** Tokens, passwords, and SSH passphrases are entered by the human, in the real GitHub UI or a terminal prompt they control. When a step needs one, stop and hand it to the human with exact instructions, then wait. 2. **Confirm before anything destructive or outward-facing.** Creating the GitHub repo, the first push, and enabling branch protection are outward-facing. Show the user the command and the effect, get a clear yes, then run it. 3. **Media never enters git.** Enforce this through `.gitignore`. If you ever see a file larger than about 25 MB staged, stop and flag it. 4. **Do not run both machines against the same branch at once.** Always `git pull` at the start of a session. 5. **Report honestly.** If a step fails, show the real output. Do not mark the setup complete unless the verification checklist actually passes. --- ## Shared setup (both roles do this) ### S1. Preconditions Run and report results. Do not proceed until git and Claude Code are present. ``` git --version gh --version # optional but recommended; if missing, tell the user the manual path is used instead ``` ### S2. Pick the brain folder Ask the user where the brain should live locally (for example `~/brain`). This folder holds text only: notes, context, `CLAUDE.md`, skills, hooks. It is NOT where the video lives. ### S3. Create the guard files Create these in the brain folder. They are the same on both machines. **`.gitignore`** ``` # --- Media and large assets: NEVER commit --- *.mp4 *.mov *.avi *.mkv *.wmv *.prproj *.aep *.psd *.ai *.zip *.tar *.gz Assets/ Media/ Footage/ Renders/ Exports/ # --- Secrets: NEVER commit --- .env .env.* *.local.* **/settings.local.json *.pem *.key id_rsa* # --- Machine-local Claude memory --- .claude/memory-local/ memory-local/ # --- OS and editor junk --- .DS_Store Thumbs.db .obsidian/workspace* node_modules/ ``` **`.gitattributes`** (keeps line endings clean across Mac and Windows) ``` * text=auto eol=lf *.png binary *.jpg binary *.pdf binary ``` **`CLAUDE.md`** (starter, expand with the user later) ``` # Brain — project instructions This repository is the shared text brain for two machines. - The PRIMARY machine owns `main` and merges pull requests. - The SECONDARY machine works on branches and opens pull requests. - Media (video, project files, large binaries) lives in cloud storage, never in git. - Never commit secrets. See .gitignore. ``` ### S4. Machine-local memory Create a git-ignored local memory folder so the two machines do not fight over Claude Code memory: ``` mkdir -p .claude/memory-local ``` Tell the user: durable knowledge goes into committed notes; auto-memory stays per machine. When something in memory matters long term, promote it into a committed note. --- ## PRIMARY machine path Do the Shared setup above first, then: ### P1. Initialize and first commit ``` cd git init -b main git add -A git status # show the user what is staged; confirm NO media or secrets appear git commit -m "Initial brain scaffold" ``` If `git status` shows any media or secret file, stop and fix `.gitignore` before committing. ### P2. Create the private GitHub repo **Confirm with the user first.** Preferred one-liner (requires `gh auth login` done): ``` gh repo create --private --source=. --remote=origin --push ``` If `gh` is unavailable: ask the human to create an empty **private** repo on github.com, then run: ``` git remote add origin git push -u origin main ``` ### P3. Protect `main` (HUMAN ACTION — you guide, they click) Tell the user, verbatim: > Open the repo on GitHub. Go to **Settings > Branches** (or **Rules > Rulesets**). Add protection for `main`. Enable **Require a pull request before merging** and **Block direct pushes / restrict who can push**. Save. If `gh` is available and the user prefers CLI, you may offer this after confirmation (classic protection): ``` gh api -X PUT repos///branches/main/protection \ -H "Accept: application/vnd.github+json" \ -f "required_pull_request_reviews[required_approving_review_count]=0" \ -F "enforce_admins=false" \ -F "restrictions=null" \ -F "required_status_checks=null" ``` Explain the trade-off: with one GitHub account, `enforce_admins=false` lets the owner merge without a second reviewer, which is what you want for a solo owner. Branch protection still blocks accidental direct pushes. ### P4. Verify (PRIMARY) Run and report every line: ``` git remote -v git log --oneline -1 git ls-files | grep -Ei '\.(mp4|mov|mkv|zip|env|pem|key)$' || echo "OK: no media or secrets tracked" ``` Then confirm with the user that branch protection is showing as active on GitHub. Only then report the primary machine as ready. --- ## SECONDARY machine path Do the Shared setup steps S1, S2, S4 first (you do NOT create the guard files from scratch here; they arrive with the clone). Then: ### C1. Create a repo-scoped token (HUMAN ACTION) Tell the user, verbatim: > On GitHub go to **Settings > Developer settings > Fine-grained personal access tokens > Generate new token**. Scope it to **only the brain repository**. Grant: **Contents: Read and write**, **Pull requests: Read and write**, **Metadata: Read**. Do NOT grant Administration. Set a short expiry. Generate it and copy it once. ### C2. Store the credential (HUMAN enters the secret) Do not read or echo the token. Set up the credential helper, then have the human paste the token at git's own prompt on first push, or via `gh auth login` choosing "paste a token". Instruct: ``` git config --global credential.helper store # or osxkeychain on macOS ``` The token is never committed and never printed. ### C3. Clone the brain ``` git clone cd git config user.name "" git config user.email "" ``` ### C4. Install the contributor guardrail Configure Claude Code on this machine to always branch and open a PR, never push to `main`. Add to this repo's `CLAUDE.md` a machine note the user confirms: ``` ## THIS IS THE SECONDARY MACHINE - Always: git pull, then work on a new branch. - Never push to main. Open a pull request and let the PRIMARY machine merge. ``` Optional hard stop: create a local pre-push hook that refuses pushes to `main`: ``` mkdir -p .git/hooks cat > .git/hooks/pre-push <<'HOOK' #!/bin/sh while read local_ref local_sha remote_ref remote_sha; do case "$remote_ref" in *refs/heads/main) echo "Blocked: this is the SECONDARY machine. Open a pull request instead."; exit 1;; esac done HOOK chmod +x .git/hooks/pre-push ``` ### C5. The working loop this machine uses from now on ``` git checkout main && git pull git checkout -b # ...do the work... git add -A && git commit -m "" git push -u origin gh pr create --fill # or open the PR on github.com ``` Then tell the user: the PRIMARY machine reviews and merges. ### C6. Reconnect connectors (HUMAN ACTION) Remind the user: MCP connectors and Claude Code plugins do not sync through git. Re-add the same ones used on the primary machine. About fifteen minutes. ### C7. Verify (SECONDARY) ``` git remote -v git branch --show-current # should NOT be main for real work git ls-files | grep -Ei '\.(mp4|mov|mkv|zip|env|pem|key)$' || echo "OK: no media or secrets tracked" ``` Do a dry-run: create a throwaway branch, make a tiny edit, push it, open a PR, and confirm the PR appears on GitHub. Then delete the throwaway branch. Only then report the secondary machine as ready. --- ## Final report (both roles) When done, give the user a short status: role set, repo URL, branch protection state, media excluded (yes), secrets excluded (yes), and the one-line daily habit for this machine. If anything did not pass, say so plainly and stop.