Codex Settings Sync

Use this skill when the goal is to share Codex state across machines by moving ~/.codex into Agent Filesystem, then mounting that same Redis-backed volume on other computers.

Default stance

Recommend a root ~/.codex/.afsignore before migration.
Default to excluding worktrees/.
Treat cache/, tmp/, logs/, *.log, *.tmp, *.pid, and *.sock as good default exclusions.
If the user appears to care about restoring local checkout state inside Codex, call out worktrees/ as a choice point before migrating.

Open the bundled starter ignore file at assets/.afsignore and adapt it to the user's needs.

Migration workflow

Ask the user to stop Codex on the machines involved, or verify that it is already closed.
Ensure agent-filesystem is built with make.
Configure afs to point at the shared Redis instance.
Create or update ~/.codex/.afsignore before migration.
On the source machine, run ./afs ws import --mount-at-source .codex ~/.codex.
Explain that the imported workspace is mounted at ~/.codex, and the workspace name is .codex.
On each additional machine, move aside any existing ~/.codex, choose mount mode with ./afs config set --mode mount if you want a live mount there, then run ./afs ws mount .codex ~/.codex.
Verify with ./afs status and ls -la ~/.codex.

Secondary machine config

Point the CLI at the same control plane or Redis database. Then run ./afs config set --mode mount for live mount mode, or ./afs config set --mode sync for sync mode, before mounting .codex at that machine's ~/.codex.

Notes to surface

afs ws import honors ~/.codex/.afsignore if present.
.afsignore uses .gitignore-style pattern syntax.
Excluding a directory like worktrees/ is usually safer than syncing it.
Avoid using the same shared ~/.codex from multiple active computers at the same time.
Keep any .local-backup directories until the setup is stable.

Rollback

Source machine rollback:

./afs ws unmount ~/.codex

Secondary machine rollback:

./afs ws unmount ~/.codex
rm -rf ~/.codex
mv ~/.codex.local-backup ~/.codex