Skip to main content

Quick Start

This guide walks through installing AgentMesh and setting it up in a git repository. The whole process takes about 10 minutes.

Prerequisites​

  • OS: macOS, Linux, or Windows
  • Git repository at your project root
  • At least one supported runtime present or planned:
    • Claude Code (.claude/ and/or CLAUDE.md)
    • Codex (.codex/ and/or AGENTS.md)

AgentMesh can bootstrap from an empty repo, but the typical case is importing existing Claude or Codex configuration.

Step 1: Install AgentMesh​

macOS / Linux:

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

Windows (PowerShell):

irm https://agentmesh.sh/install.ps1 | iex

Verify the installation:

agentmesh --version

The installer also prints the recommended first repo commands:

agentmesh scan
agentmesh init
agentmesh status

See Install with the official script for upgrade and uninstall options.

Step 2: Initialize AgentMesh​

From your project root, run the one-time setup:

cd /path/to/your/repo
agentmesh init

init scans the repository, then:

  1. Detects Claude and Codex artifacts
  2. Imports existing entities into the canonical .ai/ model
  3. Propagates entities to other detected runtimes
  4. Installs hooks into machine-local overlay files (.claude/settings.local.json, .codex/hooks.json)
  5. Writes agentmesh.lock

If no runtimes are detected, init still sets up the canonical structure for when you add them later.

Preview before init

agentmesh scan shows the same detection output as the first phase of init, but makes no changes. Use it when you want a read-only preview — for example, before running init in a repo you did not set up yourself.

The AGENTS.md vs CLAUDE.md prompt​

If both AGENTS.md and CLAUDE.md exist with different content, init asks which agent memory file to use as the starting version for initial setup:

⚠ Detected divergent project instructions:
    AGENTS.md  (last modified 2026-05-20T14:32:11Z, 3,452 bytes)
    CLAUDE.md  (last modified 2026-05-24T09:11:03Z, 3,612 bytes)
  The agent memory files are different.
  Choose which one AgentMesh should use for the initial setup.
  AgentMesh will sync the other runtime's file from this starting version.

    [1] Use AGENTS.md
    [2] Use CLAUDE.md

  Choice [1 or 2]:

This choice only seeds the initial setup. After setup, sync is bidirectional and later edits can come from either runtime file. For CI or scripts, pass a flag:

agentmesh init --canonical-instructions=AGENTS.md
# or
agentmesh init --canonical-instructions=CLAUDE.md -y

Codex trust prompt​

If Codex is detected, init installs a hook into .codex/hooks.json. Codex requires you to review and trust new command hooks before they run. On your next Codex tool call, Codex will prompt:

Trust the new hook '/Users/you/.local/bin/agentmesh sync --trigger=codex-hook --silent'?

Approve once. Until then, sync still works via the watcher daemon, manual agentmesh sync, and optional git pre-commit hooks — but Codex's PostToolUse hook itself will not fire.

Add these to your .gitignore (AgentMesh does not modify .gitignore for you):

# AgentMesh — machine-local hook files (each developer has their own binary path)
.codex/hooks.json

.claude/settings.local.json is already gitignored by Claude Code's convention.

Step 3: Verify everything works​

agentmesh status    # fast snapshot (under 50ms)
agentmesh doctor    # deep health check

Healthy output ends with ✓ All checks passed.

Test sync manually​

Edit a skill in one runtime, then check the other:

# After editing .claude/skills/security-review/SKILL.md in Claude Code:
agentmesh diff      # preview what would change
agentmesh sync      # force a sync pass (usually automatic via hooks)

Or edit directly and wait — the hook fires after Claude/Codex tool calls that write files.

Step 4: Commit the shared state​

Commit the files teammates need:

git add AGENTS.md .ai/ agentmesh.lock
git commit -m "chore: initialize AgentMesh sync"

Do not commit .claude/settings.local.json or .codex/hooks.json — each teammate runs agentmesh init (or agentmesh install --runtime <name>) on their machine.

See Repository Setup for the full teammate workflow.

Common next steps​

SituationWhat to run
Added .codex/ after init (Claude-only repo)agentmesh install --runtime codex
Want commit-time drift checkagentmesh install --git-pre-commit
Upgraded AgentMesh binaryagentmesh upgrade
CI pipelineagentmesh sync --check — see CI Integration
Something looks wrongagentmesh doctor

Init flags reference​

FlagPurpose
--canonical-instructions=AGENTS.mdNon-interactive: use AGENTS.md as the starting agent memory file during init
--canonical-instructions=CLAUDE.mdNon-interactive: use CLAUDE.md as the starting agent memory file during init
-y, --yesSkip confirmation prompts
--dry-runShow what init would do without writing
--skip-hooksSet up canonical state + lockfile only; add hooks later with install

Next steps​