⚠️ 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 --source 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, GitLab, or any git repository. Use aligntrue add source <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

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 )