How to set up AI agent config on a new laptop

The short answer

To set up AI agent config on a new laptop, move three things: your global instruction files, your skills, and the notes your agents read and write. Subagent definitions, the named helper agents you delegate to, travel alongside the skills. Recreate everything else on the new machine, including API tokens and machine-specific paths. Install your agent tools first, then put the instruction files back in the exact locations each tool expects.

Those files usually live as dotfiles: hidden configuration files scattered around your home directory. The approach that holds up across more than one machine is to keep them in a single folder you already sync, then have a command write them into each tool’s expected location. The rest of this guide covers what to move, three ways to move it, and the parts that quietly break.

What actually needs to move

Agent config is not one file. Most people restore the obvious one and miss the pieces that carried the useful behavior.

What it is	Typical location	Move it?
Global instructions for Claude Code	~/.claude/CLAUDE.md	Yes
Skills and subagent definitions	~/.claude/skills/, ~/.claude/agents/	Yes
Custom slash commands	~/.claude/commands/	Yes
Global instructions for other agents	~/.codex/AGENTS.md, ~/.gemini/GEMINI.md, copilot-instructions.md	Yes
Permissions, hooks, environment variables	~/.claude/settings.json	By hand, after review
MCP server setup	.mcp.json in each project, plus your user-level config	Yes, after checking the paths
Installed plugins and marketplaces	Claude Code’s own config	Reinstall rather than copy
Project instructions	Inside each repository	In git, if you committed and pushed
API keys, tokens, sign-in	Keychain or environment	No, re-authenticate
Notes your agents read and write	Your notes folder	Yes

Two rows deserve a second look. Check for uncommitted or gitignored project instruction files before you wipe the old machine. And if your agents have been logging decisions into notes, those notes are the memory: restoring the instructions without them gives you an agent that knows the rules but has forgotten every project.

Option one: copy the files by hand

For a single laptop move this is fine, and it is the honest baseline. Copy ~/.claude from the old machine, drop it on the new one, open settings.json, and delete anything pointing at a path that no longer exists.

The weakness shows up on the second machine. Hand copying keeps no record of which side is newer, so once you have a laptop and a desktop, you start guessing.

Option two: a dotfiles repository

Put your agent config in a git repository and symlink it into place on each machine. This works well, it is free, and version history is a genuine benefit when a new instruction makes your agent worse and you want to see what changed.

The cost is friction at the moment you least want it. Editing a rule mid-session means a commit, a push, and a pull on the other machine, so people batch the commits and the machines drift. Git also asks you to resolve conflicts in a text editor, which is awkward for a file you edit from more than one machine in a day.

Option three: keep the config with your notes

If your agents already read and write notes, the config can live in the same place. That is the approach Jotura takes. Your vault holds an Agents/ folder with your instruction files, skills, and subagent definitions, and one command reconciles it with the locations each tool expects.

Jotura itself is closed source. The vault is not: Agents/ is ordinary markdown files on disk, so you can read, diff, and back up every file without the app, and you can walk away with the folder.

On the new laptop, one command installs the app, the jotura command-line tool, and the agent skills:

curl -fsSL jotura.io/install.sh | bash

On Windows, run irm jotura.io/install.ps1 | iex in PowerShell. If piping a remote script into a shell makes you uneasy, and on this page it probably should, open jotura.io/install.sh in a browser and read it first. The regular installer bundles the same CLI.

Point the app at your vault, then look before you touch anything:

jotura agents status

That prints a read-only drift report: what is in the vault, what is on the system, and what differs. A new laptop often has starter files the tool wrote for itself, so preview the plan before writing:

jotura agents sync --dry-run

When the plan looks right, drop the flag. Sync reconciles both directions: system-side changes are pulled into the vault, vault changes are applied to the system. The first time it overwrites a system file it has never recorded, it copies the original to <name>.jotura-backup beside it. That is a one-shot safety net, not a version history.

One deliberate gap. Sync refuses to carry configuration and credential files: settings.json, config.toml, auth.json and private keys are excluded even if you name them yourself. Nothing holding a token can end up in a synced folder. Move settings.json yourself, and review it while you do.

Files changed on both sides are skipped rather than overwritten, and the command exits with code 16 so a script notices. Resolving means picking a whole side:

jotura agents sync --prefer vault

That discards the other side’s changes to those files. A git repository would have merged two non-overlapping edits automatically, so this is the simpler behavior, not the smarter one. Use --prefer system when the new laptop has the better version.

Two commands look similar and are not. jotura agents sync handles every tool it knows about in one pass, with no per-tool filter. jotura skill install claude (or all) is separate: it installs Jotura’s own skill file so the agent knows how to drive the CLI. It carries none of your restored config.

The costs are real: you are installing a notes app to solve a configuration problem, which only pays off if you wanted the notes app anyway. The free version gives you the Agents/ folder but no cloud sync, so getting it to the second machine still means Syncthing, git, or a cloud drive. A dotfiles repository hands you free version history and this does not, so if all you want is a diff of yesterday’s CLAUDE.md, git wins. Jotura runs on Mac, Windows, Linux, and Android, with no iOS app.

Restore Claude Code settings on a new machine

Claude Code needs four pieces back. Your global CLAUDE.md carries the standing instructions. The skills/ folder holds the workflows you invoke by name, and commands/ holds your custom slash commands. Permissions, environment variables, and hooks live in settings.json.

Restore the first three without editing them. Read settings.json before you trust it. Permission rules that allow a command in /Users/you/dev do nothing on a Windows box, and hooks calling a script you never copied fail on every session start. Fixing that on day one beats debugging it during real work.

Then verify with a session rather than by reading files. Ask the agent to summarize its own standing instructions back to you. If it names the rules you expect, the restore worked. If it produces a plausible summary of nothing, the file is not being loaded and your path is wrong.

What should not travel

Credentials belong in the new machine’s keychain or environment, not in a synced file. Signing in again takes a minute and keeps a secret out of a folder that reaches a server.

Absolute paths break, so replace them rather than porting them. Machine-specific settings, such as a local model endpoint or a sandbox exception, usually belong on one machine only.

Instructions you wrote for a project that has since finished are dead weight. They cost tokens every session and occasionally misdirect the agent, so a laptop move is a good moment to delete them.

Keeping both machines in step

Getting the new laptop working is the easy half. Staying in step is where setups fail, because you edit an instruction at a client site and the other machine never hears about it.

Keep one authoritative copy and edit that one, whether it lives in a git repository or a vault. Then check for drift when you sit down at the other machine. With Jotura that means jotura agents status, then jotura agents sync if it reports differences. The ongoing routine is its own topic, covered in syncing agent skills across computers.

All three options need a file sync mechanism underneath. Because a vault is an ordinary folder, Syncthing, git, and cloud drives all work on it. Jotura Sync is the built-in option at £4 per month or £40 per year, with no free trial. It is end-to-end encrypted, so the server never sees your filenames or your file contents.

Frequently asked questions

Do I need the old laptop still working? Only if the config exists nowhere else. If your instruction files live in a synced folder or a git repository, you can set the new machine up without touching the old one.

Will this restore my agent’s memory of past work? It restores the instructions, and your notes too if they are in the same synced folder. It does not restore conversation transcripts. Those sit outside the config directory, and whether they are worth copying depends on whether you actually search them. See give AI agents persistent memory for writing decisions into notes so they survive the move.

Where can I see the full command list? The jotura CLI reference covers every command, including the hash-checked writes agents use when editing notes.