Setup runbook

Two-Machine Claude Code Setup

A step-by-step guide to run Claude Code across two machines with one shared brain in a private GitHub repo. The primary machine owns main. The secondary machine contributes through pull requests. The terabytes of video stay in cloud storage and never enter git. Start with the evaluation step so your own Claude checks this against what you already run before you change anything.

Human you do this yourself Claude Claude Code does this for you

The mental model in one line. Git carries the text brain and keeps both machines in sync. Cloud storage carries the media. The two never mix. Everything below is just plumbing to make that true and to keep main under one owner.

Start here: evaluate before you adopt

Do not run this setup blindly. The right first move is to have your own Claude look at these files, inspect what you already run, and tell you honestly whether this is actually an upgrade for you. Here is the full path from the email to a decision.

Save the files. You got three files by email: architecture-diagram.html, setup-runbook.html, and CLAUDE-SETUP.md. Download all three into one new folder on the machine you want to evaluate.
Open Claude Code in that folder. Start Claude Code from that folder, or open the folder in your Claude Code workspace, so it can read all three files.
Paste the evaluation prompt below as your first message. It tells Claude to act as an AI security and Claude structure engineer, read the three files, inspect your current setup, and judge whether adopting this helps you.
Answer Claude's questions. It will ask about your machines, where your brain lives, how you sync today, and how you store secrets. Answer plainly.
Read the assessment. You get a verdict (adopt, adopt in part, or keep current), a side-by-side comparison, the real risks, and an action plan tailored to you rather than the generic runbook.
Decide, then proceed only if it fits. If you approve, Claude walks you through setup using CLAUDE-SETUP.md, one confirmation at a time. Nothing on your machine changes until you say go.

Copy-paste this into Claude Code

You are acting as a senior AI security engineer and Claude Code systems architect. Evaluate a proposed two-machine Claude Code setup against my current environment and tell me honestly whether adopting it would improve my outcomes. Do not assume the proposal is better than what I already have. Make no changes to my system during this evaluation. This is a read only inspection. You will propose changes only after I approve. INPUTS. I am giving you three files that describe the proposed architecture: 1. architecture-diagram.html, a one page visual of the target architecture 2. setup-runbook.html, the human setup runbook 3. CLAUDE-SETUP.md, machine executable setup instructions Read all three in full before forming any opinion. STEP 1, understand the proposal. In your own words, summarize the architecture, the security model (credential scoping, branch protection, secret handling), the git and sync model, how large media files are handled, the role split between the primary and secondary machines, and the daily workflow. Note every assumption the proposal makes. STEP 2, inspect my current setup, ask before you assume. Learn my real environment first. Inspect what you can access: my current repo or vault folder, its .gitignore, .git config, remotes, any visible branch protection, how Claude Code is configured here, where my brain and context files live, how secrets and tokens are stored today, and where my large or media files live. For anything you cannot determine by inspection, ask me. At minimum confirm: - Do I already work across more than one machine, and how do I sync today - Where my brain and context currently live: local only, cloud sync, or git - Whether my brain is already in a git repo, public or private, single owner or shared - How I currently store secrets and API tokens - Where my large or media files live and roughly how large they are - The operating system of each machine - Which Claude model and Claude Code version I am running Batch your questions so I can answer them in one pass. Do not move on until you have enough to be accurate. STEP 3, compare and assess. Produce a side by side comparison of my current setup versus the proposed setup across these dimensions: secret safety, credential least privilege, branch and ownership control, sync reliability and conflict risk, large file and media handling and cost, recoverability and backup, role separation across machines, portability to a new machine, and maintenance burden. For each dimension, say which is better and why, and name the real risk. Then call out explicitly: - Where the proposal is a genuine improvement for me - Where my current setup is already equal or better, so I should keep it - Any risk, downside, or one way door in adopting the proposal - Anything in the proposed files that is a security concern or does not fit my situation STEP 4, verdict and tailored action items. Give a clear verdict: adopt fully, adopt in part with the specific parts listed, or keep current. Then give me a prioritized numbered action plan tailored to my environment, not the generic runbook. Separate the steps only I can do (creating tokens, protecting the main branch, entering credentials) from the steps you can do for me. Flag every step that is outward facing or hard to reverse. STEP 5, offer to proceed, do not auto run. Tell me which Claude model you are and how that affects how much you can safely execute versus hand to me. Then ask whether I want to proceed. Only if I say yes, walk me through adoption step by step using CLAUDE-SETUP.md, pausing for my confirmation before any push, any credential step, or any branch protection change. Never enter a secret on my behalf. Ground rules for this whole task: - Be critical and specific, not flattering. If this will not help me, say so plainly. - Stay read only until I approve changes. - Never handle a secret in plain text.

