dotagents

README

dotagents

Dotfiles for your AI agents.

One private ~/.agents git repository holds your skills, MCP servers, hooks, and agent roles. The dotagents CLI syncs each of those into the native format of every coding agent you use — Claude Code, Codex, Factory Droid, Hermes, OpenCode, Pi — and follows you across machines the way dotfiles do. External skills are commit-pinned and audited before any agent loads them.

Overview & comparison → · Releases

Why

If you use more than one coding agent, you maintain the same four things — skills, MCP servers, hooks, subagent roles — in a different place and format for each harness. Copying them by hand drifts within a week. Shell config solved this decades ago with dotfiles: one versioned repo, rendered into place. dotagents applies that pattern to agent config.

Two design choices worth knowing up front:

• User-level, not project-level. Your setup lives in ~/.agents and applies everywhere you work. Tools like rulesync and ruler generate per-project config instead; see How it differs.
• The tool and your config are separate. Installing dotagents never installs anyone else's prompts. Your ~/.agents is yours, private, and versioned by you.

Quick start

Install the CLI (macOS or Linux):

# Prebuilt release binary
curl -fsSL https://raw.githubusercontent.com/yourconscience/dotagents/main/scripts/install.sh | sh

# or via mise
mise use -g github:yourconscience/dotagents

# or with Go
go install github.com/yourconscience/dotagents/cmd/dotagents@latest

Then run:

dotagents setup

setup does everything a first run needs, interactively:

1. Creates ~/.agents if it does not exist and copies in the starter content (two skills, five roles, memory hooks, a minimal dotagents.yaml).
2. Detects which harnesses are installed and records their native paths.
3. Scans each harness for skills, roles, and MCP servers you already have, and offers to import them into ~/.agents — copy-only, originals untouched, name conflicts prompted one by one.
4. Before its first sync touches a harness that already has content, shows exactly what would be removed or overwritten there and asks per harness. Declining keeps that harness's files.
5. Offers to git init the new repository, and runs the first sync.

To carry the same setup to other machines, add a private remote:

cd ~/.agents
git remote add origin <your-private-repository>
git push -u origin main
# on the next machine: clone it to ~/.agents, install dotagents, run dotagents setup

Verify state any time:

dotagents status   # per-harness sync state
dotagents doctor   # health checks: frontmatter, lock pins, audits, hooks

What it syncs

Exactly four surfaces, each rendered into the harness's own format — dotagents does not invent compatibility files a harness cannot consume:

1. Skills — SKILL.md directories, symlinked or copied to each harness's skill root.
2. MCP servers — one YAML entry, rendered into each supported native config (JSON, TOML, or YAML as the harness requires).
3. Hooks — lifecycle hooks registered only where the harness exposes a verified hook surface.
4. Agent roles — Markdown role definitions rendered to native formats (Claude Markdown, Codex TOML, Droid).

Harness	Skills	Roles	MCP	Hooks
Claude Code	yes	yes	yes	yes
Codex	yes	yes	yes	yes
Factory Droid	yes	yes	yes	yes
Hermes	yes	--	yes	yes
OpenCode	yes†	yes	yes	--
Pi*	yes	--*	--*	--

* Vanilla pi is skills-only by design. If you run the OMP fork instead, dotagents detects it separately and additionally manages roles and MCP servers there — the two never conflict.

† OpenCode reads ~/.agents/skills/ natively, so dotagents delivers skills without a mirror when the config root is ~/.agents; a custom config root mirrors into ~/.config/opencode/skills/ like other harnesses. OpenCode's only hook surface is a JS plugin API, so hooks stay unsupported.

Amp and OpenClaw can read the repo's skills through standard conventions but are not managed; a surface gets a "yes" above only after its native behavior is verified end to end.

Working with skills

A skill is a directory under ~/.agents/skills/ containing a SKILL.md with name and description frontmatter (agentskills.io convention). Create one and it appears in every configured harness:

dotagents skill new review-checklist --description "Pre-merge review checklist"
dotagents sync

Already wrote a skill inside one harness? Promote it to canonical so every agent gets it:

dotagents skill promote my-skill        # finds it in a native skill root, copies it under ~/.agents

External skills: pinned, audited

Pulling skills from other people's repos is installing prompt code from strangers — dotagents treats it like a dependency, not a download. Declare a source in dotagents.yaml:

external_skills:
  - url: https://github.com/mattpocock/skills
    branch: main
    skill_dirs: [skills/productivity/grilling]
    materialize: true

