agnostic-ai

One spec. Every AI CLI. Zero drift.

Write your agents, skills, rules, and hooks once. Ship them to Claude Code, Codex, Gemini, Cursor, Copilot, and 9 more in their native format.

---

Why

You write CLAUDE.md. Then .cursor/rules. Then GEMINI.md. Then AGENTS.md. Same content, four formats. Switch tools and you rewrite everything.

agnostic-ai keeps one source of truth in plain Markdown plus YAML frontmatter, aligned with the AGENTS.md open standard. Run sync and every tool gets the config it expects, in its native location, byte-stable across runs.

• Stateless adapters. Same input, same output. Diffable, reviewable.
• Uniform entry-point. One pointer body shared across every target's root file.
• Round-trip safe. Provenance marker plus style preservation keeps import then sync byte-stable.
• Scoped rules. rules/backend/auth.md routes to .cursor/rules/backend/auth.mdc and .github/instructions/auth.instructions.md with applyTo: backend/**.

How it works

Drop one file in .agnostic-ai/rules/conventional-commits.md:

---
name: conventional-commits
description: Always use Conventional Commits format.
globs: "**/*"
alwaysApply: true
---

Use Conventional Commits. Subject under 72 chars. Body explains why, not what.

Run agnostic-ai sync. Two layers emit per target:

1. Slim entry-point at the project root, body shared across targets. CLAUDE.md, AGENTS.md (Codex / Amp / Warp), GEMINI.md, CONVENTIONS.md, .github/copilot-instructions.md, .agnostic-ai/AGNOSTIC_AI.md all carry the same pointer:

# AI Project Conventions

This file is regenerated by agnostic-ai. Every supported AI tool reads
a copy of this body from its native entry-point so a single source of
truth drives every target.

2. Native per-rule file in each target's documented location, frontmatter + body verbatim from the source. .cursor/rules/conventional-commits.mdc:

---
description: Always use Conventional Commits format.
globs: "**/*"
alwaysApply: true
---
<!-- Generated by agnostic-ai -->

Use Conventional Commits. Subject under 72 chars. Body explains why, not what.

Same shape lands at .claude/rules/, .windsurf/rules/, .clinerules/, .continue/rules/, .github/instructions/, .agent/rules/.

Supported targets

All 14 targets are first-class. The matrix shows the emission shape per kind (every tool is supported): scan a row for your tool, the ✅ column for what works out of the box.

sync enables 12 by default. Amp and Warp share Codex's root AGENTS.md, so they stay opt-in: add them to targets: or pass -t amp,warp.

Target	Agents	Skills	Rules	Hooks	MCPs
Claude Code	✅	✅	✅	✅	✅
Codex CLI	✅	✅	◐	✅	✅
Gemini CLI	✅	○	◐	✅	✅
Cursor	✅	✅	✅	✅	✅
GitHub Copilot	✅	✅	✅	-	✅
Aider	○	○	◐	-	-
Cline	✅	✅	✅	-	-
Windsurf	✅	✅	✅	-	-
Continue	✅	✅	✅	-	✅
Amp	✅	✅	◐	-	✅
Zed	◐	◐	◐	○	✅
Warp	○	○	◐	-	✅
OpenCode	✅	○	◐	-	✅
Google Antigravity	✅	✅	✅	-	-

Legend, in descending order of native support:

• ✅ native — written in the tool's own format at the path it auto-loads: one file per spec for agents/skills/rules, the tool's native settings/MCP file for hooks and MCPs.
• ◐ bundled — folded into the target's single entry-point or merged doc (no per-spec file). Targets with no native rules directory (Codex, Gemini, Aider, Amp, Warp, OpenCode) inline rule bodies into their entry-point file; Zed merges agents, skills, and rules into .rules.
• ○ opt-in / source-dir — not emitted as a dedicated file by default; the spec stays in the source dir, referenced from the entry-point. Set the matching outputs.<target>.* key (e.g. rules-file, workflows-dir, emit-skills-as-commands) to materialize a file.
• - not supported — the kind is skipped with a warning. Suppress with on-unsupported: silent.

Hooks are native on Claude, Codex, Gemini, and Cursor; Zed runs them as on-demand tasks via opt-in outputs.zed.tasks-file. MCPs propagate to 10 of the 14 targets in each tool's native schema (every target except Aider, Cline, Windsurf, and Antigravity). The matrix shows the five headline kinds; command, settings, review, environment, and ignore round out the full matrix (e.g. command is native on Claude, Codex, Gemini, OpenCode, and Amp).

The matrix tracks the adapter's current output, locked by golden-snapshot tests. Each target carries a Verify with the real CLI checklist in targets confirming the emitted paths against the live tool.

Install

brew install --cask Chemaclass/tap/agnostic-ai                       # Homebrew
go install github.com/chemaclass/agnostic-ai/cmd/agnostic-ai@latest  # Go

Or grab a prebuilt binary from the releases page.

Upgrade

agnostic-ai upgrade           # print the upgrade command for the current install
agnostic-ai upgrade --run     # run the detected upgrade command
agnostic-ai upgrade --check   # diagnose install location and PATH shadowing

Detects the install method (Homebrew, go install, raw download) and prints or runs the matching command. --check flags any other agnostic-ai shadowing it on PATH. That shadowing is the usual reason brew upgrade says "already up-to-date" while --version lags.

Direct package-manager commands also work:

brew update && brew upgrade --cask Chemaclass/tap/agnostic-ai        # Homebrew
go install github.com/chemaclass/agnostic-ai/cmd/agnostic-ai@latest  # Go

Quickstart

agnostic-ai init --demo   # scaffold specs with one example per folder
agnostic-ai sync          # emit native config for every target

Edit specs under .agnostic-ai/, run sync again. Already have .cursor/rules or AGENTS.md?

agnostic-ai import cursor   # also: claude, codex, gemini, cline, windsurf, continue, ...

CI gate to fail PRs that drift from source specs:

- uses: chemaclass/agnostic-ai-action@v1
  with: { command: check }

Commit or ignore generated outputs? init ignores them by default (gitignore.enabled: true): .agnostic-ai/ is the source of truth, contributors run sync, and each sync maintains a managed .gitignore block (configuration). To commit them instead (e.g. teammates lack the CLI), use init --gitignore=false. The check gate guards drift either way.

Documentation

Get started

• Getting started: first rule, first sync, in 2 minutes
• Spec format: frontmatter reference for every kind
• Examples: drop-in templates
• Why not symlinks: how it compares to symlinks, copies, and shared-file setups

Reference

• Targets: what each adapter emits and where
• Configuration: agnostic-ai.yaml reference
• CLI reference: every flag, every command
• Errors: error code lookup

Workflows

• CI gate: drift checks on every PR
• Git hooks: pre-commit, lefthook, husky recipes
• Packs: share spec bundles across repos

Tools

• Playground: paste a spec, see what every adapter emits (WASM, runs offline)
• Editor extensions: VS Code (shipped), JetBrains (planned)

Contributing

• Architecture & roadmap: adapter pattern, adding targets, release process

---

Write the rule once. Every AI tool obeys it. Outlive the tool.