README.md

agnostic-ai

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

Each AI tool reads different instruction files. Hand-edited copies can fall out of sync. agnostic-ai generates them from Markdown and YAML in your repository, with no account or 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 creates .agnostic-ai/AGNOSTIC_AI.md, the instructions every selected tool reads. Replace its placeholder comment with a project note, or add one below any imported instructions:

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

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. Sync replaces generated files, so edit the source instead. It saves a hand edit as .bak first, and agnostic-ai revert restores it.

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

Set up with a coding agent

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.
• What you can share: rules, skills, agents, hooks, MCP servers, settings, and memory.
• Supported tools: what each tool receives, and where.
• Open the web interface: view context size and edit hooks, MCP servers, and settings with agnostic-ai ui.
• Save a session handoff: switch tools mid-task, or automate Git snapshots with Claude hooks.
• Trace a generated file: agnostic-ai why CLAUDE.md names its source.
• Personal settings: keep them in ~/.agnostic-ai and apply them with agnostic-ai sync --global.
• Troubleshooting: when a file is missing or a check fails. agnostic-ai doctor explains drift.

Contribute

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

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