Skip to Content
00 Getting StartedFAQ

Frequently asked questions

General

What is AlignTrue?

AlignTrue is a tool that syncs AI coding rules across multiple agents. Write rules once in AGENTS.md or any agent file, and AlignTrue keeps them synced across Cursor, GitHub Copilot, Claude Code, and 25+ other agents.

Why do I need AlignTrue?

If you use multiple AI coding agents, you’re probably copy-pasting rules between different config formats. AlignTrue eliminates this by maintaining a single source of truth and syncing to all agents automatically.

Is AlignTrue free?

Yes! AlignTrue is MIT-licensed open source. The CLI and all core features are free forever.

What agents does AlignTrue support?

28+ agents through 43 specialized exporters:

  • Cursor, GitHub Copilot, Claude Code, Aider, Windsurf
  • VS Code MCP, Amazon Q, Firebase Studio, OpenHands, Zed
  • And 18+ more

View full compatibility matrix →

Getting started

How long does setup take?

Under 60 seconds:

npx aligntrue init  # Auto-detects agents, creates config
aligntrue sync      # Generates agent files

Do I need to install anything?

Just Node.js 22+ and the AlignTrue CLI:

bash npm install -g @aligntrue/cli

What if I already have agent configs?

AlignTrue can import existing configs:

aligntrue init  # Detects existing configs, offers import

See Migration guide for details.

Usage

Where do I write rules?

In AGENTS.md or any agent-specific file (.cursor/*.mdc, etc.). AlignTrue keeps them all synced. The .aligntrue/.rules.yaml file is internal and auto-generated - don’t edit it directly.

How do I sync rules to agents?

aligntrue sync

This generates agent-specific files like .cursor/rules/*.mdc, AGENTS.md, etc.

Can I edit agent files directly?

Yes! AlignTrue supports two-way sync in solo mode:

  • AGENTS.md (universal format)
  • Agent files like .cursor/*.mdc (agent-specific)

In solo mode, auto-pull is enabled by default, so changes flow both directions. In team mode, manually pull changes with aligntrue sync --accept-agent. See Workflows guide for details.

Do I need to run sync every time?

Only when rules change. Set up auto-sync with file watchers if you want automatic syncing on save.

See File watcher setup.

What if I have conflicts?

AlignTrue detects conflicts when multiple agent files have different changes. You’ll be prompted to choose which version to keep.

Configure primary agent to avoid prompts:

# .aligntrue/config.yaml
sync:
  primary_agent: "agents-md" # Use AGENTS.md as source
  # or "cursor"  # Use Cursor files as source
  auto_pull: true # Pull from primary before syncing

Team usage

Can teams use AlignTrue?

Yes! Enable team mode for lockfiles, drift detection, and allow lists:

aligntrue team enable

See Team mode guide.

How do teams share rules?

Three ways:

  1. Git - Commit .aligntrue/ directory to your repo
  2. Git sources - Pull rules from separate repository
  3. Vendoring - Use git submodules/subtrees

See Git workflows.

What’s a lockfile?

A lockfile (.aligntrue.lock.json) pins rule versions with SHA-256 hashes. Teams use lockfiles to ensure everyone has identical rules.

What’s drift detection?

Drift detection monitors when upstream rules change. Useful for teams pulling rules from external sources.

aligntrue drift --gates  # Fail CI if drift detected

See Drift detection guide.

Multi-agent usage

Can I use AlignTrue with multiple agents at once?

Yes! AlignTrue is designed for multi-agent workflows. Configure multiple exporters:

exporters:
  - cursor
  - agents-md
  - claude-md
  - copilot
  - windsurf

Run aligntrue sync once and all agents get the same rules.

See Multi-Agent Workflows guide.

How do I maintain different settings per agent?

Use vendor bags for agent-specific metadata:

rules:
  - id: example-rule
    summary: Example
    vendor:
      cursor:
        ai_hint: "Cursor-specific hint"
      claude:
        mode: "assistant"

See Vendor Bags reference.

Should I use solo or team mode?

Solo mode for individual developers - fast, simple, no overhead.

Team mode for collaborative projects - lockfiles, drift detection, reproducible builds.

See Solo vs. team mode for detailed comparison.

Technical

Does AlignTrue require network access?

No! AlignTrue works completely offline. Network access is only needed for:

  • Pulling rules from git repositories (optional)

You’ll be prompted for consent before any network operation.

Where does AlignTrue store data?

  • Config: .aligntrue/config.yaml
  • Rules (internal): .aligntrue/.rules.yaml (auto-generated)
  • Rules (user-editable): AGENTS.md or agent files
  • Lockfile: .aligntrue.lock.json (team mode)
  • Cache: .aligntrue/.cache/ (git sources)

Can I use AlignTrue in CI?

Yes! Validate rules in CI:

aligntrue check --ci  # Schema validation
aligntrue drift --gates  # Drift detection

See CI/CD integration guide.

What’s the IR (Intermediate Representation)?

The IR is AlignTrue’s internal format stored in .aligntrue/.rules.yaml. When you write rules in AGENTS.md or agent files, they’re converted to IR, then synced to all other agents. The IR file is auto-generated - you don’t need to edit it directly.

How does AlignTrue handle agent-specific features?

Agent-specific features are preserved in the vendor.* namespace:

vendor:
  cursor:
    session: "my-session"

These fields are excluded from hashing but preserved on round-trips.

Troubleshooting

AlignTrue command not found

Install globally:

bash npm install -g @aligntrue/cli

Config file not found

Run init first:

aligntrue init

Rules not showing in my agent

  1. Check agent is enabled: cat .aligntrue/config.yaml | grep exporters
  2. Run sync: aligntrue sync
  3. Restart your IDE

Lockfile always out of sync

Mark volatile fields in config:

vendor:
  _meta:
    volatile: ["cursor.timestamp"]

More issues?

See Troubleshooting guide for comprehensive solutions.

Privacy & security

Does AlignTrue collect telemetry?

Only if you opt in. Telemetry is disabled by default:

aligntrue telemetry status  # Check status
aligntrue telemetry on      # Enable (optional)

See Privacy policy.

What data is collected (if enabled)?

  • Command names (init, sync, check)
  • Export targets (cursor, agents-md)
  • Rule hashes (SHA-256, no content)
  • Anonymous UUID

Never collected:

  • File paths or repo names
  • Code or rule content
  • Personal information

Can I use AlignTrue with private rules?

Yes! AlignTrue works completely offline. Your rules never leave your machine unless you explicitly push to git or enable telemetry.

Is AlignTrue secure for enterprise use?

Yes:

  • Local-first (no cloud required)
  • MIT license (permissive)
  • Deterministic hashing (SHA-256)
  • Audit trails (git integration)
  • No external dependencies at runtime

See Security policy.

Contributing

Can I add support for my agent?

Yes! See Adding exporters guide.

Can I contribute rule packs?

Yes! See Creating packs guide.

Where do I report bugs?

GitHub Issues 

Where do I ask questions?

GitHub Discussions 

Still have questions?

Last updated on
Solo vs. team modeAuto-pull behavior