# agnostic-ai

> A CLI tool that keeps agents, skills, rules, hooks, and MCP servers in one portable source and syncs them to native config files for every AI coding tool you use.

agnostic-ai is an open-source CLI tool built by Jose M. Valera Reales (Chemaclass) that solves the config drift problem created when developers use multiple AI coding assistants. Instead of maintaining separate, diverging config files for Claude Code, Codex, Cursor, Gemini CLI, Copilot, and others, agnostic-ai lets you write everything once in plain Markdown and YAML under `.agnostic-ai/` and then generates each tool's native files on demand. It requires no account or external service — everything lives in your repository.

## What It Is

agnostic-ai is a sync-layer CLI, not a platform. It reads a single portable source of truth — agents, skills, rules, hooks, MCP server definitions, settings, and overlays — and translates them into the exact native file formats each AI coding tool expects. The generated files (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules/`, `.gemini/settings.json`, etc.) are treated as outputs, not sources. The project is written in Go, licensed under MIT, and distributed via Homebrew, npm, and direct binary downloads.

## How the Sync Layer Works

The core workflow is three commands:

- `agnostic-ai init` — selects your target tools and optionally imports existing native configs
- `agnostic-ai sync --dry-run` — previews every native file before writing
- `agnostic-ai sync` — writes all native files for the chosen targets

The tool supports 25 targets and 10 portable spec kinds as of the current release. Because the same input always produces the same bytes, `sync --check` can be wired into CI to fail a build when generated files have drifted from their source specs. Git hooks (pre-commit, lefthook, husky) are also supported for local drift detection.

## Spec Kinds and What They Cover

agnostic-ai's portable spec format covers a wide range of AI tool configuration concerns:

- **Instructions** — project-level context written to each tool's entry-point file
- **Agents** — subagent definitions with role, tools, and per-tool model selection
- **Rules** — conventions that are always on or scoped to file globs
- **Hooks** — commands that run on tool events like `PostToolUse`
- **MCP servers** — connection definitions with secrets kept in environment variables
- **Settings** — default model, effort level, and permissions per tool
- **Skills** — reusable workflows with associated scripts
- **Overlays** — native keys that no portable spec covers, merged per tool
- **Local overrides** — personal specs in `.agnostic-ai/local/`, ignored by Git

## Target Support and Format Translation

Each AI coding tool reads a different file format at a different path. agnostic-ai handles the translation: a single rule written in Markdown becomes `.claude/rules/testing.md` for Claude Code, an inline section in `AGENTS.md` for Codex, and a matching section in `GEMINI.md` for Gemini CLI. Agent definitions are translated from a shared YAML front-matter format into `.claude/agents/*.md`, `.codex/agents/*.toml`, and `.gemini/agents/*.md` with the correct field names and structure for each tool. When a target doesn't support a given spec kind (e.g., Codex and Gemini CLI have no portable permission list), sync prints a note instead of guessing.

## Update: v0.75.0

The latest stable release is **v0.75.0**, published on 29 September 2026. Recent releases in the v0.73–v0.75 series added signed releases, patched Go, per-target commits, a `sync --check --against` flag, exact `requires` pins, Codex environments support, `gitignore.commit`, leftover reports, and worktree and preview-server specs. The project has been actively releasing multiple versions per week, signaling rapid iteration. The repository is hosted at `github.com/Chemaclass/agnostic-ai` under the MIT license.

## Features
- Write agents, skills, rules, hooks, and MCP servers once in Markdown and YAML
- Syncs to native config files for 25 AI coding tool targets
- 10 portable spec kinds including agents, rules, hooks, MCP servers, settings, and skills
- Import existing native AI tool configs with agnostic-ai init --from all
- Dry-run preview before writing any files
- sync --check for CI drift detection
- Local overrides kept out of Git for personal or per-machine specs
- Overlay support for native keys no portable spec covers
- Per-target model and effort level configuration
- MCP server definitions with environment variable secret handling
- Hook scripts copied to each targeted tool's hooks folder
- Spec packs for reusable bundles of specs
- Graph and trace commands to inspect spec-to-file relationships
- Git hook integration (pre-commit, lefthook, husky)
- Global user-level configuration with agnostic-ai sync --global
- Byte-stable output for clean diffs
- No account or external service required

## Integrations
Claude Code, OpenAI Codex, Cursor, Gemini CLI, GitHub Copilot, Qoder, Factory, OpenHands, MCP servers, Homebrew, npm, GitHub Actions CI, pre-commit, lefthook, husky, Prettier

## Platforms
WINDOWS, MACOS, LINUX, API, CLI

## Pricing
Open Source

## Version
v0.75.0

## Links
- Website: https://agnostic-ai.org
- Documentation: https://agnostic-ai.org/docs
- Repository: https://github.com/Chemaclass/agnostic-ai
- EveryDev.ai: https://www.everydev.ai/tools/agnostic-ai