agnostic-ai

Type to search the docs and updates.

Browse documentation
DocsDocumentation

Getting started

Install agnostic-ai and bring your AI coding tool setup into one source directory.

Quickstart

From your project root, with Node 18 or newer:

npm install -g agnostic-ai
agnostic-ai init --from all
agnostic-ai sync --plan
agnostic-ai sync

init --from all creates agnostic-ai.yaml and imports any existing tool files into .agnostic-ai/. Pick the tools you use when prompted. Without a terminal, init selects the tools it detects, or its default set when it finds none. sync --plan previews the changes. sync writes the native files.

For other installers, see Installation. To review an existing setup before generating files, see Migration. Already use one tool and want another? Run agnostic-ai use codex (see use).

First rule

Add a rule to the setup:

agnostic-ai new rule conventional-commits

Replace .agnostic-ai/rules/conventional-commits.md with:

---
name: conventional-commits
description: Use Conventional Commits.
alwaysApply: true
---

Use feat:, fix:, docs:, refactor:, test:, or chore: prefixes.
Keep the subject under 72 characters.

Run agnostic-ai sync again. With Claude Code and Cursor selected, the rule lands in:

OutputPurpose
.claude/rules/conventional-commits.mdClaude Code rule
.cursor/rules/conventional-commits.mdcCursor rule

Write shared project instructions in .agnostic-ai/AGNOSTIC_AI.md. Sync creates this file once and keeps your edits. Edit sources under .agnostic-ai/, then sync again. To change tools, edit targets: in agnostic-ai.yaml (target selection).

Commit or ignore generated outputs

init asks. Without a terminal, or with --all, it ignores them.

  • Ignore (default): Git holds only .agnostic-ai/, agnostic-ai.yaml, and .gitignore. Every teammate installs the tool and runs agnostic-ai sync after cloning. Checkout hooks can run it for them. CI validates and generates instead of comparing.
  • Commit (init --gitignore=off): a clone works without the tool. Add the CI drift gate to keep files current. To switch an existing project, see gitignore.

Daily use

Run agnostic-ai sync --watch while you edit specs. Run agnostic-ai status to see loaded specs, tools, and drift. Run agnostic-ai sync --check after a sync or in CI to catch drift.

Next steps