Set up GitHub to back up your CRAFT project (on a Mac)

CRAFT Tutorials · Advanced

Connecting GitHub gives your CRAFT project a safe offsite backup and a full history of your work — and lets Claude save it for you, automatically. These steps are written for a Mac; it’s a few one-time steps, and here’s why it’s worth it.

💻 On a Windows PC? Use the Windows version of this guide instead.

First, the important part: this is optional. CRAFT works fully without GitHub. Your project, your memory, your handoffs, and your file backups all live safely on your Mac either way. GitHub adds an offsite copy and lets Claude save your work online for you — a convenience and a safety net, not a requirement. If you’d rather skip it, you can — nothing else in CRAFT depends on it.

Why connect GitHub?

CRAFT already protects your work locally — it saves handoffs and can back up files inside your project folder. GitHub adds three things local backups can’t:

  • An offsite copy. If your Mac is lost, stolen, or fails, your project is safe online — not gone with the laptop.
  • A full history. Every saved version is kept, so you can look back — or recover — far beyond your most recent local backup.
  • Work across devices. Pick the project back up on another computer instead of hand-copying folders around.

And once it’s set up, the biggest benefit is that Claude does the saving for you — more on how automatic that is below.

With GitHub vs. without

Without GitHub

  • Your work lives only on this Mac.
  • Backups are local copies in your project folder.
  • Recovery depends on what’s on that one machine.
  • Moving to another device means copying folders by hand.
  • Everything else in CRAFT still works — recipes, personas, handoffs, research.

With GitHub

  • Your project is also saved offsite, automatically.
  • A full version history you can browse and restore from.
  • If the Mac dies, your work is recoverable from GitHub.
  • Open the project on another device by pulling from GitHub.
  • Claude can save to GitHub for you with a single sentence.

Before you start: you’ll need a CRAFT project and a free GitHub account. If you don’t have an account yet, create one at github.com/signup — it’s free.

Step 1 — Create a private repository for your project

A repository (or “repo”) is just your project’s home on GitHub. On GitHub, create a New repository for your CRAFT project, and — this matters — set it to Private.

Why private? Your CRAFT project holds your work, your notes, and your handoffs. A public repo is visible to the entire internet. Private keeps it to just you (and anyone you invite). If you’re unsure, have Claude explain it in plain terms:

›Explain why my CRAFT repository should be private, and the risks of making it public.

Step 2 — Create your access token (PAT)

To save to GitHub on your behalf, CRAFT needs permission. GitHub grants that with a personal access token (PAT) — a long secret string that works like a password for one specific job. Create it on GitHub with these CRAFT-specific settings:

  • Type: Fine-grained personal access token.
  • Expiration: 90 days (recommended — short-lived is safer).
  • Repository access: Only select repositories → the private repo you just created.
  • Permissions: Repository permissions → Contents → Read and write. Leave the rest as-is.

GitHub shows the token only once. Keep it on your clipboard for the next step — and never paste it into the chat (anything typed into a chat can be stored by the AI provider).

📎 Official GitHub guide

Managing your personal access tokens — GitHub owns and maintains this screen; check their guide for the current clicks.

Step 3 — Save the token in a private file

Open Terminal (your Mac’s command app, in Applications → Utilities) and run these from inside your CRAFT project folder. First, make a private folder and make sure it’s never uploaded to GitHub:

mkdir -p .craft-secrets
echo '.craft-secrets/' >> .gitignore

Open a blank file in a simple editor and paste your token into it (using an editor means the token never appears in a command or your history):

nano .craft-secrets/gh.token

Paste the token (⌘V), then press Ctrl+O and Enter to save, and Ctrl+X to exit. Finally, lock the file so only you can read it:

chmod 600 .craft-secrets/gh.token

✓ You’ll know it worked when the file .craft-secrets/gh.token exists and only you can read it.

Step 4 — Connect and do your first save

Now let Claude connect your project to the repo and push it for the first time — just ask:

›Connect this project to my GitHub repo and save my work.

✓ You’ll know it worked when you refresh your repository page on GitHub and see your project files there — and your .craft-secrets folder is not among them (that stays private on your Mac).

Optional: double-check the token file

Confirm the file is present and not empty (this does not print your token), and that GitHub will never receive it:

test -s .craft-secrets/gh.token && echo "OK: token file is present" || echo "MISSING: create it first"
git check-ignore .craft-secrets/gh.token

If the second command prints the path, you’re protected. If it prints nothing, re-run the .gitignore line from Step 3.

How automatic it is from here

That setup happens once. After it, you never touch the token again — saving your work online becomes a single sentence:

›Save my work to GitHub.

Claude handles the rest — packaging what changed and pushing it for you, no Git commands to remember. You can also fold it into how you already end a session:

›Save a handoff and back it up to GitHub.

✓ That’s the payoff: one-time setup, then your work goes offsite on demand — just by asking. The effort here buys you a backup habit that costs nothing per session.

Keep your token safe: delete vs. revoke

These are not the same thing, and the difference matters:

  • Delete the file (rm -f .craft-secrets/gh.token) — stops this Mac from using the token. The token still works elsewhere.
  • Revoke on GitHub — switches the token off everywhere, permanently.

If a token is ever exposed — pasted into chat, printed on screen, committed to a repo — revoke it immediately; deleting the file (or the chat message) is not enough.

📎 GitHub’s guide: Token expiration and revocation.

How do I rotate (replace) a token?

Do this near its expiry, after deleting it, or if you suspect it leaked: create a fresh token (Step 2), remove the old file, save the new one, re-lock it with chmod 600, and then revoke the old token on GitHub so only the new one is live.

Troubleshooting

  • “Credential file missing” — the file isn’t where CRAFT expects it. Re-run Step 3 from your project’s top-level folder.
  • git check-ignore printed nothing — the ignore rule didn’t take. Re-run the .gitignore line from Step 3.
  • A save failed with an authentication error — your token may have expired or be missing Contents: Read and write. Make a fresh one (Step 2) and save it again (Step 3).

That’s GitHub for CRAFT on a Mac: optional, set up once, and from then on your work backs up offsite whenever you ask — with your token kept out of the chat. A good next step: Work across two devices.

Similar Posts