# How it works

> What is stored in the repo, and what gets written to this machine on a pull.

## Profiles

A profile is one Claude Code setup. In the repo it looks like this:

```text
aisync-config/
  aisync.json
  secrets.json              encrypted tokens
  profiles/
    default/
      profile.json          config folder, base profile, environment
      mcp.json              MCP server definitions (tokens as references)
      files/                files that go into ~/.claude
        settings.json
        CLAUDE.md
        skills/…
```

Each profile has one config folder: `~/.claude` for `default`, `~/.claude-<name>` for any other. That is the same unit as Claude Code's `CLAUDE_CONFIG_DIR`, so one profile lines up with one Claude Code account.

## What moves and what stays

| Moves | Stays |
|---|---|
| `settings.json`, `CLAUDE.md`, `keybindings.json` | Your Claude login |
| `skills/`, `agents/`, `commands/`, `output-styles/`, `workflows/` | `projects/`, `history.jsonl`, sessions, caches |
| User MCP servers (`mcpServers` in `.claude.json`) | Everything else in `.claude.json` |
| | `skills/synced/`, `skills/.trash/` (managed by Claude) |
| | Plugin files. Instead, a pull installs every plugin settings.json enables, adding its marketplace first (`--no-plugins` skips it) |

A pull only touches the files and MCP servers on this list. Servers or files you added yourself stay.

## Paths

Hooks and MCP commands often contain absolute paths like `/Users/alice/...`. aisync stores your home directory as `{{home}}` and expands it on pull, so paths work on a machine with a different user name.

## What a pull does

1. Downloads the latest state of the repo.
2. Shows what it will add, change and remove. With `--dry-run` it stops here.
3. Checks that this machine can decrypt every token the profile uses, asking for the passphrase if there is no key yet. If it can't, it writes nothing.
4. Copies every file it will change or remove to `<config folder>/.aisync/backup/<time>/`.
5. Writes the files, and in `.claude.json` changes only this profile's entries under `mcpServers`.
6. Records what it placed in `<config folder>/.aisync/manifest.json`.

That record is how the next pull tells "files I changed here" from "files that changed in the repo".

## What a push does

1. Reads back the files and servers the last pull placed. Add new ones with `--add` and `--add-server`.
2. Turns your home directory back into `{{home}}` and checks that no token slipped in.
3. Commits the changes in one commit through the GitHub API. git is not needed.

## With Claude Code running

Claude Code re-reads `.claude.json` right before writing it, so a running session doesn't undo what aisync changed. It loads MCP servers only at startup, though, so restart the session after a pull.