Skip to main content

Repository Setup

This guide covers what AgentMesh adds to a repository, what to commit, and how teammates get set up after cloning.

Repository layout after init​

your-repo/
├── AGENTS.md                      # canonical project instructions (committed)
├── CLAUDE.md                      # emitted from AGENTS.md (committed)
├── agentmesh.lock                 # resolved sync state (committed)
├── agentmesh.config.yaml          # optional overrides (committed, if present)
├── .ai/                           # canonical skills & subagents (committed)
│   ├── skills/
│   │   └── security-review/
│   │       └── SKILL.md
│   └── subagents/
│       └── code-reviewer.md
├── .claude/                       # Claude runtime view (committed files)
│   ├── settings.json              # user-owned — AgentMesh never writes here
│   ├── settings.local.json        # gitignored — AgentMesh hook (per machine)
│   ├── skills/
│   └── agents/
└── .codex/                        # Codex runtime view (committed files)
    ├── config.toml                # user-owned — AgentMesh never writes here
    ├── hooks.json                 # gitignored (recommended) — AgentMesh hook
    ├── skills/
    └── agents/

What to commit​

PathCommit?Why
AGENTS.md, CLAUDE.mdYesShared project instructions
.ai/YesCanonical skills and subagents
agentmesh.lockYesTeammates need the same resolved entity registry
agentmesh.config.yamlYes (if present)Shared sync intent
.claude/skills/, .claude/agents/YesRuntime-specific emitted views
.codex/skills/, .codex/agents/YesRuntime-specific emitted views
.claude/settings.local.jsonNoContains your machine's absolute binary path
.codex/hooks.jsonNoContains your machine's absolute binary path

AgentMesh does not modify your .gitignore. Add:

# AgentMesh — machine-local hook files
.codex/hooks.json

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

agentmesh doctor warns if .codex/hooks.json appears to be tracked by git.

Teammate onboarding​

When a teammate clones a repo with AgentMesh already initialized:

1. Install AgentMesh​

Install with curl on their machine.

2. Run init​

cd the-repo
agentmesh init

If agentmesh.lock already exists, init is idempotent — it installs machine-local hooks pointing to the teammate's binary path and reports "nothing to do" for canonical state that is already set up.

3. Trust Codex hooks (if using Codex)​

Each developer must approve the Codex hook trust prompt on their first Codex tool call after install.

4. Verify​

agentmesh status
agentmesh doctor

Adding a runtime later​

If a repo started Claude-only and someone later adds .codex/:

  1. AgentMesh auto-onboards Codex entities silently (imports + emits)
  2. Hooks are not installed automatically — run explicitly:
agentmesh install --runtime codex

Check agentmesh status for a pending-install banner when hooks are missing.

Optional: git pre-commit safety net​

Install a pre-commit hook that refuses to commit if sync would change canonical state:

agentmesh install --git-pre-commit

This chains with existing pre-commit scripts (pre-commit, husky, lefthook) when possible. Use --force only if you understand the consequences.

Stopping AgentMesh for a repo​

Temporarily stop AgentMesh for this repository only:

agentmesh stop

This stops the watcher, removes AgentMesh-owned hooks, and clears machine-local state for this repo. It keeps agentmesh.lock, .ai/, agentmesh.config.yaml, and runtime files such as AGENTS.md and CLAUDE.md.

Start it again later with:

agentmesh start

Uninstalling from a repo​

Remove AgentMesh-owned state from this repository:

agentmesh uninstall

This runs the same cleanup as agentmesh stop, then deletes agentmesh.lock, .ai/, and agentmesh.config.yaml. It never deletes runtime files such as AGENTS.md or CLAUDE.md.

Remove AgentMesh from the computer as well:

agentmesh uninstall --full -y

Each teammate runs stop, start, or uninstall on their own machine independently.