Frequently Asked Questions

What is AgentMesh?

AgentMesh is an open-source Rust CLI that synchronizes project-level AI runtime context — instructions, skills, and subagents — across coding tools like Claude Code and Codex. It keeps a canonical model in .ai/ and AGENTS.md, then propagates changes bidirectionally to each runtime's native folders.

Which AI coding runtimes does AgentMesh support in v0.1?

v0.1 ships bundled adapters for Claude Code and Codex only. Cursor, Copilot, Gemini CLI, and Windsurf are planned for v0.2.

How do I install AgentMesh today?

Install with the official curl script:

curl -fsSL https://agentmesh.sh/install.sh | sh

See Install with the official script (curl on macOS/Linux, PowerShell on Windows). Contributors can build from source.

Do I need to run AgentMesh manually every time I edit config files?

No. Runtime hooks trigger sync automatically after tool calls that write files. A per-repo watcher daemon catches direct edits, git operations, and other cases hooks miss. Use agentmesh sync only when you want to force a pass manually.

What should teammates do after cloning a repo with AgentMesh?

1. Install AgentMesh on their machine
2. Run agentmesh init in the repo (installs machine-local hooks)
3. Run agentmesh doctor to verify
4. If using Codex, approve the hook trust prompt on first Codex tool call

They should not commit .claude/settings.local.json or .codex/hooks.json — each machine has its own binary path. See Repository Setup.

Why isn't Codex sync working after init?

Codex requires you to review and trust new command hooks before they run. On your first Codex tool call after install, approve the trust prompt for the AgentMesh hook. Until then, sync still works via the watcher daemon, manual agentmesh sync, and optional git pre-commit hooks — but Codex's PostToolUse hook will not fire.

Also verify .codex/hooks.json is gitignored and contains your machine's absolute binary path.

I added .codex/ after init — do I need to do anything?

AgentMesh auto-onboards Codex entities silently (import + emit), but does not install hooks automatically. Run:

agentmesh install --runtime codex

Check agentmesh status for a pending-install banner.

What should I do if agentmesh.lock has a git merge conflict?

agentmesh reconcile-lock
git diff agentmesh.lock    # review
git add agentmesh.lock && git commit

Do not hand-edit the lockfile.

AgentMesh auto-resolved a conflict — how do I recover the other version?

Run agentmesh doctor to see pending conflicts and recovery commands:

agentmesh restore skill:security-review --from codex   # restore losing version
agentmesh ack skill:security-review                    # keep current, clear flag

Losing versions are preserved in ~/.cache/agentmesh/<repo-hash>/conflicts/.

doctor reports an integrity check failure — what now?

This means the binary path or sha256 in your hook entries does not match the running AgentMesh binary — common after upgrading or moving the binary. Run:

agentmesh upgrade
agentmesh doctor

How do I stop or remove AgentMesh?

To temporarily stop AgentMesh for one repository while keeping shared state:

agentmesh stop
agentmesh start   # restore local hooks later

To remove AgentMesh-owned state from one repository:

agentmesh uninstall

This removes hooks, watcher state, agentmesh.lock, .ai/, and agentmesh.config.yaml. It does not delete runtime files such as AGENTS.md or CLAUDE.md.

To remove AgentMesh from the computer as well:

agentmesh uninstall --full -y

Each teammate runs these commands independently on their own machine.

Do I need agentmesh.config.yaml?

No. A project with no config file runs full bidirectional sync for every detected runtime with sensible defaults. Add config only to override behavior — see Configuration.