Troubleshooting

Start with agentsync doctor — it checks PATH, home/state writability, the config schema, and the secrets backend in one pass. The scenarios below cover the rest.

Common scenarios

First apply backed up a pile of files

Expected on a populated machine. agentsync sees pre-existing native config it didn’t write and treats each as a foreign-collision: it backs the file up to ~/.agentsync/.state/backups/<ts>/ before writing. Nothing is lost. Run agentsync apply --dry-run first to preview which files will be backed up.

One-time backup churn after upgrading

State keys are now stored ${HOME}-relative (portable) instead of absolute. If you ran a pre-portability build, the first apply after upgrading won’t recognize the old absolute-path entries, so every managed destination is treated as a foreign-collision once: current content is backed up, then re-owned. This is expected, non-destructive, and self-heals after that single apply.

`${secret:foo}` not resolving

Confirm the key exists in the decrypted vault:

agentsync secret get foo

age library errors (missing identity, wrong recipient, bad permissions) surface here too.

`plugin outdated` can’t fetch a marketplace

Sanity-check the URL:

git ls-remote <marketplace-url>

agentsync uses go-git and falls back to system git for sparse clones if needed.

Which agents can I `agent add`?

All 32 agents, ten deep adapters (claude, opencode, codex, grok, cursor, gemini, continue, windsurf, roo, cline) plus a 22-agent breadth tier (run agentsync agent list --all) — have real adapters and register normally. (AGENTSYNC_ALLOW_UNIMPLEMENTED=1 exists only for a hypothetical future agent registered as a no-op; none is today.)

Documented trade-offs

These are deliberate, not regressions.

Owned-key hand-edits have no backup

If you hand-edit a key agentsync already owns in a shared file (e.g. an MCP entry in ~/.claude.json that agentsync wrote), the next apply overwrites it with no foreign-collision backup — agentsync considers it its own.

Comment preservation

Comments in mcp/*.toml and in agent-side opencode.json are not preserved across a reconcile write-back or import in the rewritten section. Comments in unrelated sections survive. Deferred to a later release.

Insecure plugin / marketplace sources

http:// and git:// sources are rejected by default to prevent a MITM swap. Override for internal mirrors only:

AGENTSYNC_ALLOW_INSECURE_URLS=1 agentsync plugin outdated

Symlinked destinations

Rejected by default — a rename onto the path would replace the symlink with a regular file and strand your linked source. To write through the link (update the underlying file in place, keeping the link):

AGENTSYNC_ALLOW_SYMLINK_DEST=1 agentsync apply

The same switch governs how agentsync reads a symlinked whole-file destination (a CLAUDE.md, a skill, a subagent), so apply, status, diff, reconcile and explain all need it. Without it, agentsync status reports the file as drift on every run even right after an apply, and agentsync diff prints a symlink hunk instead of a content diff — that is the same refusal, seen from the read side. With it, status, diff, reconcile and explain resolve the link and compare the file it points at. (A key-merged file such as ~/.claude.json is read through the link either way.)

AGENTSYNC_ALLOW_SYMLINK_DEST=1 agentsync status

OpenCode hooks aren’t auto-translated

OpenCode hooks are JS/TS plugins, not declarative shell commands. agentsync does not auto-translate Claude hooks to OpenCode — hand-author a small JS/TS plugin if you need one. You’ll see the hook reported as skipped for OpenCode.

LSP projection

LSP projection is deferred in v1. Claude Code reads LSP servers from plugin manifests rather than settings.json, and agentsync does not synthesize Claude plugins yet; other adapters have no native LSP config target. You’ll see lsp server X skipped in the report.