FAQ
Does agentsync sync my config across machines?
Section titled “Does agentsync sync my config across machines?”No — it’s deliberately single-machine. It manages one machine’s agents from one canonical directory. To carry that directory across machines, use a dotfile manager like chezmoi. See Cross-machine sync.
Will agentsync overwrite changes an agent made to its own config?
Section titled “Will agentsync overwrite changes an agent made to its own config?”Not behind your back. agentsync records a hash of everything it writes. If a native
file changes, that’s drift — status and diff show it, and reconcile lets
you adopt the edit or re-impose your source. The one exception is hand-edits to a
key agentsync already owns in a shared file: run reconcile before the next
apply to capture those. See Troubleshooting.
Can a secret leak into my committed dotfiles?
Section titled “Can a secret leak into my committed dotfiles?”The architecture makes that extremely hard. Resolved cleartext secrets are a distinct type the source writers literally cannot accept (a compile error), all write-backs funnel through one re-referencing path, and a fail-closed backstop refuses to write if a credential would persist. See the security model.
Why is there no background daemon?
Section titled “Why is there no background daemon?”So that apply is fast, offline, and reproducible. update is the only command
that touches the network; everything else reads a local cache. If you want
scheduled refreshes, wire agentsync update --apply --auto-safe into cron,
launchd, or systemd yourself. See Updating from the network.
Why does the same component land differently on each agent?
Section titled “Why does the same component land differently on each agent?”Because the agents genuinely differ. agentsync marks each translation native (✓), projected (◐), or skipped (✗) and prints the choice in the apply report — it refuses to invent a translation that would mislead you. See the capability matrix for the full per-agent breakdown.
Are Codex CLI, Cursor, Gemini CLI, Continue, Windsurf, Roo Code, and Cline supported?
Section titled “Are Codex CLI, Cursor, Gemini CLI, Continue, Windsurf, Roo Code, and Cline supported?”All seven are supported. Codex CLI — MCP (into the TOML
~/.codex/config.toml), memory, skills, subagents (◐), slash commands (◐,
global-only), hooks (◐), and plugin import. Cursor — MCP (.cursor/mcp.json,
the same mcpServers shape as Claude), skills (.cursor/skills/), subagents (◐,
.cursor/agents/), slash commands (◐, plain markdown), and hooks (◐,
.cursor/hooks.json); its user-level rules live in app-local storage, so
memory is project-scope only (the repo-root AGENTS.md). Gemini CLI — MCP
- hooks (◐) in
.gemini/settings.json, memory (GEMINI.md), subagents (◐,.gemini/agents/), and slash commands (◐, TOML in.gemini/commands/); Gemini uses extensions rather than Agent Skills, so skills are skipped. Continue — MCP (.continue/mcpServers/), memory (.continue/rules/), and slash commands (◐,.continue/prompts/), projected as Continue blocks; skills/subagents/hooks have no Continue concept. Windsurf — MCP (~/.codeium/windsurf/mcp_config.json) at user scope only; memory (.windsurf/rules/withtrigger: always_on, globalmemories/global_rules.md) and slash commands (.windsurf/workflows/, globalglobal_workflows/) at both scopes. Roo Code — MCP (.roo/mcp.json, project scope), memory (.roo/rules/), and slash commands (.roo/commands/, keepingdescription+argument-hint) at both scopes; its global MCP is VS Code app-storage (not targeted). Cline — MCP via the CLI’s~/.cline/mcp.json(user scope), memory (.clinerules/) and slash commands (.clinerules/workflows/) at project scope. No LSP concept on any of them.
Beyond these nine deep adapters, a breadth tier of 22 more agents (amp,
goose, qwen, warp, jules, junie, openhands, amazonq, zed, kilocode, kiro, trae,
jetbrains, firebase, antigravity, augmentcode, copilot, copilot-cli, crush,
factory, pi, mistral) is supported via one data-driven generic adapter — memory
for all, MCP wherever the agent reads a JSON server-map agentsync can express,
and Agent Skills wherever the agent natively scans a SKILL.md directory (18 of
the 22) — taking agentsync to 31 agents. See the
capability matrix → Breadth tier.
What about Aider?
Section titled “What about Aider?”Planned — on the roadmap, not yet implemented.
Are my TOML / JSONC comments preserved on a round-trip?
Section titled “Are my TOML / JSONC comments preserved on a round-trip?”Not yet. 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. This is a documented limitation.
Do I need the age CLI?
Section titled “Do I need the age CLI?”Only to generate a keypair (age-keygen). agentsync embeds age for
encryption/decryption itself. See Secrets.