• dotagents.lock pins the source to an exact commit; agents only ever see the pinned tree.
• materialize: true copies the selected directories into ~/.agents/skills/<name> so the content is versioned in your repo and diffable on update.
• dotagents skill update [name ...] is the only thing that advances a pin — updates are deliberate, never implicit.
• dotagents doctor scans external sources for risky patterns (exfiltration, shell abuse) and detects drift between the lock and the materialized copies.

MCP servers

Declare once, target the harnesses you want:

mcp_servers:
  - name: tavily
    enabled: true
    command: npx
    args: [-y, mcp-remote@0.1.38, "https://mcp.tavily.com/mcp"]
    agents: [claude-code, codex, hermes, droid]

dotagents mcp list|add|import|remove manages entries from the CLI; import pulls servers you already configured in a harness into the canonical config. Secrets belong in env var references — import refuses literal secrets in command arguments.

Agent roles

A role is a Markdown file in ~/.agents/agents/ with frontmatter (name, description, model, effort, tools, optional per-harness overrides) and the system prompt as body. dotagents renders it into each harness's native format — e.g. TOML for Codex. Five generic starter roles ship with the tool: architect builder researcher reviewer tester. A same-name file in your ~/.agents/agents/ always wins over the starter.

Hooks and memory

Hooks are lifecycle commands (session start/end, stop) registered per harness in dotagents.yaml. dotagents ships a memory integration built on them — pick a tier during setup:

dotagents setup --memory basic      # default
dotagents setup --memory off
dotagents setup --memory memsearch

Tier	Behavior	Dependency
off	no managed memory hooks	none
basic	appends a bounded digest of each session to $KNOWLEDGE_DIR/sessions/YYYY-MM-DD.md and injects recent digests as context at session start	Python 3
memsearch	full-text indexed search over the knowledge vault	memsearch on PATH (uv tool install memsearch)

Memory data lives in your knowledge directory (default ~/Workspace/knowledge, configurable via KNOWLEDGE_DIR), never in the tool repository.

Command reference

dotagents setup    [--memory off|basic|memsearch] [--agents ...]   # first run, import, memory tier, first sync
dotagents status   [--agents ...]                                  # per-harness sync state
dotagents sync     [--pull] [--agents ...]                         # reconcile all harnesses (--pull: git pull first)
dotagents doctor   [--e2e] [--agents ...]                          # health checks and audits
dotagents skill    new|update|promote                              # create, advance pins, canonicalize
dotagents mcp      list|add|import|remove                          # manage MCP entries

dotagents help --all lists maintenance commands and compatibility aliases.

Configuration

~/.agents/dotagents.yaml is the single source of truth. The shipped template is intentionally small — setup fills in detected harnesses:

version: 1
agents: [] # populated by dotagents setup

external_skills:
  - url: https://github.com/mattpocock/skills
    branch: main
    skill_dirs: [skills/productivity/grilling]
    materialize: true

• Config resolution order: --config <path> → $DOTAGENTS_HOME/dotagents.yaml → ~/.agents/dotagents.yaml. dotagents never walks the current project directory looking for config.
• dotagents.local.yaml next to the main config overlays machine-local entries (kept out of git) on top of the shared ones.
• Managed entries are marked as such in native configs; anything dotagents did not create is left untouched.

Public starter content

2 skills ship with this repo:

dotagents grilling

dotagents is the self-management skill (agents can run status/sync/doctor for you). grilling is a live example of a materialized, commit-pinned external skill from mattpocock/skills. First-run setup copies starter files only where you don't already have them.

Troubleshooting

• dotagents doctor is the first stop: it validates skill frontmatter, role definitions, lock pins, materialized copies, hook registration, and audits external sources.
• Upgrading from an old config that targets agent pi with MCP: vanilla Pi has no MCP surface, so the target is ignored with a warning — rename pi to omp in dotagents.yaml if you meant the OMP fork.
• A sync proposed removals you didn't expect: setup-driven syncs always preview removals per harness and default to keeping your files; answer n and inspect with dotagents status.

How it differs

rulesync and ruler are project-level: they generate per-tool configuration inside a repository and win on tool breadth. dotagents is user-level: one private config follows you across projects and machines, and it goes deeper per harness — native role rendering, hook registration, and commit-pinned, audited external skills. openskills installs skills; dotagents manages all four user-level surfaces together.

License

MIT

Documentation

Index

• Variables

Variables

var StarterAssets embed.FS

StarterAssets contains the public files that dotagents setup scaffolds into a user-owned canonical configuration root. The CLI must not read these paths from the source checkout at runtime; release binaries carry them here.