Skip to Content
Getting startedQuickstart

Quickstart guide

Get AlignTrue running in under 60 seconds with two commands.

Prerequisites

Install AlignTrue

npm install -g aligntrue

Prefer a different package manager?

bash yarn global add aligntrue

Prefer the short alias? aln works for every command (e.g., aln init).

Alternative: Use npx for one-off commands without installing: npx aligntrue init

Quick start (2 commands)

1. Initialize

cd your-project
aligntrue init

This auto-detects any existing agent files (Cursor .mdc, CLAUDE.md, etc.) and lets you choose which ones to import:

  • Single file: Imported automatically without prompts
  • Small folder (2-10 files): Shows list with quick confirm
  • Large or multiple folders: Shows summary, lets you select folders

If no files are found, you’ll get a fresh AGENTS.md starter. After import, it writes:

  • .aligntrue/config.yaml - Configuration with detected exporters
  • .aligntrue/rules - Imported rules (your single source of truth)
  • Agent files - Updated in their native formats on next sync

Tip: By default, aligntrue init automatically runs aligntrue sync after initialization. If you use --no-sync, you can run sync manually later when you’re ready.

Want to start with external rules? Use aligntrue init --source <git-url> to import from GitHub, GitLab, SSH URLs, or local paths. See Working with external sources for all supported source formats.

2. Customize your rules

Edit rules in .aligntrue/rules/. Create .md files for your rule categories:

# Project rules
 
## Use TypeScript strict mode
 
Enable strict mode in tsconfig.json for better type safety. This catches more errors at compile time and makes refactoring safer.
 
Set these in tsconfig.json:
 
- noImplicitAny: true
- strictNullChecks: true
- strictFunctionTypes: true

That’s it! Save to .aligntrue/rules/typescript.md, then run aligntrue sync to export to all agents.

Where to edit: Only in .aligntrue/rules/ directory

Edit markdown files in .aligntrue/rules/. All agent files (Cursor .mdc, AGENTS.md, etc.) are read-only exports.

Data flow:

Edit files in .aligntrue/rules/
    ↓
aligntrue sync (loads rules, validates, exports)
    ↓
All agent files (read-only, auto-generated)

Important: Agent files are under AlignTrue’s control. Edits to agent files will be backed up and overwritten on the next sync. Always edit .aligntrue/rules/ instead.

Want automated sync? Use a pre-commit hook or editor integration. See the CI/CD integration guide.

What you get

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

For Cursor:

  • .cursor/rules/*.mdc - Rules in Cursor’s native format (one file per rule)

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)

Verify it works

Let’s confirm your agent is using the rules:

Cursor verification

  1. Open Cursor Settings (Cmd/Ctrl + ,)
  2. Navigate to Features > Cursor Rules
  3. Enable “Rules folder” option (if not already enabled)
  4. Restart Cursor
  5. Open a file and start a chat
  6. Ask: “What are the TypeScript rules for this project?”
  7. Cursor should reference your rules from AGENTS.md

Expected: Cursor responds with your project’s rules

Problem? See the troubleshooting guide.

GitHub Copilot / Claude Code verification

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

  1. Open a file
  2. Start typing code that might violate a rule
  3. Watch for suggestions that follow your rules

Problem? Make sure AGENTS.md exists in your project root:

ls -la AGENTS.md  # Should show the file

Common issues

Rules not showing in my agent:

  1. Verify files were created: ls .cursor/rules/ or ls AGENTS.md
  2. Restart your IDE completely
  3. Check agent settings to ensure rules are enabled
  4. Run aligntrue sync again to regenerate files

Still not working? See the troubleshooting guide.

Need deeper checks (VS Code MCP, Windsurf, Warp, etc.)? See the agent verification guide.

How it works

AlignTrue uses a simple three-step process:

  1. Write rules - Edit .aligntrue/rules/*.md (single source of truth)
  2. Generate exports - AlignTrue validates and converts to internal IR
  3. Sync to agents - Agent files (including AGENTS.md) are generated in their native formats (.cursor/*.mdc, AGENTS.md, etc.)

Workflow:

.aligntrue/rules (you edit) → AlignTrue IR → Agent exports (read-only, includes AGENTS.md)

Key concepts:

  • Rules - Guidelines for AI agents (e.g., “use TypeScript strict mode”)
  • Sync - Convert rules into each agent’s native format
  • Agents - AI coding assistants (Cursor, Copilot, Claude Code, etc.)

See the Glossary for complete terminology.

Next steps

Learn more:

Examples:

See also

Enable team mode (optional)

For teams that need governance and approval workflows:

aligntrue team enable
# Enables lockfile + team workflow
# Shows configuration summary

This enables:

  • Lockfile generation (deterministic bundle hash)
  • Bundle approval workflow
  • Optional team-managed sections
  • CI drift detection

See Team mode guide for details.

Need help?

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

Last updated on
IntroductionNext steps