Centralized AI assistant configuration manager. Sync rules, slash commands, and workflows across Claude Code, Cursor, Kilo Code, and Roo Code. One setup, consistent AI assistance in all projects with centralized .dev/rules/ and automatic session hooks.
npm install ai-dotfiles-managerbin/ — CLI entry points (the bin/setup.js script and helpers that parse flags and orchestrate installation).
lib/ — pure, testable modules that capture business logic without side effects so they are easy to unit test.
scripts/ — maintenance utilities such as migrations, workspace initializers, and report generators.
templates/ — provider hooks, prompt scaffolds, and rule blueprints (claude/, cursor/, kilocode/, roo/, dev/, shared/, codex/, and languages/).
resources/ — static assets consumed by the CLI or docs (images, reports, and other reference data).
__tests__/ — Jest suites, fixtures, and helpers that validate the templates, migrations, and library modules.
coverage/ & dist/ — generated artifacts from tests and builds (ignore in commits).
.dev/ — the developer workspace that AI assistants auto-load; it currently contains:
architecture.md, context-index.md, codex-manifest.json, README.md, DESIGNcode.md, and optional todo.md.
rules/ (shared, TypeScript, and .local overrides) plus lint/jetbrains-lint.md.
.claude/ — Claude Code configuration details (hooks/, slash command scripts, and settings.json that point at .dev/rules/).
.github/, .tmp/, .idea/ — CI metadata, transient workspace files, and IDE settings.
package.json, package-lock.json, tsconfig*.json, .eslintrc.js, jest.config.js, AGENTS.md, CHANGELOG.md, STATUS.md, and other project-level docs.
.dev/rules/ instead of duplicated across provider folders. Claude Code hooks (in .claude/hooks/) automatically load rules and commit completed tasks.
.dev/rules/ (shared) directory. Base rules within .dev/rules/ are managed copies sourced from this package.
/status slash command to view loaded context and current task anytime
--yes flag for automated setup/updates without prompts
--no-codex-guide to skip generating Codex manifest/index files and the AGENTS guide block
/review-changes command for comprehensive code review before pushing changes
bash
1. Install globally (once per machine)
npm install -g ai-dotfiles-manager
2. Navigate to your project
cd ~/projects/your-project
3. Run setup (interactive)
ai-dotfiles-manager setup
Or run non-interactive setup with defaults
ai-dotfiles-manager setup --yes
4. Select tools (or use "✨ Select All")
Creates centralized .dev/rules/ and provider configs pointing to it
5. Start coding with AI assistance!
Claude Code hooks automatically load rules and commit completed todos
6. Check session status anytime
Type /status in Claude Code to see loaded context and current task
`
Migrating Existing Configurations
$3
For existing projects, use the migration script to transition to the new centralized structure:
`bash
Run migration script
npm run migrate
`
This will:
1. Detect existing AI tool configurations
2. Backup existing files with timestamp
3. Migrate custom rules to .dev/rules/.local/
4. Set up centralized .dev/rules/ structure
5. Update provider configurations to point to centralized rules
6. Remove old duplicated rule folders
If you run ai-dotfiles-manager setup on a project that already has AI tool configurations (.claude/, .cursorrules, etc.), you'll be prompted with migration options:
$3
1. Migrate to .local/ (supersede shared rules)
- Moves your existing files to .local/ directories
- Your custom rules will override shared rules with the same names
- Best for: Projects with custom rules you want to preserve and prioritize
2. Migrate to .local/ (preserve alongside shared rules)
- Moves your existing files to .local/ directories
- Your custom rules exist alongside shared rules (no override)
- Best for: Projects with additional custom rules
3. Replace with new setup
- Replaces everything with fresh templates (default option)
- Best for: Quick updates or starting fresh
4. Skip - keep existing configuration as-is
- Leaves current configuration untouched
- Setup does not proceed for that tool
- Best for: Manually managed configurations
$3
Claude Code (.claude/)
`bash
Existing custom rules moved to:
.dev/rules/.local/your-custom-rule.md
`
Cursor (.cursorrules)
`bash
Existing file moved to:
.cursorrules.local
`
Kilo Code (.kilocode/) and Roo Code (.roo/)
`bash
Existing custom rules moved to:
.dev/rules/.local/your-custom-rule.md
`
Why Global Installation?
Global installation is the recommended approach because:
1. Install Once, Use Everywhere: One installation serves all your projects
2. Always Available: The command works from any directory
3. Easy Updates: Update once globally instead of in every project
4. Consistent Standards: All projects use the same rules and conventions
5. Lightweight: Projects don't need to include the package in dependencies
Installation
$3
`bash
npm install -g git+https://github.com/TonyCasey/ai-dotfiles-manager.git
Or install a specific version
npm install -g git+https://github.com/TonyCasey/ai-dotfiles-manager.git#v1.1.0
`
$3
`bash
npm install -g ai-dotfiles-manager
`
$3
For teams without npm infrastructure:
`bash
Clone to shared drive
git clone https://github.com/TonyCasey/ai-dotfiles-manager.git /shared/dev-tools/ai
Each developer installs from there
npm install -g /shared/dev-tools/ai
`
$3
`bash
ai-dotfiles-manager --version
ai-dotfiles-manager --help
`
How It Works
$3
All rules are centralized in .dev/rules/ and referenced by all AI tools:
`bash
After running "ai-dotfiles-manager setup":
~/projects/my-project/.dev/rules/
├── shared/ # Language-agnostic rules (managed copies)
│ ├── clean-architecture.md
│ ├── repository-pattern.md
│ └── testing-principles.md
├── typescript/ # Language-specific rules (managed copies)
│ ├── coding-standards.md
│ └── testing.md
└── .local/ # Project-specific overrides
├── custom-api-standards.md
└── architecture.md # Override shared rules
`
Why centralized?
- ✅ Single source of truth - no duplication across providers
- ✅ Update once, applies to all AI tools
- ✅ Consistent rules across Claude Code, Cursor, Kilo Code, Roo Code
- ✅ Easier maintenance and management
$3
Each AI tool has minimal configuration pointing to .dev/rules/ (no per-provider rule folders):
`bash
.gemini/settings.json # Points to ../.dev/rules/
.claude/settings.json # Points to ../.dev/rules/
.cursorrules # References ../.dev/rules/ files
.kilocode/config.json # Points to ../.dev/rules/
.roo/config.json # Points to ../.dev/rules/
`
Benefits:
- ✅ Provider folders still exist for tool-specific features
- ✅ All rules load from centralized location (shared)
- ✅ No more duplicated or shortcut rule folders in providers
- ✅ Easy to maintain and update
$3
Claude Code hooks automatically manage your workflow:
`bash
.claude/hooks/
├── session-start.js # Runs when Claude Code session starts
├── session-end.js # Runs when Claude Code session ends
└── user-prompt-submit.js # Validates/enhances prompts (optional)
`
What they do:
- ✅ Auto-load .dev/rules/ into AI context on session start
- ✅ Display project context (architecture, todos, git status)
- ✅ Extract and track current task from todo.md
- ✅ Commit completed todo items automatically on session end
- ✅ Track session statistics and duration
- ✅ Validate prompts for destructive operations (optional)
- ✅ Suggest relevant context files (optional)
$3
- Uses managed copies for all base rules (no symlinks required)
- No special permissions needed
Developer Workspace (.dev/)
The .dev/ folder is your personal developer workspace that's automatically loaded into AI context for every session.
$3
architecture.md (auto-generated)
- Project structure overview
- Technologies and frameworks
- Architectural patterns
- Key principles
- Regenerated on setup/update
todo.md (your personal task list)
- Markdown checkboxes for tasks
- Simply check off [x] when complete
- AI sees your current priorities
- Helps AI provide contextual suggestions
README.md (auto-generated)
- Explains the .dev/ concept
- Usage instructions
$3
All .md files in .dev/ are automatically loaded into AI context when you start a session with:
- Gemini CLI
- Claude Code
- Cursor
- Kilo Code
- Roo Code
This gives AI assistants immediate understanding of:
- What you're working on (todo.md)
- How the project is structured (architecture.md)
$3
`markdown
Developer Todo List
Current Sprint
- [ ] Implement user authentication
- [ ] Add password reset functionality
- [x] Set up database schema
Backlog
- [ ] Add email notifications
- [ ] Implement rate limiting
`
Simply change [ ] to [x] when done - no explanations needed!
$3
The .dev/ folder is personal and typically not committed:
`gitignore
.dev/
`
However, you can commit it to share architecture notes or tasks with your team.
Multi-Language Support
The package supports multiple programming languages with language-specific and language-agnostic rules.
$3
- TypeScript (fully supported)
- Python (planned - Phase 2)
- Go (planned - Phase 3)
- Java (planned - future)
- Rust (planned - future)
$3
`
templates/
├── shared/ # Language-agnostic rules
│ └── rules/
│ ├── clean-architecture.md # Universal architecture principles
│ ├── solid-principles.md # Universal SOLID patterns
│ └── repository-pattern.md # Universal data access pattern
│
├── languages/ # Language-specific rules
│ ├── typescript/
│ │ └── rules/
│ │ ├── coding-standards.md # TS naming, types, etc.
│ │ ├── testing.md # Jest, ts-jest patterns
│ │ └── tooling.md # TSC, ESLint, etc.
│ ├── python/ (coming soon)
│ ├── go/ (coming soon)
│ └── java/ (coming soon)
│
└── tools/ # Tool-specific configs
├── claude/
├── cursor/
├── kilocode/
└── roo/
`
$3
The setup wizard automatically detects your project language:
`javascript
// TypeScript: tsconfig.json or typescript in package.json
// Python: requirements.txt, pyproject.toml, setup.py
// Go: go.mod
// Rust: Cargo.toml
// Java: pom.xml, build.gradle
`
$3
TypeScript:
`typescript
// Interface in domain/interfaces/
export interface IProductRepository {
getById(id: string): Promise;
}
// Implementation in infrastructure/repositories/
export class ProductRepository implements IProductRepository {
constructor(private readonly db: IDatabase) {}
}
`
Python (coming soon):
`python
Protocol in domain/interfaces/
from typing import Protocol
class ProductRepositoryProtocol(Protocol):
def get_by_id(self, id: str) -> Product:
...
Implementation in infrastructure/repositories/
class ProductRepository:
def __init__(self, db: DatabaseProtocol):
self._db = db
`
Go (coming soon):
`go
// Interface in domain/
type ProductRepository interface {
GetByID(ctx context.Context, id string) (*Product, error)
}
// Implementation in infrastructure/
type productRepository struct {
db Database
}
`
Commands
$3
Set up AI assistant configuration in the current project:
`bash
Interactive setup
ai-dotfiles-manager setup
Non-interactive setup (uses defaults)
ai-dotfiles-manager setup --yes
ai-dotfiles-manager setup -y
`
Interactive mode prompts will ask:
- Which language? (auto-detected, or choose manually)
- Which AI tools? (Gemini CLI, Claude Code, Cursor, Kilo Code, Roo Code, or ✨ Select All)
Non-interactive mode (--yes flag):
- Uses detected language (defaults to TypeScript if not detected)
- Configures Claude Code only
- Perfect for CI/CD pipelines and automated setups
Creates configuration files in your project directory.
Need to keep your own AGENTS.md content or skip Codex context artifacts? Append --no-codex-guide to omit .dev/codex-manifest.json, .dev/context-index.md, and the managed Codex guide block:
`bash
ai-dotfiles-manager setup --yes --no-codex-guide
`
$3
Update existing configuration with latest templates:
`bash
Interactive update
ai-dotfiles-manager update
Non-interactive update (uses defaults)
ai-dotfiles-manager update --yes
ai-dotfiles-manager update -y
`
Refreshes base rules (managed copies) while preserving your .local/ customizations.
By default, replaces existing files without creating backups for streamlined updates.
$3
Analyze codebase for Clean Architecture violations:
`bash
Basic review
ai-dotfiles-manager review
Detailed review (includes info-level messages)
ai-dotfiles-manager review --detailed
JSON output (for CI/CD integration)
ai-dotfiles-manager review --json
Skip Codex guide refresh (no manifest/index updates)
ai-dotfiles-manager review --detailed --no-codex-guide
`
What it checks:
- Layer Violations (domain importing infrastructure, etc.)
- Interface Conventions ('I' prefix, file naming)
- Repository Pattern (correct layers, DI)
- Service Pattern (constructor injection, layers)
- Domain Errors (extend DomainError)
- TypeScript Quality (no any types)
$3
`bash
ai-dotfiles-manager --version
`
$3
`bash
ai-dotfiles-manager --help
`
Slash Commands (Claude Code)
After setup, use these commands in Claude Code:
$3
Display current session status:
- Project name and time
- Loaded context (rules, architecture, todos)
- Current task from todo.md
- Git working directory status
- Beautifully formatted output
$3
Creates a repository following Clean Architecture:
- Repository interface in src/domain/interfaces/
- Domain error class (optional)
- Repository implementation in src/infrastructure/repositories/
- DI registration
- Comprehensive test file
$3
Creates an application service:
- Service interface in src/application/interfaces/
- Service implementation in src/application/services/
- DI registration
- Test file with mocked dependencies
$3
Creates a domain error:
- Error class extending DomainError in src/domain/errors/
- Export from error index
- Usage examples
$3
Generates test files:
- Proper test structure
- Mock dependencies setup
- Test cases for all methods
- Error case tests
Customization
$3
Create new files in .dev/rules/.local/:
`bash
.dev/rules/.local/
├── custom-api-standards.md
└── database-conventions.md
`
These custom rules are automatically loaded by all AI tools alongside the base rules.
$3
Create a file with the same name in .local/:
`bash
.dev/rules/.local/
└── architecture.md # Overrides shared/architecture.md
`
Your local version will take precedence over the base rule with the same name.
$3
See .dev/rules/.local/README.md (auto-generated) for detailed instructions.
Version Control
$3
`gitignore
Ignore base rules copied from the package
.dev/rules/shared/
.dev/rules/typescript/
.dev/rules/python/
.dev/rules/go/
.dev/rules/java/
Ignore provider configs (auto-generated from templates)
.claude/
.cursorrules
.kilocode/
.roo/
Commit local customizations
!.dev/rules/.local/
Ignore backups (created during migration)
.backup.
Ignore session state files (auto-generated)
.dev/.session-state.json
.dev/.session-stats.json
.dev/.prompt-log.jsonl
Developer workspace (personal - usually not committed)
.dev/todo.md
.dev/architecture.md
`
$3
- Base rules are managed copies → don't commit (teammates will run ai-dotfiles-manager setup)
- Local rules are yours → commit them (project-specific customizations)
- Everyone runs setup once, gets same base rules, sees your custom rules
Team Workflow
$3
`bash
Step 1: Install the tool globally
npm install -g git+https://github.com/TonyCasey/ai-dotfiles-manager.git
Step 2: Clone first project
git clone https://github.com/your-org/my-project.git
cd my-project
Step 3: Set up AI assistance
ai-dotfiles-manager setup
Step 4: Start coding!
The AI now knows all development standards
`
$3
`bash
Clone another project
git clone https://github.com/your-org/my-other-project.git
cd my-other-project
Set up AI (takes 10 seconds)
ai-dotfiles-manager setup
Start coding with same standards!
`
$3
`bash
Update the global tool
npm update -g ai-dotfiles-manager
Refresh projects
cd ~/projects/my-project && ai-dotfiles-manager update
cd ~/projects/my-other-project && ai-dotfiles-manager update
`
Quality Assurance
$3
The package includes a comprehensive test suite ensuring reliability and maintainability:
- 78+ Unit Tests - Comprehensive coverage of core functionality including hooks
- 100% Coverage - Language detection module fully tested
- Hook Testing - All Claude Code hooks have dedicated test suites
- SOLID Principles - Tests follow the same principles as production code
- Fast Execution - Full test suite runs in < 2 seconds
- CI/CD Ready - Proper exit codes and coverage reporting
`bash
Run the full test suite
npm test
Generate coverage report
npm run test:coverage
`
$3
- Dependency Injection - All modules accept dependencies for testability
- Pure Functions - Predictable behavior with no side effects
- TypeScript AST - Robust code analysis using TypeScript compiler API
- Error Handling - Graceful handling of edge cases and failures
- Documentation - JSDoc comments and comprehensive README
$3
- Tests are required for all new features
- Code reviews ensure quality and consistency
- Regular updates with latest best practices
- Community feedback drives improvements
Troubleshooting
$3
The global bin directory is not in PATH:
`bash
Find npm global bin directory
npm config get prefix
Add to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$(npm config get prefix)/bin:$PATH"
Reload shell
source ~/.zshrc
`
$3
To refresh base rules (managed copies) after upgrading the tool:
`bash
npm update -g ai-dotfiles-manager
ai-dotfiles-manager update
`
$3
This is intentional! Base rules are managed copies. To customize:
1. Create files in .dev/rules/.local/
2. See .dev/rules/.local/README.md for instructions
3. Your .local/ files take precedence over base rules
$3
If AI isn't following the rules:
1. Check .dev/rules/ directory exists and has content
2. Verify .claude/settings.json has correct rulesDirectory path (../.dev/rules)
3. Try explicitly referencing a rule file in your prompt
4. Restart your AI coding assistant
$3
If slash commands don't work:
1. Check .claude/commands/ directory exists
2. Verify settings.json has correct commandsDirectory path
3. Restart Claude Code
Architecture Overview
$3
`
src/
├── domain/ # Core business entities and interfaces
│ ├── errors/ # Domain error classes
│ └── interfaces/ # Repository interfaces, core service interfaces
├── application/ # Business logic and use cases
│ ├── interfaces/ # Service interfaces, use case configs
│ └── services/ # Service implementations
└── infrastructure/ # External concerns
├── di/ # Dependency injection container
├── repositories/ # Repository implementations
└── services/ # External API integrations
`
$3
1. Dependency Inversion: Dependencies flow inward (Infrastructure → Application → Domain)
2. Repository Pattern: All data access through repositories
3. Dependency Injection: Constructor injection for all dependencies
4. Interface Segregation: One focused interface per file
5. Domain Errors: Specific error classes with HTTP status codes
Contributing
We welcome contributions! Here's how to contribute:
$3
1. Fork and Clone the repository
2. Create a branch for your feature: git checkout -b feature/your-feature
3. Make your changes to files in templates/, lib/, or scripts/
4. Write tests for new functionality (see __tests__/ for examples)
5. Run the test suite to ensure everything passes: npm test
6. Test manually by running ai-dotfiles-manager setup in a test project
7. Commit your changes with a descriptive message
8. Submit a pull request with a clear description of the changes
$3
- All new features must include unit tests
- Tests should follow the AAA pattern (Arrange, Act, Assert)
- Aim for at least 70% code coverage on new code
- Run npm test before submitting PR
$3
- Follow SOLID principles
- Use dependency injection for testability
- Write pure functions where possible
- Add JSDoc comments for public APIs
- Follow existing code style
Development
$3
`
ai-dotfiles-manager/
├── bin/
│ └── setup.js # CLI setup tool
├── lib/
│ └── language-detector.js # Language detection module (testable)
├── scripts/
│ └── review.js # Code review engine
├── templates/
│ ├── shared/ # Language-agnostic rules
│ │ └── rules/
│ ├── languages/ # Language-specific rules
│ │ ├── typescript/rules/
│ │ └── python/rules/
│ ├── dev/ # .dev/ workspace templates
│ ├── claude/ # Claude Code config + hooks
│ │ ├── hooks/
│ │ ├── commands/
│ │ └── settings.json
│ ├── cursor/ # Cursor config
│ ├── kilocode/ # Kilo Code config
│ └── roo/ # Roo Code config
├── __tests__/
│ ├── helpers/ # Test utilities (fs-mock, etc.)
│ ├── fixtures/ # Test data and sample structures
│ ├── hooks/ # Tests for Claude Code hooks
│ ├── lib/ # Tests for lib modules
│ ├── scripts/ # Tests for scripts
│ ├── setup.js # Jest setup
│ └── README.md # Testing documentation
├── jest.config.js # Jest configuration
├── package.json
└── README.md
`
$3
The package includes a comprehensive test suite with 78+ tests following SOLID principles:
`bash
Run all tests
npm test
Run tests with coverage
npm run test:coverage
Run tests in watch mode
npm run test:watch
Run tests with verbose output
npm run test:verbose
`
Test Coverage:
- Language Detector: 100% ✅
- Claude Code Hooks: 100% ✅
- Code Reviewer: 27.82%
- Overall: 5 test suites, 78 passing tests
Testing Principles:
- AAA Pattern (Arrange, Act, Assert)
- Dependency Injection for testability
- Mock utilities for file system operations
- Pure functions with no side effects
- SOLID principles throughout
See __tests__/README.md for detailed testing documentation.
$3
`bash
Install dependencies
npm install
Link the package
npm link
Run tests
npm test
Test in a project
cd /path/to/test-project
ai-dotfiles-manager setup
Verify configuration is correct
`
$3
1. Create templates/languages/{language}/rules/
2. Add language-specific rules:
- coding-standards.md
- testing.md
- tooling.md
3. Add detection logic in lib/language-detector.js
4. Add tests in __tests__/lib/language-detector.test.js
5. Run tests to verify: npm test
6. Test with a project in that language
License
MIT License - See LICENSE file for details.
Changelog
$3
- Improved Package Update Flow - Streamlined updates and session management
- Made "replace existing" the default option during package updates (no backups)
- Added --yes / -y flag for non-interactive setup and updates
- Fixed hooks format in settings.json for new Claude Code hooks API
- Enhanced session-start hook with current task detection from todo.md
- Added /status slash command for on-demand session info display
- Improved visual formatting in session hooks with better banners
- Updated help documentation with non-interactive mode examples
$3
- Removed Redundant Code - Cleanup and optimization release
- Removed duplicate provider-specific rules folders (7,248 lines deleted)
- Removed unused .claude/rules/ setup code
- Single source of truth for all rules in .dev/rules/
- All providers consistently reference .dev/rules/
$3
- Claude Code Hooks System - Comprehensive hook implementation
- Added session-start.js - Loads context and displays session info
- Added session-end.js - Auto-commits todos and tracks statistics
- Added user-prompt-submit.js - Validates and enhances prompts (optional)
- Hooks located in templates/claude/hooks/ → .claude/hooks/
- Updated settings.json to reference .claude/hooks/
- Hook Testing - 25 new tests for hook functionality
- session-start.test.js (8 tests)
- session-end.test.js (8 tests)
- user-prompt-submit.test.js (12 tests)
- Test suite expanded from 53 to 78 tests
$3
- Added Migration Support - Graceful handling of existing AI configurations
- Detects existing .claude/, .cursorrules, .kilocode/, .roo/ configurations
- Offers 4 migration options: supersede, preserve, replace, or skip
- Automatically moves existing files to .local/ directories
- Creates timestamped backups when replacing configurations
- Special handling for .cursorrules single-file migration
- Added Comprehensive Test Suite - Enterprise-grade testing infrastructure
- 53+ tests following SOLID principles and best practices
- AAA pattern (Arrange, Act, Assert) throughout
- Mock utilities for file system operations
- 100% coverage on language-detector module
- Jest configuration with coverage thresholds
- Dependency injection for testability
- Refactored for Testability - Extracted pure functions
- Created lib/language-detector.js module
- Applied dependency injection pattern
- Improved code maintainability
- Updated .gitignore recommendations to include backup directories and test coverage
$3
- Added .dev/ Developer Workspace - Personal workspace auto-loaded into AI context
- architecture.md - Auto-generated project overview (structure, technologies, patterns)
- todo.md - Personal task list with markdown checkboxes
- Automatically loaded by all AI tools (Claude Code, Cursor, Kilo Code, Roo Code)
- Provides immediate project context for AI assistants
- Updated all AI tool configurations to load .dev/ files on session start
- Enhanced project analysis for better architecture.md generation
- Added framework detection (Next.js, React, Express, NestJS, etc.)
- Updated .gitignore recommendations to include .dev/
$3
- Added "Select All" option for tool selection
- Added update command for updating existing configurations
- Switched to managed copies for consistency
- Added .local/ directories for project-specific customizations
- Base rules treated as managed sources (edit via .local overrides)
- Auto-generate README.md in .local/ directories with instructions
- Renamed package from ai-dev-standards to ai-dotfiles-manager
- Enhanced Windows support with junctions (no admin required for directories)
- Added Kilo Code support with comprehensive rule templates
- Added Roo Code support with comprehensive rule templates
- Added review` command for automated architecture violation detection