Introduction

Instantly sync rules across agents, people, projects and teams. Start in 60 seconds.

Write rules once in markdown. Sync everywhere. Stay aligned.

• Solo developers: Keep your personal AI rules consistent across projects and machines.
• Teams: Shared rule sets with version control, CI validation, and drift detection.

Solo developer? Start here

Get started in 60 seconds:

npm install -g aligntrue
aligntrue init
aligntrue sync

Auto-detects agents, imports existing rules, or creates AGENTS.md. Generates and updates each agent's native files (Cursor, AGENTS.md, VS Code, etc.).

Edit rules in .aligntrue/rules/. AlignTrue works seamlessly with Cursor, GitHub Copilot, Claude Code, and 28+ agents, automatically exporting to each in their native format.

→ Verify it works | Solo guide

Why AlignTrue

• Auto-detects and imports - Discovers 28+ agents automatically, imports existing rules from Cursor, AGENTS.md, Claude, and more
• 60-second setup with zero config - Run aligntrue init and AlignTrue handles agent detection and rule import
• Single source of truth - Edit rules in .aligntrue/rules/; changes sync to all agents automatically
• Preview before applying - --dry-run mode shows exactly what will change
• Three-layer safety with one-command rollback - Mandatory workspace backups, overwritten-rules backup, section-level preservation, and aligntrue revert with diff preview

Built for reliability

Enterprise-grade validation and determinism:

• TypeScript 5+ strict mode - Comprehensive type coverage across the entire codebase
• JSON Schema 2020-12 validation - All IR and config validated with Ajv strict mode
• 1800+ deterministic tests - Vitest + Playwright with reproducible, seed-controlled execution
• Canonical JSON hashing - JCS-based reproducible hashing for lockfiles and integrity verification
• Atomic operations - Safe file writes prevent corruption across sync operations
• Multi-layer safety - Mandatory workspace backups, overwritten-rules backup, and section-level preservation ensure no work is lost

Why this matters: AlignTrue validates every operation against schemas and ensures byte-identical outputs for identical inputs. Your AI agent configurations are never corrupted, even during concurrent syncs or network failures. Multiple safety layers protect against data loss.

Features

Complete feature matrix

Feature	Description	Learn more
Core Sync
Centralized editing	Edit your configured edit source file; AlignTrue keeps everything aligned	Sync Behavior
Dry-run mode	Preview changes before applying with --dry-run	Basic Commands
Watch mode	Continuous file watching with auto-sync on changes	Basic Commands
Multi-layer safety	Mandatory workspace backups, overwritten-rules backup, and section-level preservation	Backup & Restore
Atomic operations	Safe file writes prevent corruption during syncs	Features
Agent Support
Auto-detection	Finds Cursor, Copilot, Claude, VS Code, and 25+ others automatically	How it works
28+ agents	Comprehensive coverage through 50 exporters	Agent Support
Unidirectional sync	Edit in .aligntrue/rules/, sync to all agents automatically	Getting Started
Multi-format support	Agent-optimized formats (.mdc, AGENTS.md, MCP configs, and more)	Agent Support
Team Collaboration
Lockfiles	Pin rule versions with .aligntrue.lock.json for reproducible builds	Team Mode
Drift detection	Compare lockfile vs allowed sources with multiple output formats	Drift Detection
CI validation	Built-in commands for CI/CD pipelines with aligntrue check and aligntrue drift	CI/CD Integration
Customization
Plugs	Dynamic value slots with validation for flexible rules	Customization
Overlays	Surgical modifications to packs for safe fork-resistant customization	Customization
Scopes	Hierarchical rules for monorepos and complex projects	Scopes
Developer Experience
.gitignore automation	Smart management of generated files	Git Workflows
Verbose output	Detailed execution logs with --verbose flag	CLI Reference
Ruler migration	Auto-detect and convert from Ruler	Features
Backup & restore	Selective file restoration with diff preview via aligntrue revert	Backup & Restore
Safety & Reliability
Multi-layer safety	Mandatory workspace backups, overwritten-rules backup, section-level preservation	Safety Guide
Easy recovery	Quick rollback with aligntrue revert showing preview and diff	Backup & Restore
1800+ tests	Vitest + Playwright with reproducible, seed-controlled execution	Architecture
JSON Schema validation	All IR and config validated with Ajv strict mode	Features
Deterministic hashing	JCS-based reproducible hashing for lockfiles and integrity	Features
TypeScript strict mode	Comprehensive type coverage across the entire codebase	Features

