---
name: clauderoam
description: Use when the user wants to set up, sync, restore, back up, or move their Claude Code configuration and memory across machines — e.g. a new Mac, switching Claude accounts, "my settings/memory aren't here", "back up my Claude setup", "make my config follow me", "sync my Claude Code across computers". Drives the clauderoam CLI; do not hand-roll symlinks or git steps.
user-invocable: true
---

# clauderoam — config + memory that follow you across machines

ClaudeRoam keeps the user's portable Claude Code state — `CLAUDE.md`, `agents/`,
`commands/`, `skills/`, the project registry, and per-project **memory** — in a private
git repo that is symlinked into `~/.claude/`. Your job is to drive its CLI, not to
re-implement the symlinking or git logic by hand.

**Invoked as `/clauderoam [args]`?** With args, run `clauderoam <args>` (after step 1)
and explain the result. With no args, run `clauderoam status` and summarize what
clauderoam does plus the common next steps below.

## 1. Make sure the CLI exists

Run `command -v clauderoam`. If missing, install it (then re-check):
- `brew install YunyueLi/tap/clauderoam` (preferred), or
- `curl -fsSL https://raw.githubusercontent.com/YunyueLi/ClaudeRoam/main/install.sh | bash`

## 2. Map the user's intent to one command

| User wants… | Command |
|---|---|
| First machine — create their config repo | `clauderoam init` (interactive), then push `~/clauderoam` to a **private** GitHub repo |
| New machine — they already have a config repo | `clauderoam setup <repo-url>` — clones, symlinks, restores memory, clones projects (one shot) |
| Save current state to GitHub | `clauderoam push` |
| Pull config + memory onto this machine | `clauderoam install` (symlinks + restores memory; `--no-restore` to skip) |
| Bring memory back / after a username change | `clauderoam restore` (gap-fill; `--force` to overwrite live memory) |
| Health check / current state | `clauderoam doctor` / `clauderoam status` |
| Choose which project repos follow them | `clauderoam projects add` / `list` / `clone-all` / `pull-all` |

Run `clauderoam help` if unsure.

## 3. Safety

- The config repo must be **private** — memory can contain personal notes.
- Never add `.credentials.json` (account auth) to the repo; clauderoam keeps it
  machine-local by design — don't override that.
- After `setup`/`install`, tell the user to **restart Claude Code** to load the symlinked config.
- Confirm before destructive/account-affecting steps: `restore --force`, `push --force`,
  deleting the repo. Memory divergence across machines is union-merged (lossless) by `push`.