Read this before the reference steps below. Everything from here down is the reference setup. It is not meant to be run blindly. Let the evaluation above decide which parts actually apply to you, then follow only those.

Before you start (both machines)

Git installed. Check with git --version.
The GitHub CLI is recommended: gh. It makes auth and repo creation a one-liner.
Claude Code installed and signed in.
A GitHub account. You will use the same account on both machines. Roles are enforced by branch protection and per-machine credentials, not by separate logins.

Part A. Primary machine (the owner of main)

Run this once, on the machine that holds the authoritative brain.

Claude Scaffold the brain repo.

Claude creates the folder structure, a starter CLAUDE.md, a .gitignore that blocks media and secrets, and a .gitattributes for clean cross-machine line endings. It then runs the first commit.

Human Create the private repo on GitHub.

Easiest path, Claude runs it after you confirm:

gh repo create my-brain --private --source=. --remote=origin --push

If you prefer the website, create an empty private repo, then Claude wires up the remote and pushes.

Human Protect the main branch.

On GitHub, go to Settings, then Branches, then Add branch ruleset (or classic protection) for main. Turn on Require a pull request before merging and Block direct pushes. This is the switch that makes main owner-controlled. Now every change lands through a reviewed pull request.

Human Authenticate this machine with write access.

Run gh auth login and follow the prompts, or add this machine's SSH key to your GitHub account. Claude will tell you exactly which, but it cannot type your credentials for you. That step is always yours.

Claude Set up machine-local memory and verify.

Claude points Claude Code memory at a local, git-ignored location so the two machines never fight over it, then runs a verification pass: repo pushed, main protected, media excluded, secrets excluded.

Part B. Secondary machine (the contributor)

Run this on the second machine after Part A is done.

Human Create a repo-scoped credential.

On GitHub, go to Settings, then Developer settings, then Fine-grained tokens. Create a token limited to the one brain repo with these permissions: Contents: Read and write, Pull requests: Read and write, Metadata: Read. Do not grant administration. This lets the second machine push branches and open pull requests, but it cannot rewrite protected history. Give the token a short expiry and renew it.

Human Hand the token to Claude to store.

Paste the token when Claude asks, or better, let Claude configure the git credential helper and paste it into the system prompt only once. The token is a secret. It never gets committed.

Claude Clone the brain and configure the workflow.

Claude clones the repo, sets your git identity, sets up machine-local memory, and installs a local guardrail so it always works on a branch and opens a pull request instead of pushing to main.

Human Reconnect MCP connectors and plugins.

These do not travel through git. Re-add the same connectors and plugins you use on the primary machine. Budget about fifteen minutes.

The daily rhythm

Primary machine	Secondary machine
Pull, work, commit. Merge pull requests from the secondary. You are the gate on `main`.	Pull first. Work on a branch. Push the branch. Open a pull request. Wait for the primary to merge.

Golden habit. Always git pull before you start a session, and never leave uncommitted work stranded on the other machine. With git as the sync layer, that single habit prevents almost every conflict.

The media library

Keep the terabytes of video exactly where they are, in cloud storage. Sync or mount them locally on whichever machine is doing the editing work.
Do not use git-LFS for a multi-terabyte library. It bills on storage and bandwidth and gets expensive fast. LFS is for the occasional large asset, not a media catalog.
When Claude works with the video, it writes the outputs, transcripts, metadata, and edit notes, back into the brain repo as text. Text flows through git. Media never does.

Guardrails and gotchas

Secrets never get committed. The .gitignore blocks .env, any *.local.* file, and settings.local.json. A leaked token is a bad day, so keep the discipline.
Memory stays machine-local. Shared, durable knowledge belongs in committed notes. Claude Code auto-memory stays per-machine to avoid merge conflicts. Promote anything important from memory into a note that gets committed.
Cross-operating-system line endings. If the two machines are a Mac and a Windows box, the .gitattributes Claude adds normalizes line endings so diffs stay clean.
Do not run heavy edits on both machines at the same time against the same branch. Pull before you start.

One honest note on enforcement. Because both machines use the same GitHub account, the primary-versus-secondary split is enforced by branch protection plus the scoped token plus the workflow habit, not by separate user identities. That is the right level for a two-machine personal setup. If you ever want hard, technical separation that a person cannot bypass, the next step up is a dedicated bot account added as a write-only collaborator, with review required on every merge. You do not need that on day one.

Companion files: architecture-diagram.html for the one-page picture, EVALUATION-PROMPT.md for the copy-paste evaluation prompt on its own, and CLAUDE-SETUP.md for the machine to read and execute after you decide to adopt.