Skip to Content
00 Getting StartedQuickstart

Quickstart guide

Get AlignTrue running in under 60 seconds. No prior knowledge required.

What is AlignTrue?

AlignTrue helps you control how AI coding assistants behave in your project. You write rules once in a simple format, and AlignTrue converts them into each agent’s specific format automatically.

Key terms:

  • Rules - Guidelines that tell AI agents how to work in your project (e.g., “use TypeScript strict mode”)
  • Sync - Convert your rules into agent-specific formats (like .cursor/rules/*.mdc or AGENTS.md)
  • Agents - AI coding assistants like Cursor, GitHub Copilot, Claude Code, etc.

The two-step workflow

AlignTrue’s workflow is simple:

  1. Initialize (aligntrue init)

    • Detects installed agents (Cursor, Copilot, Claude Code, etc.)
    • If existing rules found: Offers to import them
    • If no rules found: Creates AGENTS.md starter template
    • Creates .aligntrue/config.yaml and .aligntrue/.rules.yaml (internal)

  2. Sync (aligntrue sync)

    • Converts rules to agent-specific formats
    • Generates .cursor/rules/*.mdc, .vscode/mcp.json, etc.
    • Keeps everything aligned when you make changes

The key decision: AGENTS.md is your primary editing file. The .aligntrue/.rules.yaml file is auto-generated - don’t edit it directly.

Prerequisites

Installation

bash npm install -g aligntrue

Which mode should I use?

AlignTrue has two modes optimized for different workflows:

ModeBest forKey features
SoloIndividual developersFast iteration, auto-pull, no lockfile overhead
TeamCollaborative projectsLockfile, drift detection, approved sources

Default: Solo mode (perfect for getting started)

Need help deciding? See Solo vs. team mode for detailed comparison.

Quick start (60 seconds)

Initialize a new configuration:

aligntrue init

This creates .aligntrue/config.yaml, .aligntrue/.rules.yaml (internal), and AGENTS.md with:

  • Configuration file with your org/user namespace and default exporters
  • Internal IR file (auto-generated from your rules)
  • AGENTS.md starter template with example rules

Sync your first export:

aligntrue sync

This creates .cursor/rules/*.mdc files ready for Cursor.

2. Customize your rules

Open AGENTS.md and edit the starter rules for your project:

# AGENTS.md
 
## Rule: use-typescript-strict
 
**ID:** use-typescript-strict
**Severity:** ERROR
**Scope:** **/\*.ts, **/\*.tsx
 
Enable strict mode in tsconfig.json for better type safety.

The starter template includes examples for:

  • Code style enforcement
  • Testing requirements
  • Documentation standards
  • Security practices

3. Sync to your agents

Run this command (in your project directory) to generate agent-specific files:

aligntrue sync

What this does: Converts your rules from AGENTS.md (or agent files) into formats that each AI agent understands.

Example output:

◇ Loading configuration...
◇ Parsing rules...
◇ Syncing to 2 agents...
│
◆ Files written:
│  • .cursor/rules/aligntrue.mdc (3 rules)
│  • AGENTS.md (3 rules)
│
◇ Sync complete! No conflicts detected.

What you get

After running aligntrue sync, you’ll have agent-specific rule files:

For Cursor:

  • .cursor/rules/aligntrue.mdc - Rules in Cursor’s native format

For GitHub Copilot, Claude Code, Aider, and others:

  • AGENTS.md - Universal markdown format

For VS Code with MCP:

  • .vscode/mcp.json - Model Context Protocol configuration (if enabled)

Enabling rules in your agents

Cursor

  1. Open Cursor Settings (Cmd/Ctrl + ,)
  2. Navigate to Features > Cursor Rules
  3. Enable “Rules folder” option
  4. Restart Cursor to load rules from .cursor/rules/

GitHub Copilot / Claude Code / Aider

No setup needed! These agents automatically read AGENTS.md from your project root.

VS Code with MCP

  1. Install VS Code extension that supports MCP
  2. Extension will automatically detect .vscode/mcp.json
  3. Restart VS Code to load configuration

Windsurf

  1. Open Windsurf settings
  2. MCP configuration automatically loaded from .windsurf/mcp_config.json

Next steps

Want to try a working example first? See the Golden Repository Example  for a complete working demo.

Ready to learn more? Check out Next Steps for:

  • Auto-sync on save
  • Team collaboration features
  • Git-based rule sharing
  • Custom exporters

Run into issues? See Troubleshooting Guide for common solutions.

That’s it! You now have consistent AI rules across all your coding agents.

Basic workflow:

  1. Edit rules in AGENTS.md or any agent file
  2. Run aligntrue sync
  3. Your AI agents now follow your project’s standards

Next: Author your own rules

The starter template uses a simple markdown format. To author rules in fenced code blocks (literate markdown), see the Markdown authoring guide.

Last updated on
OverviewNext steps