Simple setup • One source of truth • Safe to re-run anytime

Fork of @iannuttall/dotagents with project scope agent files support

Quick Start

Requirements: Bun 1.3+.

Run the guided CLI:

npx @maulikso/dotagents

Or with Bun:

bunx @maulikso/dotagents

Choose a workspace (Global home or Project folder), select the clients you want to manage, and follow the prompts. You can run it again anytime to repair links or undo changes.

Global home affects all projects. Project folder only affects the current directory you run dotagents from.

What it does

• Keeps .agents as the source of truth.
• Creates symlinks for Claude, Codex, Factory, Cursor, OpenCode, and Gemini (based on your selection).
• Always creates a backup before any overwrite so changes are reversible.

Where it links (global scope)

.agents/CLAUDE.md → ~/.claude/CLAUDE.md (if present)

.agents/AGENTS.md → ~/.claude/CLAUDE.md (fallback when no CLAUDE.md)

.agents/GEMINI.md → ~/.gemini/GEMINI.md (if present)

.agents/AGENTS.md → ~/.gemini/GEMINI.md (fallback when no GEMINI.md)

.agents/commands → ~/.claude/commands

.agents/commands → ~/.factory/commands

.agents/commands → ~/.codex/prompts

.agents/commands → ~/.cursor/commands

.agents/commands → ~/.config/opencode/commands

.agents/commands → ~/.gemini/commands

.agents/hooks → ~/.claude/hooks

.agents/hooks → ~/.factory/hooks

.agents/AGENTS.md → ~/.factory/AGENTS.md

.agents/AGENTS.md → ~/.codex/AGENTS.md

.agents/AGENTS.md → ~/.config/opencode/AGENTS.md

.agents/skills → ~/.claude/skills

.agents/skills → ~/.factory/skills

.agents/skills → ~/.codex/skills

.agents/skills → ~/.cursor/skills

.agents/skills → ~/.config/opencode/skills

.agents/skills → ~/.gemini/skills

Where it links (project scope)

Project scope creates the same symlink structure as global scope, but within your project directory instead of your home directory. This allows per-project customization while keeping .agents as the canonical source.

.agents/CLAUDE.md → project/.claude/CLAUDE.md (if present)

.agents/AGENTS.md → project/.claude/CLAUDE.md (fallback when no CLAUDE.md)

.agents/GEMINI.md → project/.gemini/GEMINI.md (if present)

.agents/AGENTS.md → project/.gemini/GEMINI.md (fallback when no GEMINI.md)

.agents/commands → project/.claude/commands

.agents/commands → project/.factory/commands

.agents/commands → project/.codex/prompts

.agents/commands → project/.cursor/commands

.agents/commands → project/.opencode/commands

.agents/commands → project/.gemini/commands

.agents/hooks → project/.claude/hooks

.agents/hooks → project/.factory/hooks

.agents/AGENTS.md → project/.factory/AGENTS.md

.agents/AGENTS.md → project/.codex/AGENTS.md

.agents/skills → project/.claude/skills

.agents/skills → project/.factory/skills

.agents/skills → project/.codex/skills

.agents/skills → project/.cursor/skills

.agents/skills → project/.opencode/skills

.agents/skills → project/.gemini/skills

.agents/skills → project/.github/skills (GitHub Copilot)

Development

Run the CLI in dev mode:

bun run dev

Type-check:

bun run type-check

Run tests:

bun test

Build the CLI:

bun run build

Notes

• Cursor supports .claude/commands and .claude/skills (global or project). dotagents also links .agents/commands → .cursor/commands and .agents/skills → .cursor/skills.
• OpenCode uses ~/.config/opencode/AGENTS.md and prefers AGENTS.md over CLAUDE.md when both exist.
• Codex prompts always symlink to .agents/commands (canonical source).
• Skills require a valid SKILL.md with name + description frontmatter.
• Claude prompt precedence: if .agents/CLAUDE.md exists, it links to .claude/CLAUDE.md. Otherwise .agents/AGENTS.md is used. After adding or removing .agents/CLAUDE.md, re-run dotagents and apply/repair links to update the symlink. Factory/Codex always link to .agents/AGENTS.md.
• Gemini context file precedence: if .agents/GEMINI.md exists, it links to .gemini/GEMINI.md. Otherwise .agents/AGENTS.md is used. After adding or removing .agents/GEMINI.md, re-run dotagents and apply/repair links to update the symlink.
• Project scope creates .agents plus client folders with full symlink support for commands, hooks, skills, and agent markdown files (CLAUDE.md, AGENTS.md, GEMINI.md). This keeps .agents as the canonical source for all files in both global and project scopes.
• Backups are stored under .agents/backup/<timestamp> and can be restored via “Undo last change.”

License

MIT