Add to your workflow

Integrate AlignTrue into your development and CI/CD pipelines in seconds. Use validation gates, precommit hooks, and automated checks.

NPM scripts (precommit hooks):

{
  "scripts": {
    "aligntrue:check": "aligntrue check --ci",
    "aligntrue:drift": "aligntrue drift --gates",
    "aligntrue:sync": "aligntrue sync",
    "precommit": "aligntrue check --ci"
  }
}

GitHub Actions:

# .github/workflows/aligntrue-check.yml
name: AlignTrue Validation
on: [pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - run: npm install -g aligntrue
      - run: aligntrue check --ci
      - run: aligntrue drift --gates

View solo developer guide →

Broad agent support

AlignTrue supports 28+ AI coding agents through 50 exporters:

Popular agents:

• Cursor (.mdc files)
• GitHub Copilot (AGENTS.md)
• Claude (AGENTS.md + CLAUDE.md)
• Aider (AGENTS.md + .aider.conf.yml)
• Windsurf (AGENTS.md + MCP config)
• VS Code MCP agents
• Amazon Q, Firebase Studio, OpenHands, Zed, and 20+ more

Coverage:

• 50 total exporters supporting 28+ agents
• 14 MCP configurations for protocol-based agents
• 15 unique format exporters for agent-specific formats
• 11 universal format agents using AGENTS.md
• 9 dual-output agents with both universal + specific formats

View full agent compatibility matrix →

How it works

1. AlignTrue detects your agents - Finds Cursor, Copilot, Claude Code, and 28+ others automatically
2. Edit in .aligntrue/rules/ - Create and edit markdown files with your rules
3. Run sync - AlignTrue exports to all agents in their native formats
4. Stay aligned - All agents receive identical rules automatically

Common workflows

Solo developer (default):

aligntrue init    # One-time setup
aligntrue sync    # Update agents when rules change

Team mode (opt-in):

aligntrue lock    # Pin rule versions
aligntrue check   # Validate in CI

Centralized editing:

• Edit rules in .aligntrue/rules/ → sync to all agents
• All agent files are read-only exports

See guides for details.

Optional verification:

aligntrue sync --dry-run       # Preview changes
aligntrue check                # Validate rules (great for CI)

Migrating from Ruler:

aligntrue migrate ruler        # Convert Ruler config to AlignTrue
aligntrue sync                 # Sync to all agents

See migration guide for details.

Who is this for?

Solo developers: Keep your personal AI rules consistent across projects and machines

Teams: Shared rule sets with version control, CI validation, and drift detection

Key concepts

• Quickstart - Get AlignTrue running in 60 seconds
• Glossary - AlignTrue terminology and key concepts explained
• Customization - Plugs, overlays, and scopes for fork-safe customization
• Team Mode - Collaboration features for teams
• Sync Behavior - How centralized rule management works
• Drift Detection - Track alignment changes over time
• Git Workflows - Pull and share rules via git
• Examples - Browse 11 curated rule packs

Reference

• CLI Commands - Complete command reference
• Concepts - Understand AlignTrue terminology
• Troubleshooting - Common issues and solutions

Contributing

Want to contribute? Check out the guides:

• Getting Started - Set up your development environment
• Creating Packs - Author and publish rule packs
• Adding Exporters - Add support for new agents

Development

Setting up AlignTrue for local development:

• Setup - Prerequisites and installation
• Workspace - Monorepo structure and packages
• Commands - Development commands and scripts
• Architecture - Key architectural concepts

Learn more

• GitHub repository
• Examples - Browse 11 curated rule packs
• Security policy

Support

• GitHub Issues
• Discussions

License

MIT (see LICENSE)

---

This file is auto-generated from the AlignTrue documentation site. To make changes, edit the source files in apps/docs/content/ and run pnpm generate:repo-files.