Dotfiles for your AI agents.
brew install yourconscience/tap/dotagentsNot affiliated with the unscoped npm
dotagentspackage — this repo publishes as@your_conscience/dotagents.
Overview & comparison → · Releases · Docs
If you use more than one coding agent, you maintain the same skills, MCP servers, hooks, and roles in a different place and format for each one. Copying them by hand drifts within a week. Skills have converged on one open convention (agentskills.io), plugins on agent-plugins-spec, and root instructions on AGENTS.md — but every harness still stores and renders config in its own native format. dotagents applies the dotfiles pattern to that last mile: one versioned repo, rendered natively per harness, with memory tooling built in.
brew install yourconscience/tap/dotagents # or: npm i -g @your_conscience/dotagents
dotagents setup # detect harnesses, import, first syncsetup creates ~/.agents, detects installed harnesses, imports existing content by copy after a per-item review, and runs the first sync. To carry the setup to other machines, add a private git remote and repeat — details in docs/setup.md.
dotagents status # per-harness sync state
dotagents doctor # health checks: frontmatter, lock pins, audits, hooksFive surfaces, each rendered into the harness's own format — dotagents does not invent compatibility files a harness cannot consume:
| Harness | Skills | Roles | MCP | Hooks | Plugins |
|---|---|---|---|---|---|
| Claude Code | yes | yes | yes | yes | -- |
| Codex | yes | yes | yes | yes | planned |
| Factory Droid | yes | yes | yes | yes | -- |
| Hermes | yes | -- | yes | yes | -- |
| OpenCode | yes† | yes | yes | -- | -- |
| OMP (pi fork) | yes | yes | yes | --‡ | -- |
| Pi* | yes | --* | --* | -- | -- |
* Vanilla pi is skills-only by design; the OMP fork is detected as its own target.
† OpenCode reads ~/.agents/skills/ natively; its only hook surface is a JS plugin API.
‡ OMP has no managed hook surface yet; register memory hooks manually if needed.
Amp and OpenClaw read the repo's skills via standard conventions but are not managed. A "yes" above only appears after end-to-end verification.
A skill is a directory under ~/.agents/skills/ with a SKILL.md (agentskills.io convention) — create once, appears everywhere. External skills are treated like dependencies: pinned in dotagents.lock, materialized for diffing, audited by dotagents doctor. Details in docs/skills.md.
Pick a tier during setup: off, basic (session digests), or memsearch (indexed search). On top of that, sync builds two Go helpers into ~/.local/bin: knowledge-sync (vault git sync) and rem:
rem add -src claude "prefers pnpm for Node work" # capture a candidate fact anywhere
rem dream # consolidate candidates into review reports
rem dream --apply # collapse exact-duplicate records (backup + commit)
rem search "quota preferences" # semantic search over captured memoryCandidates are inert until you promote them into durable instructions — consolidation is report-first by design, because automatically rewriting memory is how agents quietly corrupt their own instructions. Design notes in docs/memory.md.
Markdown role definitions in ~/.agents/agents/, rendered to each harness's native format (Claude Markdown, Codex TOML, Droid). Generic model tiers (haiku/sonnet/opus) render natively per family; per-harness overrides pin exact ids. Six starter roles ship with the tool; yours win on name collision. Details in docs/roles.md.
dotagents setup [--memory off|basic|memsearch] [--yes] [--dry-run] [--json]
dotagents status [--agents ...]
dotagents sync [--pull] [--agents ...]
dotagents doctor [--e2e] [--agents ...]
dotagents skill new|update|promote
dotagents mcp list|add|import|remove~/.agents/dotagents.yaml is the single source of truth; setup fills in detected harnesses. Resolution order: --config <path> → $DOTAGENTS_HOME/dotagents.yaml → ~/.agents/dotagents.yaml; never walks the current project. Machine-local entries overlay via dotagents.local.yaml. Managed entries are marked in native configs; anything else is left untouched.
scripts/release.sh v0.7.0 # verify + tag; CI publishes binaries, brew tap, npm- docs/setup.md — first-run walkthrough, review screen, multi-machine setup
- docs/skills.md — authoring skills, external pins and audits
- docs/roles.md — role format, model tiers, per-harness overrides
- docs/memory.md — memory tiers, rem workflow, vault layout
- docs/comparison.md — how dotagents differs from rulesync, ruler, openskills
- Troubleshooting
Project-level generators (rulesync, ruler) win on tool breadth; dotagents is user-level — one private repo, seven targets deep, pinned externals, review-first memory. Full table in docs/comparison.md.