Set up your AI coding tools once. Rebuild that setup on any machine.
Backup and migration for your Claude Code, Codex, Cursor, opencode, Copilot CLI, Kilo Code, and Antigravity setup — skills, subagents, plugins, hooks, settings, memories — into a private Git repo you own.
Quick start · Commands · How sign-in works · What still needs you after a pull · Secrets
You've spent months tuning Claude Code or Codex — custom skills, a stack of subagents, plugins, hooks, your CLAUDE.md. Then you get a new laptop and do it all again from scratch.
Arbella saves that whole setup into a private Git repo and puts it back on another machine with one command. Linux, macOS, Windows.
arbella setup # install what arbella leans on (git, gh, the tool CLIs)
arbella init # point it at a private repo, pick your options
arbella push # snapshot your setup and push it
# later, on another machine:
arbella pull https://github.com/you/your-setupNeeds Node 18+.
npm install -g arbella
arbella --help
arbella update # later: update arbella itself push ~/.claude · ~/.codex · Cursor · $HOME ──▶ strip · template ──▶ private repo
pull private repo ──▶ install · place ──▶ tools + Cursor User data + $HOME
push reads the parts of your setup that matter, strips anything secret, swaps machine-specific paths for placeholders, and pushes the result to your repo. pull does the reverse: installs the CLIs you don't have, drops files back with this machine's paths, merges MCP servers into ~/.claude.json, writes shared home files back under $HOME, reinstalls plugins, skills, and external tools, and wires shared Claude/Codex instructions back into CLAUDE.md and AGENTS.md.
Beyond the obvious config files, Arbella also carries:
| It also carries | Where it comes from | Notes |
|---|---|---|
| MCP servers | ~/.claude.json → mcpServers |
Never the whole file — only the server definitions, sanitized and templated; env values are redacted unless includeSecrets is on |
The rest of ~/.claude |
rules/, scripts/, output-styles/, keybindings.json, mcp-configs/, AGENTS.md |
The pieces your hooks and CLAUDE.md actually reference |
| Shared home files | shared/home/ |
Scripts your hooks, statusLine, or MCP commands point at outside any tool's home — picked up automatically (one hop, files only, 1 MiB cap) — plus anything you list in extraPaths, and the claude-mem companion ~/.claude-mem/settings.json |
| Claude memories | claude/memories/ |
Per-project memory, only when includeMemories is on |
| External tools | manifest externalTools |
Binaries behind an MCP/hook command that brew, uv tool, or pipx installed — reinstalled best-effort on pull |
Two things it deliberately won't do:
- Excludes secrets by default. Whole credential files —
auth.json,.credentials.json, and the like — sit on a hard denylist and are never read into the repo, no exceptions. Inline secret-shaped values (API keys, OAuth tokens) found in files that are captured are redacted by default;includeSecretsis the explicit opt-in that carries them verbatim into your (private) repo instead. You sign back in after a pull, or carry credentials yourself witharbella secrets. - Reinstalls plugins from their sources. Plugins are saved as a list and pulled fresh. Local and shared skills include their contents, preserving local edits and avoiding guesses about their original source.
Supported today: Claude Code, Codex, Cursor (IDE + the cursor-agent CLI), opencode, GitHub Copilot CLI, Kilo Code, and Google Antigravity. Claude Code coverage also reaches into ~/.claude.json for MCP servers, per-project memories, and any linked scripts living under $HOME. Cursor support covers global MCP config, user settings, keybindings, snippets, local skills, shared skill contents with their symlinks, the cursor-agent CLI config + global commands, and extension IDs; runtime state and credentials stay out. opencode, Copilot CLI, and Kilo are config-dir CLIs — Arbella captures each one's config dir (the JSON/JSONC config, custom agents/commands, MCP config), strips token-shaped values, and skips machine-local state, plugin install artifacts, and reinstallable skills (regenerated from the config on first run). Antigravity spans three roots — its VS Code-style User settings, the ~/.antigravity extension list, and the shared ~/.gemini agent config (global rules, MCP servers, skills) — while its Google OAuth tokens never leave your machine.
| Command | What it does |
|---|---|
arbella setup |
Install git, the provider CLIs, and the AI tool CLIs |
arbella init |
One-time wiring: pick a repo and your options |
arbella push |
Snapshot your setup and push it — the everyday one |
arbella pull <url> |
Rebuild your setup on a fresh machine |
arbella status |
Show what a push would change — read-only |
arbella update |
Update arbella itself through npm |
arbella auth |
Sign in to your repo host |
arbella secrets |
Move credentials between machines, off Git |
Every prompt has a flag, so anything interactive can be scripted. --dry-run works wherever it makes sense.
Checks what's installed and offers to fill the gaps — a checklist, so you tick what you actually use.
arbella setup # interactive checklist
arbella setup --all # everything, no prompts
arbella setup --deps git,gh -y # just these- Covers git (required), gh / glab (handle sign-in for you), and the AI CLIs (claude, codex, cursor, opencode, copilot, kilo).
- Installs through your system's package manager: apt, dnf, or pacman on Linux, Homebrew on macOS, winget on Windows.
initandpullalso install on demand — if something's missing when you run them, Arbella stops and asks first.
The one-time wiring. Pick a host (GitHub, GitLab, or a plain Git URL); if the repo doesn't exist yet, Arbella creates it private for you.
arbella init
arbella init --provider github --repo you/your-setup --auto-push daily -y
arbella init --extra-paths ~/.agents/hooks,~/.agents/memory -ySaves your preferences:
- which tools Arbella should manage
- who wins a conflict — your machine or the repo
- auto-push cadence — off, once per session, or daily
- whether secrets are allowed into the repo (off by default), and whether to include memories (also off)
- extra
$HOMEpaths to carry along (--extra-paths, comma-separated, or the interactive prompt) — Arbella pre-fills the prompt with suggestions from the scripts your hooks and MCP servers already point at. Suggestions are never accepted on your behalf:-ykeeps whatever is already configured, so pass--extra-pathsto carry them non-interactively
The one you'll run most. Captures your current setup, sanitizes it, commits, and pushes. Run it whenever you've changed something worth keeping, or let the auto-push hook do it in the background.
arbella push
arbella push --dry-run # show exactly what goes in (and what's skipped), write nothingWorth a --dry-run before your first real push, so there are no surprises.
The reason the whole thing exists.
arbella pull https://github.com/you/your-setup
arbella pull <url> --dry-runpull --dry-run does not alter your tool setup or persistent backup clone. It
plans from an existing local clone without refreshing it; when there is no clone
yet, it makes a temporary download for the preview and removes it afterwards.
- First copies your current
~/.claudeand~/.codexto a timestamped safety folder, so a pull can't quietly wreck what's already there. - Installs any missing CLIs — reaching for
sudoonly when the global npm folder actually needs root. - Writes files with this machine's paths, then reinstalls your plugins and skills from the manifest.
- Merges MCP servers into
~/.claude.json— a safety copy is taken first; the file is read in full, only themcpServerskeys (user- and project-scope) are changed, every other key (auth, telemetry) is carried over unchanged, and the whole file is rewritten atomically so it's never left half-written. - Writes shared home files (linked scripts,
extraPaths) back under$HOME— an existing file is snapshotted first and never overwritten while your machine is the source of truth. - Reinstalls external tools behind MCP/hook commands via brew,
uv tool, or pipx, best-effort. - Deploys your shared instructions to
CLAUDE.mdandAGENTS.md. - Reminds you to sign back in for credential stores that never travel. With the default secret setting, it also lists inline values that were redacted and need to be supplied again.
Read-only. It answers one question: if you ran push right now, what would change?
arbella status
arbella status --json # pipe it somewhereNew and modified files, plugin drift, MCP server and external-tool drift, and the secrets it would skip. Files it doesn't recognize print as not backed up (unknown to arbella) — add them via extraPaths or open an issue. Writes nothing, installs nothing.
Updates the Arbella CLI package itself. It does not touch your backed-up Claude, Codex, or Cursor setup.
arbella update # npm install -g arbella@latest
arbella update --version 0.1.2 # pin a specific release
arbella update --dry-run # show the npm command onlyHandles sign-in to your repo host. You rarely call it yourself — push and pull sign in on their own when they hit a private repo. It's here for when you'd rather log in ahead of time, or check where you stand.
arbella auth login
arbella auth status
arbella auth login --provider gitlab
arbella auth login --device-flow # skip gh/glab, use Arbella's own flowFor the credentials that never belong in the repo. Git is never involved — you carry the blob between your own machines yourself.
arbella secrets export # encrypted, passphrase-protected blob (AES-256-GCM)
arbella secrets import # unpack it on the other machineShort version: gh and glab are preferred, not required. They're the smoothest route, and the one I'd point you to — but Arbella works without them.
| Situation | What Arbella does |
|---|---|
| CLI installed and signed in | Uses it directly. gh/glab already do OAuth properly and configure Git's credentials, so nothing sensitive passes through Arbella. |
| CLI installed, signed out | Runs its auth login for you — prints a URL and a code you type into your browser. |
| CLI missing | Offers to install it, or falls back to its own path: an OAuth device flow, or a pasted token kept in a local 0600 file. |
For the device flow, point Arbella at your own registered OAuth app with ARBELLA_GITHUB_CLIENT_ID (or ARBELLA_GITLAB_CLIENT_ID). There's no sensible default to ship — the client ID is public but tied to your account — so with none set, Arbella skips the device flow and asks for a token instead. SSH and file:// remotes are left alone, so those keep working however your Git already has them.
Arbella restores everything it safely can. A few things are yours to finish:
- Credentials. Credential stores never travel, so sign back in when Arbella tells you to, or carry them yourself with
arbella secrets. By default, inline API keys and OAuth tokens are redacted too;includeSecretsis the explicit private-repo opt-in that carries those inline values. - Redacted MCP env values. If an MCP server's config held a secret-shaped value, push replaced it with
{{REDACTED}}. Pull prints one line per key it couldn't restore, e.g.claude: MCP server serena needs env SERENA_TOKEN re-supplied (redacted on backup). - Per-project MCP servers for a project you haven't cloned yet. A project's MCP servers are only registered when its directory exists on this machine; if it doesn't, pull skips them and warns you which directory was skipped. Clone the project, then run
arbella pullagain. - External tools Arbella couldn't classify or install. brew/
uv tool/pipx tools are reinstalled best-effort; anything unknown, or that failed, is listed by name and by what uses it, so you can install it yourself. ~/.claude.jsonis only merged, key by key. Pull touchesmcpServers(and per-projectmcpServers) and nothing else in that file — youroauthAccount, telemetry, and everything else stay exactly as they were.- The repo is trusted. A pull writes the hooks, MCP commands, and install lists your repo describes, and runs
brew/uv tool/pipx/npmfor the tools it lists — exactly like the machine you pushed from. Keep the repo private, and runarbella pull <url> --dry-runfirst on anything you did not push yourself: the plan prints every command and target path.
This is the part I most wanted to get right.
- Whole credential files (
auth.json,.credentials.json, and the like) sit on a hard denylist and are never read into the repo. - Everything that does get committed runs through a sanitizer that redacts token-shaped values.
~/.claude.jsonitself is still never stored — only itsmcpServerssub-objects are lifted out, sanitized, and templated; the rest of that file (OAuth account, telemetry) never leaves your machine.- Shared home files go through the same sanitizer, plus a home-specific denylist —
.env,*.pem,*.key,id_rsa*,.netrc,.npmrc,.git-credentials, and friends are never captured even when something points at them. - Any token Arbella holds for itself lives in one local file with
0600permissions — not in the repo, not in a logged command, not baked into a Git remote. - A test fails the build if a credential can reach the repo. This isn't on the honor system.
Putting secrets in the repo is opt-in, and the default is off. It's your private repo and your call — but I'd leave it there.
Paths get templated, so a setup captured on a Mac under /Users/you restores correctly on Linux under /home/you, or on Windows. The one place the machine matters is global npm installs: on a system Node the folder is root-owned, so Arbella elevates with sudo and tells you it's doing so; on nvm, Homebrew, or Windows it's already yours, so it skips sudo. It checks first instead of guessing.
The Arbella was the flagship of the 1630 Winthrop Fleet — a few hundred settlers, their livestock, and the colony's founding charter, carried across the Atlantic to start over somewhere new. That's the idea here: pack up the things that make your environment yours, carry them across, and unpack on the other side.
v1.0.0 — builds clean, the full test suite passes, and I use it daily. Issues and pull requests welcome.
Merging to main runs the Linux, macOS, and Windows checks first. When they pass,
publish.yml publishes to npm and creates the GitHub tag and release automatically.
The first release from the existing 0.x tags is 1.0.0. This jump is one-time;
subsequent commits determine the next version:
fix: ..., documentation, maintenance, or other changes increment the patch version (for example, 1.0.0 → 1.0.1).feat: ...increments the minor version (for example, 1.0.1 → 1.1.0).- A
BREAKING CHANGE:footer or a!after the commit type/scope increments the major version.
Use the same conventions in the PR title when squash merging. No manual version bump,
tag, or GitHub release is needed. Re-running a successful release does not bump again.
The published package and arbella --version use the computed version; the source
package.json stays at its baseline because release versions are tracked by Git tags.
Publishing uses npm trusted publishing.
The arbella package's npm Settings must have a GitHub Actions trusted publisher with
owner Fafoooo, repository arbella, and workflow filename publish.yml
(no environment name). This avoids maintaining an npm token in GitHub secrets.
Release tooling runs separately on Node 24; Arbella itself continues to support Node 18+.
Copyright (c) 2026 Fafoooo.
Arbella is licensed under the GNU Affero General Public License v3.0 only (AGPL-3.0-only). See LICENSE.