dotagents

dotagents

Use the root CLI tool. This skill is specific to the ~/Workspace/dotagents repo and its managed symlink surface.

Commands

From the repo root:

go install ./cmd/dotagents                  # install to Go bin dir
dotagents setup                             # first-time machine setup
dotagents status                            # show sync state
dotagents sync                              # sync skill symlinks
dotagents pull                              # git pull + sync (for cron)
dotagents cron --interval 30m               # install auto-pull crontab
dotagents cron --remove                     # remove crontab entry
dotagents mcp list                          # list canonical managed MCPs
dotagents mcp add local --command uvx --arg pkg@latest
dotagents mcp import claude-code local
dotagents mcp remove local

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

Limit a run to specific agents:

dotagents sync --agents=claude-code,hermes

Subcommands

setup

First-time setup on a new machine. Does three things:

1. Creates ~/.agents symlink pointing at the repo root.
2. Patches detected primary agent configs to load shared dotagents config where needed (Hermes: adds skills.external_dirs in config.yaml).
3. Runs sync for managed skills, managed MCP entries, and supported hook entries.

Amp compatibility note: Amp support remains in the CLI for explicit local configs, migration, and cleanup, but Amp is no longer a canonical dotagents.yaml target. Do not add Amp to managed plugin/MCP/skill targets unless the user explicitly asks for that one-off integration.

Important Hermes note: Hermes should consume dotagents skills primarily via skills.external_dirs: ["~/.agents/skills"], not by mirroring repo skills into ~/.hermes/skills. Hermes already ships a bundled categorized skill tree under ~/.hermes/skills, so symlinking repo skills there can collide with bundled category directories. Example: a repo skill named research conflicts with Hermes' builtin research/ category. Prefer Hermes-native bundled skills when an equivalent already exists there. Example: use Hermes' builtin google-workspace skill instead of trying to override it from dotagents. Treat external_dirs as the canonical Hermes integration path.

When a dotagents skill overlaps with a Hermes builtin skill, prefer the Hermes builtin and let the external dotagents copy exist only for other agents. Current example: the shared skills/gws/ skill now has frontmatter name google-workspace, but on Hermes the builtin google-workspace skill should win and no extra sync action is needed.

status

Reports sync state for each detected agent. Agents whose binary is not on PATH show "not detected" and are skipped. The report covers managed skills, native roles, MCP entries, and supported hook entries declared in dotagents.yaml.

sync

Creates, updates, or removes skill symlinks in each detected primary agent's skill root for agents that use managed mirrors. Non-repo skills are reported as external and left untouched. Hermes is special-cased: sync verifies its config-driven shared-skill integration and does not mirror repo skills into ~/.hermes/skills.

For external skills (declared under external_skills in dotagents.yaml), sync clones or updates the remote git repos into ~/.agents/external/<repo-name>/, discovers skills under the configured skill_dir, and symlinks them into agent skill roots alongside local skills.

For MCPs, sync patches only the managed server entries declared in dotagents.yaml and leaves unrelated MCP servers alone. Use dotagents mcp add or dotagents mcp import to update canonical dotagents.yaml, then run dotagents sync to distribute those MCPs to supported agents. If --agents is omitted, new/imported MCPs target the configured primary agents with MCP support (claude-code, codex, hermes, droid, pi). import redacts native env values into ${KEY} references (preserving existing ${SOME_VAR} references); fill those values through environment variables or local native config as appropriate. list shows env key ***** only; it does not print env values. remove deletes only the canonical entry and does not remove native agent config entries.

For hooks, sync patches only managed hook entries declared in dotagents.yaml for agents with verified hook config support. It manages Claude Code hooks in ~/.claude/settings.json, Codex hooks in ~/.codex/hooks.json plus [features].hooks = true, Factory Droid hooks in ~/.factory/settings.json, and Hermes hooks in ~/.hermes/config.yaml. It reports unsupported hook targets without failing. Hook approval is not automated; first-use approval and reapproval after script changes remain host-local user actions.

For repo-owned local MCP servers, prefer mcp/<server-name>/ plus a canonical dotagents.yaml entry using sh -lc 'exec ...', with local secrets/state outside git.

dotagents mcp list
dotagents mcp add local --command uvx --arg pkg@latest --env KEY=value
dotagents mcp import claude-code local --agents=codex,hermes,droid,pi
dotagents sync
dotagents mcp remove local

pull

Runs git pull --ff-only in the repo root, then sync. Designed to be called from cron for auto-sync on remote machines.

cron

Installs or removes a crontab entry that runs pull on a schedule. Default interval is 30m. Options: 5m, 15m, 30m, 1h, 6h, 12h, daily.

promote

Promotes a Hermes skill to dotagents shared skills. Copies the skill, creates a branch, commits, pushes, and opens a PR.

dotagents promote SKILL_NAME          # by name (searches ~/.hermes/skills/)
dotagents promote <category>/<name>   # with category prefix
dotagents promote <name> --dry-run    # copy only, skip git/PR

The skill is searched in ~/.hermes/skills/ by name (including inside category subdirectories). The promote command:

