Skip to main content

Adapters

Adapters translate between a runtime's native configuration format and AgentMesh's canonical entity model.

Bundled adapters (v0.1)​

AdapterRuntimeReads / writes
claudeClaude Code.claude/skills/, .claude/agents/, CLAUDE.md
codexCodex.codex/skills/, .codex/agents/, AGENTS.md

Both adapters support all three v0.1 entity types: instructions:root, skill, subagent.

How adapters run​

In v0.1, bundled adapters execute inside the same binary via a hidden mode:

agentmesh __adapter claude --stdio # internal — not for direct use

The core communicates with adapters via JSON-RPC over stdio (similar to LSP/MCP). Hot-path operations use in-process Rust calls; cold-path fan-out uses JSON-RPC.

External third-party adapters and a TypeScript SDK are planned for v0.2.

Format translation example​

Subagents illustrate why adapters matter:

LocationFormat
.ai/subagents/code-reviewer.mdMarkdown (canonical)
.claude/agents/code-reviewer.mdMarkdown
.codex/agents/code-reviewer.tomlTOML

The Codex adapter handles Markdown ↔ TOML translation. The lockfile tracks separate emitted_native_sha256 hashes per location so the watcher can suppress self-writes correctly.

Hook installation per adapter​

RuntimeHook fileEvent
Claude Code.claude/settings.local.jsonPostToolUse on Edit|Write|MultiEdit
Codex.codex/hooks.jsonPostToolUse with regex matcher

Hook commands use an absolute pinned binary path (not $PATH resolution) for integrity verification. Each developer's path differs; overlay files are not committed.

Codex trust requirement​

Codex requires manual trust approval for user-installed command hooks. After init or install --runtime codex, approve the hook on your first Codex tool call. Until approved, sync falls back to the watcher and manual agentmesh sync.

Capability mismatch​

When an adapter cannot represent part of an entity, AgentMesh warns and skips the incompatible portion rather than failing the entire sync. Surface skipped capabilities in:

agentmesh doctor

Set ci.fail_on_capability_skip: true in CI to treat skips as hard errors.

Auto-onboarding vs hook install​

When a new runtime folder appears after init:

StepAutomatic?Command
Import entitiesYes (silent)—
Emit to other runtimesYes (silent)—
Install hooksNo (explicit)agentmesh install --runtime <name>

Check agentmesh status for pending hook install banners.

Future adapters (v0.2+)​

Cursor, Copilot, Gemini CLI, and Windsurf adapters are planned. External adapter loading and @agentmesh/adapter-sdk arrive in v0.2.