Global setup

Synchronize global instructions and skills across machines with a Git-backed profile.

Global mode is for personal agent context that follows you across machines. Each host keeps a tiny machine config and selects one profile from a shared Source Repository.

1. Create the machine config

Create ~/.agents/agentsmith/config.toml:

source = "~/.agents/agentsmith/source"
profile = "laptop"

source points to a local clone of your context repository. Relative paths resolve from the config file; ~ expands to your home directory.

2. Create a profile

In the Source Repository, create profiles/laptop.toml:

harnesses = ["codex", "claude-code"]
template = "personal"
packs = ["base", "personal", "macos"]
skills_enable = ["review-worktree"]
skills_disable = ["publish"]

The Source Repository also needs an agentsmith.toml root config, the selected template family, packs, and skill sources. See Source Repository layout.

3. Preview and synchronize

asmith global lint
asmith global explain
asmith global diff
asmith global sync

global sync requires a clean Source Repository with an upstream. It runs git pull --ff-only, rebuilds the plan, and writes all global artifacts.

Use asmith global generate when the local source is already current and you only want to regenerate.

Adoption and recovery

Global outputs are protected by hashes stored in ~/.agents/agentsmith/state.toml. An existing file that agentsmith has never recorded is not overwritten by default. Inspect the diff, then use --force once to adopt it:

asmith global diff
asmith global generate --force

--force is available only for global generation and synchronization. Project mode intentionally has no force option.