{"id":30584072,"url":"https://github.com/johnlindquist/dotagent","last_synced_at":"2025-08-29T09:02:59.529Z","repository":{"id":299659364,"uuid":"1003709431","full_name":"johnlindquist/dotagent","owner":"johnlindquist","description":"Universal AI agent configuration parser and converter","archived":false,"fork":false,"pushed_at":"2025-07-09T18:40:50.000Z","size":150,"stargazers_count":47,"open_issues_count":5,"forks_count":4,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-19T00:03:08.636Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/johnlindquist.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-17T14:48:03.000Z","updated_at":"2025-08-12T09:59:50.000Z","dependencies_parsed_at":"2025-06-18T16:02:49.975Z","dependency_job_id":null,"html_url":"https://github.com/johnlindquist/dotagent","commit_stats":null,"previous_names":["johnlindquist/agentconfig","johnlindquist/dotagent"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/johnlindquist/dotagent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnlindquist%2Fdotagent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnlindquist%2Fdotagent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnlindquist%2Fdotagent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnlindquist%2Fdotagent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/johnlindquist","download_url":"https://codeload.github.com/johnlindquist/dotagent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnlindquist%2Fdotagent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272658781,"owners_count":24971604,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-29T02:00:10.610Z","response_time":87,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-29T09:02:57.724Z","updated_at":"2025-08-29T09:02:59.517Z","avatar_url":"https://github.com/johnlindquist.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","others"],"sub_categories":[],"readme":"# dotagent\n\nMulti-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.\n\n## Features\n\n- 🔄 **Import** rules from any supported IDE/tool format\n- 📝 **Convert** to a unified `.agent/` directory structure\n- 🚀 **Export** back to all supported formats\n- 📁 **Nested folders** support for better organization\n- 🛠️ **CLI tool** for easy automation\n- 📦 **TypeScript API** for programmatic use\n- 🎨 **Color-coded output** for better readability\n- 👁️ **Dry-run mode** to preview operations without changes\n- 💡 **Smart error messages** with actionable hints\n\n## Supported Formats\n\n| Tool/IDE | Rule File | Format |\n|----------|-----------|---------|\n| Agent (dotagent) | `.agent/**/*.md` | Markdown with YAML frontmatter |\n| Claude Code | `CLAUDE.md` | Plain Markdown |\n| VS Code (Copilot) | `.github/copilot-instructions.md` | Plain Markdown |\n| Cursor | `.cursor/**/*.mdc`, `.cursor/**/*.md` | Markdown with YAML frontmatter |\n| Cline | `.clinerules` or `.clinerules/*.md` | Plain Markdown |\n| Windsurf | `.windsurfrules` | Plain Markdown |\n| Zed | `.rules` | Plain Markdown |\n| OpenAI Codex | `AGENTS.md` | Plain Markdown |\n| Aider | `CONVENTIONS.md` | Plain Markdown |\n| Gemini | `GEMINI.md` | Plain Markdown |\n| Qodo | `best_practices.md` | Plain Markdown |\n| Amazon Q Developer | `.amazonq/rules/*.md` | Plain Markdown |\n\n## Installation\n\n```bash\nnpm install -g dotagent\n# or\npnpm add -g dotagent\n```\n\n## CLI Usage\n\n### Import all rules from a repository\n\n```bash\n# Import from current directory (creates .agent/ directory)\ndotagent import .\n\n# Import from specific path\ndotagent import /path/to/repo\n\n# Preview without making changes\ndotagent import . --dry-run\n```\n\n### Export `.agent/` directory to formats\n\n```bash\n# Interactive export (shows menu to select format)\ndotagent export\n\n# Export to specific format (non-interactive)\ndotagent export --format copilot\n\n# Export to multiple formats (non-interactive)\ndotagent export --formats copilot,claude,cursor\n\n# Export all formats at once\ndotagent export --formats all\n\n# Export from specific directory\ndotagent export /path/to/repo --format copilot\n\n# Include private rules in export\ndotagent export --include-private --format copilot\n\n# Skip gitignore prompt (useful for CI/CD)\ndotagent export --format copilot --no-gitignore\n\n# Preview without making changes\ndotagent export --dry-run\n```\n\n### Convert a specific file\n\n```bash\n# Auto-detect format\ndotagent convert .github/copilot-instructions.md\n\n# Specify format explicitly\ndotagent convert my-rules.md -f cursor\n```\n\n### CLI Flags Reference\n\n| Flag | Short | Description |\n|------|-------|-------------|\n| `--help` | `-h` | Show help message |\n| `--format` | `-f` | Export to single format (copilot\\|cursor\\|cline\\|windsurf\\|zed\\|codex\\|aider\\|claude\\|gemini\\|qodo) |\n| `--formats` | | Export to multiple formats (comma-separated list) |\n| `--output` | `-o` | Output directory path |\n| `--overwrite` | `-w` | Overwrite existing files |\n| `--dry-run` | `-d` | Preview operations without making changes |\n| `--include-private` | | Include private rules in export |\n| `--skip-private` | | Skip private rules during import |\n| `--no-gitignore` | | Skip gitignore update prompt |\n\n## Unified Format\n\nThe `.agent/` directory contains `.md` files (Markdown with YAML frontmatter) to organize rules, supporting nested folders:\n\n```markdown\n---\nid: core-style\ntitle: Core Style Guidelines\nalwaysApply: true\npriority: high\n---\n\n## Core Style Guidelines\n\n1. Use **Bazel** for Java builds\n2. JavaScript: double quotes, tabs for indentation\n3. All async functions must handle errors\n```\n\nAnd another file `.agent/api-safety.md`:\n\n```markdown\n---\nid: api-safety\ntitle: API Safety Rules\nscope: src/api/**\nmanual: true\n---\n\n## API Safety Rules\n\n- Never log PII\n- Validate all inputs with zod\n- Rate limit all endpoints\n```\n\nNested folders are supported - for example `.agent/frontend/components.md`:\n\n```markdown\n---\nid: frontend/components\ntitle: Component Guidelines\nscope: src/components/**\n---\n\n## Component Guidelines\n\n- Use functional components with hooks\n- Follow atomic design principles\n- Include unit tests for all components\n```\n\n## Private Rules\n\nDotAgent supports private/local rules that are automatically excluded from exports and version control. This is useful for:\n- Personal preferences that shouldn't be shared with the team\n- Client-specific requirements  \n- Temporary experimental rules\n- Sensitive information or internal processes\n\n### Naming Convention\n\nPrivate rules are identified by:\n1. **Filename suffix**: `*.local.md` (e.g., `api-keys.local.md`)\n2. **Directory**: Files in `/private/` subdirectories\n3. **Frontmatter**: `private: true` in YAML frontmatter\n\n### Examples\n\n```markdown\n\u003c!-- .agent/team-rules.md (PUBLIC) --\u003e\n---\nid: team-rules\n---\n# Team Standards\nShared team guidelines\n```\n\n```markdown\n\u003c!-- .agent/my-preferences.local.md (PRIVATE) --\u003e\n---\nid: my-preferences\n---\n# My Personal Preferences\nThese won't be exported\n```\n\n```markdown\n\u003c!-- .agent/private/client-specific.md (PRIVATE) --\u003e\n---\nid: client-rules\n---\n# Client-Specific Rules\nConfidential requirements\n```\n\n### Private Rules in Other Formats\n\n| Format | Public File | Private File |\n|--------|-------------|---------------|\n| Copilot | `.github/copilot-instructions.md` | `.github/copilot-instructions.local.md` |\n| Cursor | `.cursor/rules/*.mdc` | `.cursor/rules/*.local.mdc` |\n| Cline | `.clinerules` | `.clinerules.local` |\n| Windsurf | `.windsurfrules` | `.windsurfrules.local` |\n| Zed | `.rules` | `.rules.local` |\n| Claude | `CLAUDE.md` | `CLAUDE.local.md` |\n| Gemini | `GEMINI.md` | `GEMINI.local.md` |\n\n### CLI Options\n\n```bash\n# Export including private rules\ndotagent export --include-private\n\n# Import but skip private rules\ndotagent import . --skip-private\n```\n\n### Automatic .gitignore\n\nWhen you run `dotagent export`, it automatically updates your `.gitignore` with patterns for private files:\n\n```gitignore\n# Added by dotagent: ignore private AI rule files\n.agent/**/*.local.md\n.agent/private/**\n.github/copilot-instructions.local.md\n.cursor/rules/**/*.local.mdc\n.cursor/rules-private/**\n.clinerules.local\n.clinerules/private/**\n.windsurfrules.local\n.rules.local\nAGENTS.local.md\nCONVENTIONS.local.md\nCLAUDE.local.md\nGEMINI.local.md\n```\n\n## Programmatic Usage\n\n```typescript\nimport { \n  importAll, \n  importAgent,\n  exportToAgent,\n  exportAll \n} from 'dotagent'\n\n// Import all rules from a repository\nconst { results, errors } = await importAll('/path/to/repo')\n\n// Import from .agent directory\nconst { rules } = await importAgent('/path/to/repo/.agent')\n\n// Export to .agent directory\nawait exportToAgent(rules, '/path/to/repo')\n\n// Export to all formats\nexportAll(rules, '/path/to/repo')\n```\n\n## API Reference\n\n### Types\n\n```typescript\ninterface RuleBlock {\n  metadata: RuleMetadata\n  content: string\n  position?: Position\n}\n\ninterface RuleMetadata {\n  id: string\n  alwaysApply?: boolean\n  scope?: string | string[]\n  triggers?: string[]\n  manual?: boolean\n  priority?: 'high' | 'medium' | 'low'\n  description?: string\n  [key: string]: unknown\n}\n```\n\n### Parser Functions\n\n- `parseAgentMarkdown(markdown: string): RuleBlock[]` - Parse HTML-directive format\n- `parseFenceEncodedMarkdown(markdown: string): RuleBlock[]` - Parse fence-encoded format\n\n### Import Functions\n\n- `importAll(repoPath: string): Promise\u003cImportResults\u003e` - Auto-detect and import all formats\n- `importCopilot(filePath: string): ImportResult` - Import VS Code Copilot format\n- `importCursor(rulesDir: string): ImportResult` - Import Cursor MDC files\n- `importCline(rulesPath: string): ImportResult` - Import Cline rules\n- `importWindsurf(filePath: string): ImportResult` - Import Windsurf rules\n- `importZed(filePath: string): ImportResult` - Import Zed rules\n- `importCodex(filePath: string): ImportResult` - Import OpenAI Codex format\n- `importGemini(filePath: string): ImportResult` - Import Gemini CLI format\n- `importQodo(filePath: string): ImportResult` - Import Qodo best practices\n- `importAmazonQ(rulesDir: string): ImportResult` - Import Amazon Q Developer rules\n\n### Export Functions\n\n- `toAgentMarkdown(rules: RuleBlock[]): string` - Convert to unified format\n- `exportAll(rules: RuleBlock[], repoPath: string): void` - Export to all formats\n- `exportToCopilot(rules: RuleBlock[], outputPath: string): void`\n- `exportToCursor(rules: RuleBlock[], outputDir: string): void`\n- `exportToCline(rules: RuleBlock[], outputPath: string): void`\n- `exportToWindsurf(rules: RuleBlock[], outputPath: string): void`\n- `exportToZed(rules: RuleBlock[], outputPath: string): void`\n- `exportToCodex(rules: RuleBlock[], outputPath: string): void`\n- `exportToAmazonQ(rules: RuleBlock[], outputDir: string): void`\n- `exportToGemini(rules: RuleBlock[], outputPath: string): void`\n- `exportToQodo(rules: RuleBlock[], outputPath: string): void`\n\n## Development\n\n```bash\n# Install dependencies\npnpm install\n\n# Build\npnpm build\n\n# Run tests\npnpm test\n\n# Development mode\npnpm dev\n```\n\n## License\n\nMIT\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Roadmap\n\n- [ ] Support for more IDE formats\n- [ ] Web-based converter UI\n- [ ] GitHub Action for automatic sync\n- [ ] Support for team rule templates\n- [ ] Validation and linting of rules\n- [ ] Rule inheritance and composition","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnlindquist%2Fdotagent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjohnlindquist%2Fdotagent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnlindquist%2Fdotagent/lists"}