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 | Slug | | ------------------ | ------------------------------------- | ------------------------------ | -------- | | Agent (dotagent) | .agent/**/*.md | Markdown with YAML frontmatter | agent | | Claude Code | CLAUDE.md | Plain Markdown | claude | | VS Code (Copilot) | .github/copilot-instructions.md | Plain Markdown | copilot | | Cursor | .cursor/**/*.mdc, .cursor/**/*.md | Markdown with YAML frontmatter | cursor | | Cline | .clinerules or .clinerules/*.md | Plain Markdown | cline | | Windsurf | .windsurfrules | Plain Markdown | windsurf | | Zed | .rules | Plain Markdown | zed | | OpenAI Codex | AGENTS.md | Plain Markdown | codex | | OpenCode | AGENTS.md | Plain Markdown | opencode | | Aider | CONVENTIONS.md | Plain Markdown | aider | | Gemini | GEMINI.md | Plain Markdown | gemini | | Qodo | best_practices.md | Plain Markdown | qodo | | Amazon Q Developer | .amazonq/rules/*.md | Plain Markdown | amazonq | | JetBrains Junie | .junie/guidelines.md | Plain Markdown | junie | | Roo Code | .roo/rules/*.md | Markdown with YAML frontmatter | roo |

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

# Auto-update gitignore (skip prompt)
dotagent export --format copilot --gitignore

# 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|junie|roo|opencode) | | --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 | | --gitignore | | Auto-update gitignore (skip prompt) | | --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:

1. Filename suffix: *.local.md (e.g., api-keys.local.md)
2. Directory: Files in /private/ subdirectories
3. 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 | | OpenCode | AGENTS.md | AGENTS.local.md | | Gemini | GEMINI.md | GEMINI.local.md | | Junie | .junie/guidelines.md | .junie/guidelines.local.md | | Roo Code | .roo/rules/*.md | .roo/rules/*.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
.junie/guidelines.local.md
.roo/rules/*.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
• importOpenCode(filePath: string): ImportResult - Import OpenCode 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
• importJunie(filePath: string): ImportResult - Import JetBrains Junie guidelines
• importRoo(rulesDir: string): ImportResult - Import Roo Code 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
• exportToOpenCode(rules: RuleBlock[], outputPath: string): void
• exportToAmazonQ(rules: RuleBlock[], outputDir: string): void
• exportToGemini(rules: RuleBlock[], outputPath: string): void
• exportToQodo(rules: RuleBlock[], outputPath: string): void
• exportToJunie(rules: RuleBlock[], outputPath: string): void
• exportToRoo(rules: RuleBlock[], outputDir: 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