Skip to main content

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)​

TypeDescriptionCanonical locationRuntime examples
instructions:rootProject-wide instructionsAGENTS.md at repo rootCLAUDE.md
skillNamed capability with prompt + metadata.ai/skills/<name>/SKILL.md.claude/skills/, .codex/skills/
subagentSpecialized 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 pathEntity ID
.claude/skills/security-review/SKILL.mdskill:security-review
.codex/agents/code-reviewer.tomlsubagent:code-reviewer
AGENTS.mdinstructions: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+​

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

Learn more​