spec

dotagents

Cross-agent sync CLI for managing shared skills, agent roles, and MCP servers across the primary coding-agent stack: Claude Code, Codex, Factory Droid, Hermes, and Pi/OMP. Amp, OpenClaw, OpenCode, and similar non-primary harnesses are compatibility-only unless explicitly configured.

This repo is the canonical ~/.agents layer. It detects installed agent platforms, syncs shared skills and MCP entries to each platform's native format, validates drift, and self-tests.

Open the full harness map.

Agent instructions

AGENTS.md is the canonical instruction file. CLAUDE.md is only a compatibility shim for agents that look for Claude-style project memory.

Install

Two ways to consume this repo - pick exactly one per machine and harness:

You want	Do this
Just the skills in Claude Code	/plugin marketplace add yourconscience/dotagents then /plugin install dotagents@yourconscience
Just the skills in Codex	codex plugin marketplace add https://github.com/yourconscience/dotagents then codex plugin add dotagents@yourconscience
The full managed setup (skills, roles, MCP, hooks) on any supported harness - Claude Code, Codex, Hermes, Factory Droid, Pi/OMP	Install the dotagents CLI (below), clone the repo, run dotagents setup

Plugins snapshot the repo at install time and update through each harness's plugin update flow. dotagents sync keeps live symlinks instead. Do not combine both on the same harness or skills appear twice; see "Installing this repo as a plugin" for details and how delivery: arbitrates this for Claude Code.

CLI install

Prebuilt binaries for macOS and Linux (amd64/arm64) are attached to GitHub Releases. With Go installed:

go install github.com/yourconscience/dotagents/cmd/dotagents@latest

Or from a clone:

go install ./cmd/dotagents

Ensure the Go install directory is on PATH. If go env GOBIN is non-empty, add that directory; otherwise add $(go env GOPATH)/bin.

After that, run first-time machine setup (creates ~/.agents, patches detected agent configs, syncs), or inspect state directly:

dotagents setup
dotagents status
dotagents deps check

Releases are cut by pushing a v* tag; CI runs GoReleaser, which builds the archives and publishes the GitHub Release.

Alternatives

How dotagents compares to other cross-agent config sync tools:

	dotagents	skillshare	vsync	agents-cli
Skills sync	yes (symlinks + config-driven dirs)	yes	yes	yes
MCP sync	yes	no	yes	yes
Hooks sync	yes (Claude Code, Codex, Hermes, Droid)	no	no	no
Native subagent roles	yes (Claude Code, Codex, Droid)	agents as files	yes	no
Plugin catalog	yes (first-party dotagents.yaml entries)	no	no	no
External skill pinning	yes (dotagents.lock)	version tracking	no	no
Skill security audit	yes (dotagents doctor)	yes	no	no
Local private overlay	yes (dotagents.local.yaml)	no	no	no
Target agents	Claude Code, Codex, Amp, Hermes, Factory Droid, Pi/OpenClaw	Claude Code, Codex, Cursor, Gemini, 60+	Claude Code, Cursor, OpenCode, Codex	Codex, Claude Code, Gemini CLI, Cursor, Copilot, others
Language	Go	Go	TypeScript	TypeScript

dotagents focuses on the post-IDE agent stack (Hermes, Amp, Droid, OpenClaw/Pi alongside Claude Code and Codex) and on syncing the full surface - skills, MCP, hooks, roles, plugins, root instructions - from one canonical ~/.agents layer.

Agents

Reusable agent role definitions for agent-native subagents. Canonical roles live in agents/*.yaml; dotagents sync renders them to each configured native format:

• Claude Code: ~/.claude/agents/<name>.md

• Codex: ~/.codex/agents/<name>.toml

• Factory Droid: ~/.factory/droids/<name>.md

• architect - designs system architecture, telemetry schemas, and technical plans. Sonnet, read + write.

• builder - implements code changes following specs or architect designs. Sonnet, read + write.

• researcher - investigates codebases, APIs, repos, and web sources. Sonnet, read + write + web.

• reviewer - reviews code against specs, finds bugs and security issues. Sonnet, read-only.

Reference these from TeamCreate teammates, Claude Code subagent types, or Codex native subagent roles. See skills/spawn/SKILL.md for usage patterns.

Skills

Grouped by category, with the execution surface each skill drives. See docs/reports/skill-categorization.md for the full analysis.

Orchestration and delegation: