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 Windows; it’s a few one-time steps, and here’s why it’s worth it.
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 PC 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 PC is lost, stolen, or fails, your project is safe online — not gone with the machine.
- 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 PC.
- 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 PC 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, a free GitHub account (create one at github.com/signup), and Git for Windows, which includes the Git Bash app you’ll use below. If you don’t have it, get it free from git-scm.com/download/win and install with the default options.
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:
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 Git Bash (installed with Git for Windows — find it in the Start menu) 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/' >> .gitignoreOpen a blank file in Notepad and paste your token into it (using an editor means the token never appears in a command or your history):
notepad .craft-secrets/gh.tokenIn Notepad: paste the token (Ctrl+V), save with Ctrl+S, then close the window. (If Notepad asks to create the file, choose Yes.)
About file safety on Windows: Windows handles file permissions differently from a Mac, so there’s no chmod step. The protection that matters is the .gitignore rule you just added — it keeps the token file off GitHub — and the file lives in your private user folder. Keep it there and don’t share it.
✓ You’ll know it worked when the file .craft-secrets/gh.token exists and holds your token.
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:
✓ 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 PC).
Optional: double-check the token file
In Git Bash, 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.tokenIf 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:
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:
✓ 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.tokenin Git Bash) — stops this PC 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 (Step 3), 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-ignoreprinted nothing — the ignore rule didn’t take. Re-run the.gitignoreline 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 Windows: 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.