One canonical .agents folder powers all your AI tools, providing a unified source of truth for hooks, commands, skills, and rule files. It targets developers and power users managing multiple AI clients, simplifying setup and ensuring consistency across projects. The core benefit is streamlined, version-controllable management of AI tool integrations.

How It Works

The tool establishes symbolic links from a user-defined .agents folder to the configuration directories of supported AI clients (Claude, Codex, Factory, Cursor, OpenCode). Users define their AI logic and rules within .agents, and dotagents creates the necessary symlinks, either globally or per-project. This approach centralizes management, prevents duplication, and allows for easy rollbacks via automatic timestamped backups before any modifications.

Quick Start & Requirements

• Install/Run: Execute npx @iannuttall/dotagents or bunx @iannuttall/dotagents.
• Prerequisites: Bun 1.3+.
• Setup: A guided CLI prompts users to select a workspace (global or project) and desired clients. Re-running the CLI can repair links or undo changes.

Highlighted Details

• Supports both global (affecting all projects) and project-specific configurations.
• Manages symlinks for commands, hooks, skills, and rule files across Claude, Codex, Factory, Cursor, and OpenCode.
• Implements specific precedence for Claude rule files: .agents/CLAUDE.md is preferred over .agents/AGENTS.md.
• Codex prompts are always symlinked from .agents/commands.
• Skills require a SKILL.md file with frontmatter.
• Automatic backups are stored under .agents/backup/<timestamp> for reversible changes.

Maintenance & Community

The provided README does not detail specific contributors, sponsorships, partnerships, or community channels (e.g., Discord, Slack), nor does it link to a public roadmap.

Licensing & Compatibility

• License: MIT.
• Compatibility: The permissive MIT license allows for commercial use and integration into closed-source projects without significant restrictions.

Limitations & Caveats

In project scope, rule files (AGENTS.md/CLAUDE.md) are not managed via symlinks and require explicit user handling in the project root. Modifications to rule files necessitate re-running dotagents to update associated symlinks. Skills require a correctly formatted SKILL.md file.