README
¶
dot-agent
Sync AI coding assistant configuration across machines using git.
Supports Claude Code (~/.claude), Cursor (~/.cursor), Hermes Agent (~/.hermes), OpenAI Codex (~/.codex), Gemini CLI (~/.gemini), GitHub Copilot CLI (~/.copilot), and Antigravity CLI (~/.gemini/antigravity-cli) on macOS, Linux, and Windows.
Install
Homebrew (macOS / Linux)
brew tap cthulhu/dot-agent https://github.com/cthulhu/dot-agent
brew install dot-agent
Install the latest development build from main:
brew install --HEAD dot-agent
Requires git in your PATH (installed automatically via Homebrew).
Chocolatey (Windows)
To install via Chocolatey using GitHub Packages as a custom source (similar to a Homebrew tap):
# Register the GitHub Packages source (run as Administrator)
choco source add -n="cthulhu" -s="https://nuget.pkg.github.com/cthulhu/index.json"
# Install dot-agent from the custom source
choco install dot-agent --source="cthulhu"
Go
go install github.com/cthulhu/dot-agent/cmd/dot-agent@latest
From source
git clone https://github.com/cthulhu/dot-agent.git
cd dot-agent
go build -o dot-agent ./cmd/dot-agent
Quick start
Create a private git repo (GitHub, GitLab, etc.), then on your primary machine:
dot-agent init --repo git@github.com:you/ai-config.git
dot-agent add claude
dot-agent add cursor
dot-agent add hermes
dot-agent add codex
dot-agent add gemini
dot-agent add copilot
dot-agent add antigravity
dot-agent push
On a new machine:
dot-agent init --repo git@github.com:you/ai-config.git
dot-agent pull --apply
Commands
| Command | Description |
|---|---|
init [--repo URL] [--path DIR] |
Create or clone the source git repo |
add [claude|cursor|hermes|codex|gemini|copilot|antigravity] |
Capture local config into the repo |
rm <assistant> |
Remove an assistant from the repo |
apply [claude|cursor|hermes|codex|gemini|copilot|antigravity] |
Write repo config to local directories |
diff [claude|cursor|hermes|codex|gemini|copilot|antigravity] |
Show differences (source vs local) |
status |
Git status + config drift |
push |
Commit (if needed) and push |
pull [--apply] |
Pull remote; optionally apply locally |
doctor |
Validate git, paths, and manifest |
source-path |
Print source repo path |
cd |
Launch a shell in the source directory |
base init |
Initialize ~/.dot-agent/base/skills library |
base skills list |
List skills in the base library |
base skills show <skill> |
Show a base skill's SKILL.md |
base skills pull <assistant> [skill|--all] |
Copy skill(s) from an assistant into base |
base skills push <assistant> [skill|--all] |
Copy skill(s) from base into an assistant |
base skills remove <skill> |
Remove a skill from base |
base skills copy from|to|between ... |
Copy skills via base or between assistants |
Flags
add --dry-run/apply --dry-run— preview changesapply --backup— backup overwritten local filesapply --force— apply even when local files differ--source DIR— override source repo path (default stored in user config)
dot-agent cd
Like chezmoi cd, this launches a subshell in your source repo — it does not change your current shell's directory. Exit the subshell to return where you were:
dot-agent cd
git status
exit
To change directory in your current shell instead:
cd "$(dot-agent source-path)"
Inside the subshell, DOT_AGENT_SUBSHELL=1 and DOT_AGENT_SOURCE_DIR are set (useful for shell prompts).
Source repo layout
dot-agent.yaml
assistants/
claude/
cursor/
hermes/
codex/
gemini/
copilot/
antigravity/
Hermes syncs portable config (config.yaml, SOUL.md, memories/, skills/, cron/) and skips secrets (.env, auth.json), sessions, logs, and the installed source tree (hermes-agent/). On native Windows, Hermes may use %LOCALAPPDATA%\hermes instead of ~/.hermes — override target in dot-agent.yaml if needed.
Codex syncs portable config (config.toml, AGENTS.md, rules/instructions) and skips auth.json, session history, logs, and caches. Override target if you use a custom CODEX_HOME.
Gemini CLI syncs portable config (settings.json, GEMINI.md, skills/, commands/, agents/, extensions/, policies/) and skips OAuth tokens, .env files, session history, caches, and machine-local state. Override target if you use a custom GEMINI_CLI_HOME.
Copilot CLI syncs portable config (settings.json, copilot-instructions.md, agents/, skills/, hooks/, MCP/LSP configs, and plugins) and skips authentication state (config.json), session history, logs, and IDE integration state. Override target if you use a custom COPILOT_HOME.
Default paths:
| OS | Source repo | User config | Base library |
|---|---|---|---|
| macOS / Linux | ~/.dot-agent/source |
~/.dot-agent/config.yaml |
~/.dot-agent/base/skills |
| Windows | %LOCALAPPDATA%\dot-agent\source |
%APPDATA%\dot-agent\config.yaml |
%USERPROFILE%\.dot-agent\base\skills |
Base skills library
The base library at ~/.dot-agent/base/skills is a local collection of reusable skills. It is not synced via your dot-agent git repo — use it as a staging area to copy skills between assistants.
dot-agent base init
dot-agent base skills pull cursor babysit
dot-agent base skills list
dot-agent base skills push claude babysit
dot-agent base skills copy between cursor gemini babysit
Skills-aware assistants: claude, cursor, hermes, gemini, copilot. Use --repo with pull/push/copy to read from or write to your source repo instead of local assistant directories. Use --force to overwrite existing skills.
What gets synced
Sensitive and machine-local paths are ignored by default (caches, projects, extensions, credentials). Edit dot-agent.yaml in your source repo to customize ignore patterns.
Contributing
Contributions are welcome! Please see CONTRIBUTE.md for guidelines.
License
MIT
Directories