Change machines

Your project and its tracking travel through GitHub. Agent sign-ins, approvals and conversations stay local. On the destination machine, prepare PALABRE, then create a new teammate with --new.

This path applies to Windows, macOS and Linux. On a previously used machine, start with the inventory below. Do not delete any old clone or .palabre/ folder before finding the work you need to keep.

1. Take inventory without changing installations

In each old clone, on both machines if they are accessible:

git --no-optional-locks status --short --branch
git --no-optional-locks diff --stat
git --no-optional-locks diff --cached --stat
git log --oneline --branches --not --remotes
git worktree list

These commands show modified or untracked files, commits missing from local remote-tracking references and separate worktrees. References may be outdated: also check GitHub before concluding that a commit was pushed. --no-optional-locks avoids optional index refreshes during this inventory. Do not update a clone containing unsaved work yet.

Find which installations are being used. In PowerShell:

Get-Command node,palabre,codex,claude,pwsh,powershell -All -ErrorAction SilentlyContinue | Select-Object Name,Source

In Bash or Zsh, on macOS or Linux:

type -a node palabre codex claude

For commands that are present, record their versions:

node --version
palabre --version
codex --version
claude --version

Several paths may mean several installations. On Windows, a WindowsApps path may be a Microsoft Store alias rather than the expected installation. Do not delete anything just to hide a duplicate; identify the installation to keep using Windows troubleshooting. Complete duplicate diagnostics remain tracked in #153.

Also check whether the personal PALABRE folder exists. PowerShell:

if (Test-Path -LiteralPath "$HOME/.palabre") {
    Get-ChildItem -LiteralPath "$HOME/.palabre" -Force
}

POSIX shell:

if [ -d "$HOME/.palabre" ]; then
    ls -la "$HOME/.palabre"
fi

Locate project configurations (palabre.config.json, or the older chicane.config.json) and skill copies: ~/.agents/skills/palabre/, ~/.claude/skills/palabre/, the older ~/.codex/skills/palabre/ and project skill directories. Also check skills added through your application. Keep backups outside directories where agents load their skills.

PALABRE installed from a repository clone (development version)

If palabre --version shows an old version installed from a clone, update the clone yourself, after preserving the work identified in step 1:

git -C <clone-directory> switch main
git -C <clone-directory> pull --ff-only
pnpm -C <clone-directory> install
pnpm -C <clone-directory> build
cd <clone-directory>
pnpm link --global
palabre --version

Before 0.17.0, palabre update only displays instructions, and --check does not exist. If Git refuses the update (local changes, a different branch), stop and examine the situation: do not force anything.

2. Update the tools

For an installation from a clone, follow the clone update instructions above.

First preserve the work you found: review changes, then publish the commits or PR you want to resume. For work kept in a Relay worktree, follow Retrieve the result. Until then, GitHub does not know about your local changes.

Install operating system updates, then check the installation prerequisites, including Node.js 20 or later. If PALABRE is already installed:

palabre update --check
palabre update

The first command checks without updating; the second shows the plan and asks for confirmation in the terminal. Depending on the installation, it may update the Git checkout and its dependencies or the global package. If PALABRE is missing, follow Installation. Choose one installation source for each tool.

Update agent CLIs according to how they were installed too. For a native Claude Code installation:

claude update

For Codex installed with npm:

npm install --global @openai/codex

For other installations, use the Claude Code and Codex guides. Close and reopen the terminal, then record paths and versions again.

Check sign-in, then sign in only if needed:

claude auth status
codex login status

claude auth login
codex login

Choose the account and access terms yourself. Being signed in to Desktop does not prove that the CLI is signed in. Do not transfer sign-in files from ~/.claude/ or ~/.codex/; keep the results of these checks on your machine.

3. Recreate or review the configuration

In the project, run:

palabre init

This creates the global configuration and approves the content it has just created. If that file already exists, it keeps it: it does not replace or repair an old configuration. To choose a project-specific configuration, use palabre init --local only if you want that scope.

Review the configuration actually being used, local or global: agent commands, absolute paths, models, export directory and Relay policy. An absolute path from the old machine may be missing here; palabre config --sync-agents deliberately preserves it. Adapt it using advanced configuration, without changing your security settings to make a test pass.

After reviewing an existing file, approve its exact content yourself. For the global configuration, in PowerShell or a POSIX shell:

palabre config --config "$HOME/.palabre/palabre.config.json" --trust-config

For an existing project file:

palabre config --config ./palabre.config.json --trust-config

Only approve the file actually selected; local/global precedence matters on a previously used machine too. An agent must not approve a configuration that grants itself rights on your behalf.

For approvals referring to missing files:

palabre config --prune-trust --dry-run
palabre config --prune-trust

The preview writes nothing. Cleanup requires your keyboard confirmation and creates a timestamped backup. It keeps existing or inaccessible paths; it does not approve any file again. Never copy an approval registry from the old machine.

If your help does not offer --new in palabre relay --help or --prune-trust in palabre config --help, the version being used does not contain this path yet. After palabre update, if the published version still lacks these options, use installation from the source repository to test the changes available on main.

4. Reinstall the skill

To install it for your agents on this machine, across all your projects:

npx skills add JuReyms/Palabre --skill palabre --global

This uses the skills tool, downloads the skill from the repository and lets you select agents. Review the choices before confirming. For a copy-based installation, follow the skill guide and copy the entire folder, including references.

The skills tool has its own Node requirements, which may be higher than PALABRE's. If npx reports EBADENGINE, update Node to meet those requirements or use copy-based installation.

An installed copy is not updated by palabre update: explicitly reinstall or copy it again after the skill changes. Check that only one version remains active for each agent, then open a new conversation so it can discover the skill.

5. Check with doctor

From the project:

palabre doctor --terminal

Follow the displayed diagnostics. Today, doctor checks the configuration and tool availability, among other things; it may contact configured Ollama servers. It does not certify agent sign-in, skill installation or freshness, or the absence of duplicates. An old readable configuration can therefore pass this check without being suitable for the new machine.

6. Find the project and create a new teammate

Resume the preserved clone, or clone your repository from its GitHub URL into a new directory. Read README, AGENTS.md, issues and PRs: they describe completed work, what remains and decisions needed. Prepare a short brief with those links, without a local conversation identifier.

From a new conversation with your agent, say for example:

Use PALABRE to ask Codex to review docs/plan.md without changing any files. Create a new teammate and keep its identifier for follow-up.

Or, from the project terminal:

palabre relay --new --to codex --subject "Resume fictional project Orion" "Read README.md and docs/plan.md. Summarize what still needs checking, without changing any files." --json

For a Claude teammate, replace codex with your configured Claude agent name. This first call uses its account and model and may consume its quota. Desktop paths and platform limitations are detailed in Your first Relay.

PALABRE does not transfer conversations from the old machine. An old identifier is not a new local target. --new returns a new identifier in to.session, with cwd and the delivery result; keep it locally for further exchanges. Check status, reply and evidence before continuing. No automatic resend after failure or unknown delivery.

What to keep, recreate or leave local

~ means your personal directory. .palabre/ is relative to the directory from which you run PALABRE, usually the project. If you run it from your personal directory, that path may therefore be ~/.palabre/. outputDir can select a different location for exports.

Cleanup is a separate step, after verifying the new setup. This guide never asks you to delete all of .palabre/.