dotagent

dotagent

Multi-file AI agent configuration manager with .agent directory support. Maintain a single source of truth for AI coding assistant rules across Claude Code, VS Code Copilot, Cursor, Cline, Windsurf, Zed, Amazon Q Developer, and more.

Features

• 🔄 Import rules from any supported IDE/tool format
• 📝 Convert to a unified .agent/ directory structure
• 🚀 Export back to all supported formats
• 📁 Nested folders support for better organization
• 🛠️ CLI tool for easy automation
• 📦 TypeScript API for programmatic use
• 🎨 Color-coded output for better readability
• 👁️ Dry-run mode to preview operations without changes
• 💡 Smart error messages with actionable hints

Supported Formats

Tool/IDE	Rule File	Format
Agent (dotagent)	.agent/**/*.md	Markdown with YAML frontmatter
Claude Code	CLAUDE.md	Plain Markdown
VS Code (Copilot)	.github/copilot-instructions.md	Plain Markdown
Cursor	.cursor/**/*.mdc, .cursor/**/*.md	Markdown with YAML frontmatter
Cline	.clinerules or .clinerules/*.md	Plain Markdown
Windsurf	.windsurfrules	Plain Markdown
Zed	.rules	Plain Markdown
OpenAI Codex	AGENTS.md	Plain Markdown
Aider	CONVENTIONS.md	Plain Markdown
Gemini	GEMINI.md	Plain Markdown
Qodo	best_practices.md	Plain Markdown
Amazon Q Developer	.amazonq/rules/*.md	Plain Markdown

Installation

npm install -g dotagent
# or
pnpm add -g dotagent

CLI Usage

Import all rules from a repository

# Import from current directory (creates .agent/ directory)
dotagent import .

# Import from specific path
dotagent import /path/to/repo

# Preview without making changes
dotagent import . --dry-run

Export .agent/ directory to formats

# Interactive export (shows menu to select format)
dotagent export

# Export to specific format (non-interactive)
dotagent export --format copilot

# Export to multiple formats (non-interactive)
dotagent export --formats copilot,claude,cursor

# Export all formats at once
dotagent export --formats all

# Export from specific directory
dotagent export /path/to/repo --format copilot

# Include private rules in export
dotagent export --include-private --format copilot

# Skip gitignore prompt (useful for CI/CD)
dotagent export --format copilot --no-gitignore

# Preview without making changes
dotagent export --dry-run

Convert a specific file

# Auto-detect format
dotagent convert .github/copilot-instructions.md

# Specify format explicitly
dotagent convert my-rules.md -f cursor

CLI Flags Reference

Flag	Short	Description
--help	-h	Show help message
--format	-f	Export to single format (copilot|cursor|cline|windsurf|zed|codex|aider|claude|gemini|qodo)
--formats		Export to multiple formats (comma-separated list)
--output	-o	Output directory path
--overwrite	-w	Overwrite existing files
--dry-run	-d	Preview operations without making changes
--include-private		Include private rules in export
--skip-private		Skip private rules during import
--no-gitignore		Skip gitignore update prompt

Unified Format

The .agent/ directory contains .md files (Markdown with YAML frontmatter) to organize rules, supporting nested folders:

---
id: core-style
title: Core Style Guidelines
alwaysApply: true
priority: high
---

## Core Style Guidelines

1. Use **Bazel** for Java builds
2. JavaScript: double quotes, tabs for indentation
3. All async functions must handle errors

And another file .agent/api-safety.md:

---
id: api-safety
title: API Safety Rules
scope: src/api/**
manual: true
---

## API Safety Rules

- Never log PII
- Validate all inputs with zod
- Rate limit all endpoints

Nested folders are supported - for example .agent/frontend/components.md:

---
id: frontend/components
title: Component Guidelines
scope: src/components/**
---

## Component Guidelines

- Use functional components with hooks
- Follow atomic design principles
- Include unit tests for all components

Private Rules

DotAgent supports private/local rules that are automatically excluded from exports and version control. This is useful for:

• Personal preferences that shouldn't be shared with the team
• Client-specific requirements
• Temporary experimental rules
• Sensitive information or internal processes

Naming Convention

Private rules are identified by:

• Filename suffix: *.local.md (e.g., api-keys.local.md)
• Directory: Files in /private/ subdirectories
• Frontmatter: private: true in YAML frontmatter

Examples

<!-- .agent/team-rules.md (PUBLIC) -->
---
id: team-rules
---
# Team Standards
Shared team guidelines

<!-- .agent/my-preferences.local.md (PRIVATE) -->
---
id: my-preferences
---
# My Personal Preferences
These won't be exported

<!-- .agent/private/client-specific.md (PRIVATE) -->
---
id: client-rules
---
# Client-Specific Rules
Confidential requirements

Private Rules in Other Formats

Format	Public File	Private File
Copilot	.github/copilot-instructions.md	.github/copilot-instructions.local.md
Cursor	.cursor/rules/*.mdc	.cursor/rules/*.local.mdc
Cline	.clinerules	.clinerules.local
Windsurf	.windsurfrules	.windsurfrules.local
Zed	.rules	.rules.local
Claude	CLAUDE.md	CLAUDE.local.md
Gemini	GEMINI.md	GEMINI.local.md

CLI Options

# Export including private rules
dotagent export --include-private

# Import but skip private rules
dotagent import . --skip-private

Automatic .gitignore

When you run dotagent export, it automatically updates your .gitignore with patterns for private files:

# Added by dotagent: ignore private AI rule files
.agent/**/*.local.md
.agent/private/**
.github/copilot-instructions.local.md
.cursor/rules/**/*.local.mdc
.cursor/rules-private/**
.clinerules.local
.clinerules/private/**
.windsurfrules.local
.rules.local
AGENTS.local.md
CONVENTIONS.local.md
CLAUDE.local.md
GEMINI.local.md

Programmatic Usage

import { 
  importAll, 
  importAgent,
  exportToAgent,
  exportAll 
} from 'dotagent'

// Import all rules from a repository
const { results, errors } = await importAll('/path/to/repo')

// Import from .agent directory
const { rules } = await importAgent('/path/to/repo/.agent')

// Export to .agent directory
await exportToAgent(rules, '/path/to/repo')

// Export to all formats
exportAll(rules, '/path/to/repo')

API Reference

Types

interface RuleBlock {
  metadata: RuleMetadata
  content: string
  position?: Position
}

interface RuleMetadata {
  id: string
  alwaysApply?: boolean
  scope?: string | string[]
  triggers?: string[]
  manual?: boolean
  priority?: 'high' | 'medium' | 'low'
  description?: string
  [key: string]: unknown
}

Parser Functions

• parseAgentMarkdown(markdown: string): RuleBlock[] - Parse HTML-directive format
• parseFenceEncodedMarkdown(markdown: string): RuleBlock[] - Parse fence-encoded format

Import Functions

• importAll(repoPath: string): Promise<ImportResults> - Auto-detect and import all formats
• importCopilot(filePath: string): ImportResult - Import VS Code Copilot format
• importCursor(rulesDir: string): ImportResult - Import Cursor MDC files
• importCline(rulesPath: string): ImportResult - Import Cline rules
• importWindsurf(filePath: string): ImportResult - Import Windsurf rules
• importZed(filePath: string): ImportResult - Import Zed rules
• importCodex(filePath: string): ImportResult - Import OpenAI Codex format
• importGemini(filePath: string): ImportResult - Import Gemini CLI format
• importQodo(filePath: string): ImportResult - Import Qodo best practices
• importAmazonQ(rulesDir: string): ImportResult - Import Amazon Q Developer rules

Export Functions

• toAgentMarkdown(rules: RuleBlock[]): string - Convert to unified format
• exportAll(rules: RuleBlock[], repoPath: string): void - Export to all formats
• exportToCopilot(rules: RuleBlock[], outputPath: string): void
• exportToCursor(rules: RuleBlock[], outputDir: string): void
• exportToCline(rules: RuleBlock[], outputPath: string): void
• exportToWindsurf(rules: RuleBlock[], outputPath: string): void
• exportToZed(rules: RuleBlock[], outputPath: string): void
• exportToCodex(rules: RuleBlock[], outputPath: string): void
• exportToAmazonQ(rules: RuleBlock[], outputDir: string): void
• exportToGemini(rules: RuleBlock[], outputPath: string): void
• exportToQodo(rules: RuleBlock[], outputPath: string): void

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Run tests
pnpm test

# Development mode
pnpm dev

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Roadmap

• Support for more IDE formats
• Web-based converter UI
• GitHub Action for automatic sync
• Support for team rule templates
• Validation and linting of rules
• Rule inheritance and composition