agnostic-ai

agnostic-ai keeps your coding tools working from the same project instructions. Edit one source, then run agnostic-ai sync to write the files Claude Code, Codex, and your other tools read.

Each AI tool reads its instructions from different files. Kept by hand, those files fall out of step. agnostic-ai keeps one source in plain Markdown and YAML inside your repository. It needs no account and no service. See Why agnostic-ai.

Quickstart

From your project root, with Node 18 or newer:

npm install -g agnostic-ai
agnostic-ai init

Select the tools you use, for example Claude Code and Codex. If the project already has files such as CLAUDE.md or AGENTS.md, accept the offer to import them so their instructions are kept. If the project already has agnostic-ai.yaml, skip init and run agnostic-ai sync.

init also creates .agnostic-ai/AGNOSTIC_AI.md, the note every selected tool reads. Open it and replace the placeholder comment with one project note, or add it below any imported instructions, for example:

Run the project tests before finishing a change.

Preview the files, write them, and check that they match the source:

agnostic-ai sync --plan
agnostic-ai sync
agnostic-ai sync --check

For user-level configuration, agnostic-ai sync --global --plan --check previews changes and exits non-zero on drift. agnostic-ai doctor explains drift, including when a shared settings file keeps your keys after sync removes its own.

Use sync -v for a concise report of changes and sync -vv for full details. Both commands write generated files. Sync saves hand edits as .bak before replacing or removing a generated file; revert restores them.

Changing only the capitalization of a rule, skill, or agent name needs one sync, including on macOS and Windows.

With Claude Code and Codex selected, your note is now in AGENTS.md, and CLAUDE.md points to it. To change what both tools read, edit .agnostic-ai/AGNOSTIC_AI.md and sync again. Do not edit the generated files: sync replaces them.

Homebrew, the install script, Windows, and Go are on the installation page.

When a project version requirement blocks a command, the terminal offers a fix, a configured AI CLI, or a prompt to copy. See version mismatch help.

Set up with a coding agent

Or paste this into Claude Code, Codex, Cursor, or another coding agent:

Set up agnostic-ai in this repository. Follow https://agnostic-ai.org/agent-setup.txt exactly. Preserve existing AI tool behavior. Before any sync, check for existing CLAUDE.md, AGENTS.md, and similar files, and ask me what to do with their content. Finish with agnostic-ai sync --check. Summarize the targets selected and every file changed.

Next steps

• Set up your project: the full walkthrough, Git choices, and everyday commands.
• Import an existing setup: review your current tool files before the first sync. Grok MCP imports leave out ignored descriptions.
• What you can share: rules, skills, agents, hooks, MCP servers, settings, and memory.
• Supported tools: what each tool receives, and where.
• Inspect lifecycle hooks: scan stage counts, then expand a stage or all stages to see hooks.
• Share an MCP server only one tool has: Tools previews and saves one server as a spec, ready for your next sync.
• Find a global hook's files: agnostic-ai explain --global hooks/guard.yaml lists where sync places the hook; directory-based hooks also list copied scripts.
• Trace a generated file: agnostic-ai why CLAUDE.md finds its source even when an unselected tool rejects your setup.
• Voice dictation: keep personal voice settings in your home specs, import existing values, and apply them with sync --global, including Warp dictation.
• Inspect context size: compare startup and on-demand text, filter by file, and open sources in your chosen editor. The report stays in place while a new tool loads.
• Edit settings in the browser: browse source groups in tabs, compare Project and Local values, preview permission rules, and edit global voice dictation settings. Section headings link to the relevant reference docs.
• Troubleshooting: when a file is missing or a check fails.

Contribute

See CONTRIBUTING.md to build the CLI and choose checks for your change.

Documentation · Playground · Editor extensions · Claude Code plugin · CLI reference · Changelog