Skip to main content

Configuration

AgentMesh works without any config file on the happy path. Every key in agentmesh.config.yaml is optional.

Create the file at your repository root only when you need to override defaults.

Minimal example​

# agentmesh.config.yaml — all keys optional
version: 1

ci:
  fail_on_conflict: true
  require_clean_lock: true

AgentMesh creates this file only if absent during init — and never modifies it afterward. You are the editor.

Full schema reference​

version: 1

# Per-runtime behavior (v0.1: claude, codex only)
runtimes:
  claude:
    mode: bidirectional # default
  codex:
    mode: bidirectional

# Sync behavior
sync:
  conflict_strategy: auto # v0.1 only option
  rename_similarity_threshold: 0.80
  vcs_throttle_ms: 2000
  ignore:
    - "**/draft/**"

# Watcher daemon
watcher:
  idle_timeout_minutes: 30
  log_level: info # error | warn | info | debug
  debounce_ms: 500

# CI strict mode
ci:
  fail_on_conflict: true
  fail_on_capability_skip: false
  require_clean_lock: true

# Hook installation
hooks:
  claude:
    enabled: true
    matcher_extra: "Bash" # extend Edit|Write|MultiEdit
  codex:
    enabled: true

Keys for v0.2+ runtimes (cursor, copilot, etc.) are parsed but have no effect in v0.1.

Runtime modes​

ModeBehavior
bidirectionalDefault — full sync both directions
mergeBidirectional; extra cautious when writing
read-onlyDetect and report; never write to this runtime
managedAgentMesh owns this runtime's folder
disabledIgnore this runtime even if detected

CI strict mode​

agentmesh sync --check exits non-zero on any state movement by default (exit 1). The ci.* keys add finer-grained exit codes:

KeyDefaultEffect when true
fail_on_conflictfalseExit 2 when conflicts would be auto-resolved
fail_on_capability_skipfalseExit 2 when entities skipped due to capability mismatch
require_clean_lockfalseExplicit alias for "lockfile must not change"

See CI Integration for pipeline examples.

Per-runtime overrides (lockfile)​

Opt-in per-runtime field divergence is recorded in agentmesh.lock, not the config file:

# inside agentmesh.lock — managed by AgentMesh
overrides:
  skill:security-review:
    codex:
      reasoning_effort: high

This keeps user-visible skill files pristine while allowing runtime-specific rendering hints.

Validation​

  • Unknown keys → warning, sync continues (forward compatibility)
  • Invalid values → hard error (exit 5)
  • agentmesh doctor validates config as part of health checks

What's not configurable (v0.1)​

  • Per-entity settings (use lockfile overrides:)
  • User-level config layering (deferred to v0.2)
  • Telemetry (AgentMesh is local-first; nothing to opt out of)