⚠️ Alpha Status: This project is in active development. Most core features work well, but expect API changes before 1.0. Use for development/internal projects first. If you find issues create an issue or PR.

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

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 other popular agents, exporting to each in its native format.

Start with existing rules? Import from any git source:

aligntrue init https://github.com/org/rules

Supports GitHub, GitLab, SSH URLs, version tags, and local paths. See all source options →

→ Verify it works | Solo guide

Common workflows

Solo developer (default):

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

Solo developer (external source):

aligntrue init --source https://github.com/your/rules
aligntrue sync

Import rules from GitHub. Use aligntrue add link <url> to keep a connected source for ongoing updates; use aligntrue add <url> for a one-time import. More examples →

Team mode (opt-in):

aligntrue team enable  # Enable team mode (creates lockfile)
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 migrate command for details.

Why AlignTrue

• Auto-detects and imports - Finds common agents automatically and 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 + safety - --dry-run previews changes; backups, validation, and deterministic exports keep outputs consistent (see Features for details)

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
Multi-layer safety	Mandatory workspace backups, individual file 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 other popular agents automatically	How it works
Broad coverage	Native exporters for many AI coding agents	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, multi-file exports)	Agent Support
Per-exporter config	Control ignore file generation and format options per agent	Export Formats
.alignignore protection	Protect files from modifications using gitignore-style patterns	Features
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 Aligns for safe fork-resistant customization	Customization
Scopes	Hierarchical rules for monorepos and complex projects	Scopes
Export format options	Choose native multi-file or AGENTS.md format per agent	Export Formats
Per-rule targeting	Control which agents receive specific rules via frontmatter	Per-Rule Targeting
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
Structure Preservation
Import structure	Recursive scanning preserves filenames and directory organization during import	Working with external sources
Export structure	Multi-file exporters mirror .aligntrue/rules/ subdirectory structure	Solo guide or Team guide
Safety & Reliability
Built-in safety	Mandatory backups with quick rollback via aligntrue revert	Backup & Restore
Deterministic exports	Schema validation and reproducible hashing keep outputs stable	Features

Broad agent support

AlignTrue supports a wide range of AI coding agents with native 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 more

View the full compatibility matrix →

How it works

1. AlignTrue detects your agents - Finds Cursor, Copilot, Claude Code, and 30+ 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

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 →

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 Aligns

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 Aligns - Author and publish rule Aligns
• 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 Aligns
• 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.