Adapters
Adapters translate between a runtime's native configuration format and AgentMesh's canonical entity model.
Bundled adapters (v0.1)
| Adapter | Runtime | Reads / writes |
|---|---|---|
claude | Claude Code | .claude/skills/, .claude/agents/, CLAUDE.md |
codex | Codex | .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:
| Location | Format |
|---|---|
.ai/subagents/code-reviewer.md | Markdown (canonical) |
.claude/agents/code-reviewer.md | Markdown |
.codex/agents/code-reviewer.toml | TOML |
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
| Runtime | Hook file | Event |
|---|---|---|
| Claude Code | .claude/settings.local.json | PostToolUse on Edit|Write|MultiEdit |
| Codex | .codex/hooks.json | PostToolUse 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:
| Step | Automatic? | Command |
|---|---|---|
| Import entities | Yes (silent) | — |
| Emit to other runtimes | Yes (silent) | — |
| Install hooks | No (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.
Related
- Repository Setup — gitignore for hook files
- Sync Engine — when adapters are invoked