---
name: github-sync
description: Connect this brain to a private GitHub repository and keep it synced — install/sign in to the GitHub CLI, create the repo, set it as `origin`, push the full history, record it in `Agent/config.json`, and run the ongoing push/pull routine. Use when the owner says "sync to github", "back this up to github", "put my brain on github", "add a github remote", "push my brain to github", or asks how to back up or sync their notes off this machine. NOT an email setup of any kind (a local brain has no email channel) and NOT first-time setup (alexandria-install).
served: false
---

# Sync this brain to GitHub

The brain is already a complete local git repository — every note and every core
update since install day is in its history. This skill gives that history an
off-site home: a **private** GitHub repository set as `origin`. The rendered
`.gitignore` keeps `.alexandria/` (the software) out of the repo, and a
zip-installed brain holds no secrets, so the only thing that ever syncs is the
owner's notes. Once connected, the launch banner's *vault sync* line reads `ok`
instead of `local-only`.

**Already connected?** `git remote -v` — if `origin` exists, skip to **The sync
routine**.

## Connect (one time)

1. **The GitHub CLI.** `command -v gh` — if missing, install it:
   `brew install gh` on macOS (Homebrew arrived in the install steps); the
   package manager elsewhere.
2. **Sign in — the owner does this, not you.** `gh auth status`; if it isn't
   logged in, run `gh auth login` and hand the terminal to the owner — it walks
   a one-time browser code flow. Never ask for, read, or paste a token in chat.
3. **Commit anything in flight** so the first push is the whole brain:
   `git status --porcelain`; if dirty, `git add -A && git commit -m "vault: work
   in flight, committed before first sync"`.
4. **Create it, private, and push** — suggest a name (`alexandria-brain` is a
   fine default; their call) and confirm **private**: these are their notes.
   From the vault root:
   ```sh
   gh repo create <name> --private --source . --push
   ```
   One command: creates the repo, sets it as `origin`, pushes the full history.
   (Repo already made on github.com? Then `git remote add origin
   git@github.com:<owner>/<name>.git && git push -u origin main`.)
5. **Record it in config and re-render.** Set `"repo": "<owner>/<name>"` in
   `Agent/config.json` (the `owner/name` form, not a URL), then refresh Core so
   everything that reads the config sees the remote, and health-check:
   ```sh
   "$ALEX" update --no-pull --vault . && "$ALEX" doctor --vault .
   ```
   (`ALEX=".alexandria/app/.venv/bin/alexandria"` on a folder brain; plain
   `alexandria` on a checkout install.) Also flip the Obsidian Git plugin to
   full sync — the no-remote render ships it commit-only, and the Core
   re-render never touches it (it's Content, rendered once): in
   `.obsidian/plugins/obsidian-git/data.json` set `"autoPullInterval": 10`,
   `"autoPullOnBoot": true`, `"disablePush": false`. Commit the result and push:
   ```sh
   git add -A && git commit -m "vault: connected to github (<owner>/<name>)" && git push
   ```
6. **Verify, then report.** `git remote -v` shows origin; `git log origin/main
   -1` matches local. Tell the owner: the repo, that it's private, that only
   notes sync (never the software, never secrets). Don't pitch email on the
   back of this — a local brain has no email channel (hosted-tier feature).

## The sync routine

- **Push after work lands.** The brain commits per write; end any session that
  changed notes with `git push`.
- **Pull before work on a second machine.** `git pull --rebase` at session
  start. To stand the brain up on another machine: clone the repo, then unzip a
  current `Alexandria.zip` and move its `.alexandria/` folder in — the software
  never lives in the repo, so it arrives via the zip, and `update --from-zip`
  keeps it current.
- **A push rejection means the remote moved:** `git pull --rebase`, resolve,
  push again. Never force-push, and never rebase away commits that were already
  on the remote.

## Ground rules

- **Private unless the owner explicitly insists otherwise** — and if they do,
  warn once, plainly: everything in the repo is their notes, readable by anyone.
- The auth flow belongs to the owner. No tokens through chat, ever.
- If `gh repo create` fails on auth or scopes, `gh auth status` says why — fix
  the sign-in, don't hand-build tokens.