1. Copies the skill to skills/<name>/
2. Creates branch promote/<name>
3. Commits as "add skill"
4. Pushes and creates a PR via gh

Requires gh CLI authenticated with push access to the repo.

For the full promotion workflow (evaluation, pr-triage, merge), use the skill-promote Hermes skill.

dogfood

End-to-end self-test: runs sync, then status, then doctor. Fails on any drift, conflict, or doctor warning. Use after making changes to skills or config to verify the full pipeline.

dotagents dogfood

What it manages

• Fixes ~/.agents if it should point at the repo root and is missing or drifted.
• Configures Hermes to load skills from ~/.agents/skills through ~/.hermes/config.yaml when Hermes is a configured target.
• Links Droid global instructions: ~/.factory/AGENTS.md -> ~/.agents/AGENTS.md (real files conflict).
• Detects agents by checking if their binary is on PATH (detect field in config).
• Treats repo skills under skills/ as the managed set for each detected agent.
• Treats repo hooks under hooks/, memory hooks under memory/hooks/, and skill hook entrypoints as managed only when declared in dotagents.yaml.
• Renders canonical repo roles under agents/*.yaml to each detected agent's native agent_root format where supported:
  • Claude Code: ~/.claude/agents/<name>.md
  • Codex: ~/.codex/agents/<name>.toml
  • Factory Droid: ~/.factory/droids/<name>.md
• Stops on conflicts when a native agent file with the same name already exists and was not generated by dotagents.
• Reports non-repo skills already present in agent skill roots as external and leaves them untouched.
• Stops on conflicts when a managed skill path exists as a real file or directory instead of a symlink.

Root instruction shims

Keep AGENTS.md canonical. CLAUDE.md points agents to it. Droid uses the same canonical file through ~/.factory/AGENTS.md -> ~/.agents/AGENTS.md; deleting ~/.factory/AGENTS.md does not make Droid discover ~/.agents/AGENTS.md.

readlink ~/.agents
cmp -s CLAUDE.md ~/.agents/CLAUDE.md && echo "CLAUDE.md visible via ~/.agents"

Memory sync

The dotagents repo also owns the agent memory ↔ knowledge vault sync pipeline at ~/.agents/memory/. This is separate from skill/MCP sync but lives in the same repo.

Hook scripts:

• hooks/session-end.sh: Appends a session digest to $KNOWLEDGE_DIR/sessions/YYYY-MM-DD.md and reindexes memsearch. Dispatches on hook payload shape for Claude Code, Droid, and Hermes.
• hooks/sync.sh -> lib/sync.py: Bidirectional sync between Hermes built-in memory files (~/.hermes/memories/) and the knowledge vault ($KNOWLEDGE_DIR). Three modes: memory-to-vault, vault-to-memory, both.
• hooks/session-start.sh and hooks/stop.sh: Claude Code memory hook shims when the memsearch Claude plugin is available.

The typical Hermes hook pipeline:

on_session_finalize:
  - command: ~/.agents/memory/hooks/session-end.sh
    timeout: 30
  - command: ~/.agents/memory/hooks/sync.sh
    args:
    - memory-to-vault
    timeout: 15

Hook approval: first-use consent requires a TTY prompt. Scripts modified after approval require revoke + re-approve via hermes hooks revoke <command> then approve at the next session-end TTY prompt. Cannot be automated from CLI.

Hook health pitfall: hermes hooks doctor requires hook stdout to be valid JSON. Plain-text sync wrapper output can be allowlisted/executable but still fail doctor with stdout was not valid JSON; fix the wrapper contract only when ready to re-approve the modified script in a TTY.

For detailed pitfalls (char limits, silent sync failures, hook debugging, JSON stdout requirements, and re-approval after wrapper changes), see references/memory-sync.md.

The knowledge-sync tool source lives at memory/tools/knowledge-sync/. See its README for build and install instructions.

MCP support

dotagents can also manage selected MCP server parity across agents without symlinking whole config files.

Current managed MCP set lives in root dotagents.yaml under mcp_servers:. Minimal examples in this repo:

• linkedin -> uvx linkedin-scraper-mcp==4.13.2
• tavily -> npx -y [email protected] https://mcp.tavily.com/mcp

Status and sync rules:

• dotagents status reports mcp managed, mcp missing, and mcp drifted alongside skills.
• dotagents sync patches only the managed MCP entries for each supported agent.
• Unrelated MCP servers remain untouched.

Per-agent targets:

• Claude Code: ~/.claude.json -> mcpServers.<name>
• Codex: ~/.codex/config.toml -> [mcp_servers.<name>]
• Hermes: ~/.hermes/config.yaml -> mcp_servers.<name>
• Factory Droid: ~/.factory/mcp.json -> mcpServers.<name>
• Pi: ~/.omp/agent/mcp.json -> mcpServers.<name>

Do not symlink whole agent config files. Use targeted patches only. Droid MCP config is patched in-place at ~/.factory/mcp.json; it is not symlinked.

Config

Default targets live in:

dotagents.yaml

Use --agents only as a one-run override.