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
# no brew/npm? curl -fsSL https://raw.githubusercontent.com/yourconscience/dotagents/main/scripts/install.sh | sh
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 |
|---|---|---|---|---|---|
| Amp | yes, config-driven | --⁑ | yes | --⁑ | -- |
| 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 | -- | -- |
| Qwen Code | yes, config-driven | yes | yes | yes | skills + MCP§ |
| OMP (pi fork) | yes | yes | yes | --‡ | -- |
| Pi* | yes | yes* | yes* | -- | skills + MCP* |
* Vanilla pi gains managed roles through pi-subagents and managed MCP/Agent Plugin projection through pi-mcp-adapter. A Pi target can also declare a pinned packages list; sync writes that list to ~/.pi/agent/settings.json, and Pi installs missing packages on its next startup. Dotagents does not install the Pi executable itself. The OMP fork remains a separate target.
agents:
- name: pi
enabled: true
detect: pi
skill_root: ~/.pi/agent/skills
agent_root: ~/.pi/agent/agents
packages:
- npm:pi-mcp-adapter@2.33.0
- npm:pi-subagents@0.67.0† 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.
§ Qwen Code natively loads Agent Plugins v1 skills and MCP servers; dotagents manages those same surfaces without rewriting the plugin.
⁑ Amp's hook and role surfaces use plugin-based models incompatible with dotagents' script-based hooks and per-agent role files.
OpenClaw is not currently supported. Native skill discovery from ~/.agents/skills may work due to OpenClaw's multi-tier skill precedence, but this is unverified and unmanaged. A managed harness entry is planned for a future release. 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, Qwen Markdown, Droid). Generic model tiers (haiku/sonnet/opus) render natively for Claude and Droid; Codex omits them and uses its own default unless a per-harness override pins an exact id. 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 [--verbose] [--agents ...]
dotagents sync [--pull] [--agents ...]
dotagents doctor [--e2e] [--agents ...]
dotagents config # Bubble Tea canonical YAML editor (terminal)
dotagents config validate|print
dotagents view [--addr 127.0.0.1:8765] [--no-open] [--secure-cookie] [--ssh-host user@host] # loopback web config UI
dotagents inspect [--no-open] [--ssh-host user@host] [--port N] [--host ADDR] # launch HarnessKit (cross-harness inspector)
dotagents sessions [--no-open] [--ssh-host user@host] [--port N] [--host ADDR] # launch AgentsView (sessions and usage)
dotagents skill new|list|info|update|promote
dotagents publish [--target NAME] [--skills a,b] [--dry-run] [--json] [--yes] # push skills to a remote registry
dotagents mcp list|add|import|remove
dotagents hook list [query] | remove [--dry-run] <query>dotagents can launch two optional external tools. Neither is installed, vendored, or required by dotagents:
| Integration | Purpose | Connector |
|---|---|---|
| HarnessKit | Inspect and audit skills, MCP servers, hooks, and native harness configuration | dotagents inspect |
| AgentsView | Search and replay sessions; inspect tool telemetry, token usage, and estimated cost | dotagents sessions |
dotagents skill list remains the built-in provenance view for each harness skill root. It reports managed links, foreign symlinks, unmanaged directories, drift, broken links, and estimated context cost.
dotagents hook list [query] inventories native hook registrations and marks canonical entries as managed and missing script targets as stale. To clean up a hook installed outside dotagents, preview with dotagents hook remove --dry-run <query>, then rerun without --dry-run; unrelated hook entries are preserved. dotagents doctor reports stale native hooks, and dotagents sync reconciles the remaining canonical hooks afterward.
dotagents inspect shells out to HarnessKit (hk serve). Treat it as read-mostly: HarnessKit's enable/disable/deploy actions bypass dotagents, so reconcile any changes with dotagents sync. Install HarnessKit separately.
dotagents sessions shells out to AgentsView (agentsview serve). AgentsView owns its local transcript index and configuration; dotagents does not sync or mutate either. --no-open maps to AgentsView's --no-browser; --ssh-host user@host prints a loopback tunnel command on a remote machine. Other flags are forwarded to agentsview serve. Install AgentsView separately.
A dotagents-format repo also works as a plain skills source. Anyone can copy individual skills into their harness of choice with the skills.sh installer, no dotagents install needed:
npx skills add yourconscience/myagents -s dotagents --copy # verified: copies cleanly, no symlinksThat path copies editable files (the "fork" model); dotagents users get the symlink-to-canonical model with lock-pinned updates. Pick one per machine — installing both leaves you with every skill twice.
Other tools share the name: npm's dotagents (@iannuttall) and Sentry's @sentry/dotagents skill vendoring CLI. This repo is yourconscience/dotagents — install as brew install yourconscience/tap/dotagents or npm i -g @your_conscience/dotagents.
~/.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.
dotagents config (terminal TUI) and dotagents view (browser web UI) edit the
resolved canonical YAML through the same review-first flow. Shared and
dotagents.local.yaml are separate editable layers; the effective view is
read-only. Structured edits preserve comments and unknown fields, and a save
never runs sync implicitly.
dotagents config # interactive terminal editor
dotagents view --no-open --addr 127.0.0.1:8765 # loopback web UI, print the URL
dotagents config validate
dotagents config printThe view web server is loopback-only, session-cookie authenticated (a
one-time startup token swapped for an HttpOnly, SameSite=Strict cookie),
CSRF- and origin-checked on mutations, guards saves by revision, and keeps sync
as a separate preview/confirm step. It prints the tokenized URL on its own line
and opens your default browser locally; --no-open skips that, and
--ssh-host user@host (or an SSH session, via SSH_CONNECTION) prints an
ssh -L tunnel command for reaching the loopback UI from another machine. For
deliberate HTTPS tailnet access, expose the loopback listener yourself:
dotagents view --no-open --secure-cookie --addr 127.0.0.1:8765
tailscale serve --bg --set-path /dotagents http://127.0.0.1:8765Releases are cut from main after the release PR is reviewed and merged, and only with explicit approval:
scripts/release.sh vX.Y.Z # verify + tag; CI publishes binaries, brew tap, npmThe script refuses to run unless the tree is clean, HEAD matches origin/main, the tag is strict vMAJOR.MINOR.PATCH, and every check passes. Pushing the tag starts .github/workflows/release.yml, which re-verifies the tag against main and a green ci.yml run, waits on the protected release environment, then publishes binaries, the Homebrew tap, and the npm wrapper.
- Overview & comparison — landing page, sync matrix, positioning
- 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
- memory/README.md — memory layer layout, hooks, and tools
Project-level generators (rulesync, ruler) win on tool breadth; dotagents is user-level — one private repo, nine targets deep, pinned externals, review-first memory. Full table in docs/comparison.md.