Core Concepts

AgentMesh is a synchronization layer for AI coding runtimes — not an inference proxy, prompt manager, or hosted service.

The canonical model

AgentMesh translates between runtime-specific formats through a shared canonical model:

.claude/skills/foo/  ←→  .ai/skills/foo/  ←→  .codex/skills/foo/
CLAUDE.md            ←→  AGENTS.md        ←→  (Codex instructions)

Adapters never read each other's native formats directly. The core knows about canonical entities; each adapter translates to and from its runtime.

Entity types (v0.1)

Type	Description	Canonical location	Runtime examples
instructions:root	Project-wide instructions	AGENTS.md at repo root	CLAUDE.md
skill	Named capability with prompt + metadata	.ai/skills/<name>/SKILL.md	.claude/skills/, .codex/skills/
subagent	Specialized agent for delegated tasks	.ai/subagents/<name>.md	.claude/agents/*.md, .codex/agents/*.toml

Why AGENTS.md?

AgentMesh reinforces the emerging AGENTS.md cross-runtime convention rather than inventing a parallel canonical file. Benefits:

• Already used by Codex and other tools
• Visible at the repo root to all contributors
• A repo with only AGENTS.md (no AgentMesh) is valid — adding AgentMesh later just enables bidirectional sync to CLAUDE.md

Editing AGENTS.md propagates to every connected runtime. Editing CLAUDE.md propagates back to AGENTS.md. Both directions are bidirectional.

Pristine user files

Files you edit contain no AgentMesh metadata — no marker comments, no agentmesh: frontmatter blocks. A skill copied out of .ai/ into another project without AgentMesh installed is still a valid Claude or Codex skill.

AgentMesh state lives elsewhere:

• agentmesh.lock — committed; entity IDs, hashes, provenance, conflict flags
• ~/.cache/agentmesh/<repo-hash>/ — machine-local; integrity pins, hook ownership, watcher state, conflict archives

Shared frontmatter vocabulary

Skills and subagents use a small common frontmatter vocabulary:

---
name: security-review
description: Audit code for OWASP top-10 vulnerabilities
allowed-tools: [Read, Grep, Bash]
model: claude-opus-4-7
---

Runtime-specific keys (e.g., Codex's reasoning_effort) pass through unchanged. Adapters that do not recognize a field ignore it at runtime but preserve it on round-trip.

Identity without markers

Entity IDs are derived from paths on first encounter:

First-seen path	Entity ID
.claude/skills/security-review/SKILL.md	skill:security-review
.codex/agents/code-reviewer.toml	subagent:code-reviewer
AGENTS.md	instructions:root

The same skill in both .claude/ and .codex/ is recognized as one entity. Renames are detected via content-hash similarity (default threshold: 0.80).

Project scope only (v0.1)

v0.1 syncs per-repository project config only. Personal global config (~/.claude/, ~/.codex/) is deferred to v0.2.

Deferred to v0.2+

Feature	Release
Cursor, Copilot, Gemini adapters	v0.2
Scoped instructions (instructions:scoped:<name>)	v0.2
External third-party adapters + TypeScript SDK	v0.2
Personal-mesh (~/.claude/ sync)	v0.2
rule, hook, slash_command entity types	v0.2+

Learn more

• Sync Engine — how changes propagate
• Adapters — Claude and Codex translation
• Lockfile and State — agentmesh.lock and cache layout