Why agnostic-ai?
Each coding tool has its own instruction and settings files. agnostic-ai generates them from one set of sources, so you update shared instructions once.
A small useful setup
Start with a short project note in .agnostic-ai/AGNOSTIC_AI.md:
Application code is in src/. Tests are in tests/.
Read CONTRIBUTING.md for the test command.
Run the relevant tests before finishing a change.
Run agnostic-ai sync. Claude Code gets CLAUDE.md, Codex gets AGENTS.md, and other tools get their own files. Change the note and sync again to update them all.
What agnostic-ai does
Source files, called specs, live in .agnostic-ai/ as Markdown and YAML. Choose the coding tools, called targets, in agnostic-ai.yaml.
Sync translates the specs into each tool's paths, formats, and setting names, and reports features a tool cannot use. agnostic-ai sync --check tells you whether the generated files still match the specs.
You still install and sign in to the coding tools yourself. Instructions guide the model; tests and tool permissions enforce checks and limits. A connection to an outside service still needs that service's login or key.
What to add, and when
Start with the project note. Add another kind of spec only when you need it:
| You need | Use | Example |
|---|---|---|
| Project instructions | .agnostic-ai/AGNOSTIC_AI.md | Where code lives and how to test it |
| A coding convention | A rule | Use the project's commit format |
| Steps for a repeatable task | A skill | Prepare a release |
| A specialist to delegate to | An agent | Review a change for defects |
| Limits on what an agent may read, run, or call | Agent capabilities | Let a reviewer read but not edit |
| A command at a tool event | A hook | Format a file after an edit |
| Tool settings | Settings | Choose a model or permissions |
| One model choice for every tool | Model roles | Use a fast model for lookups |
| An outside service or data source | An MCP connection | Read an issue tracker |
| Guidance for code review bots | Reviews | Flag missing tests |
| Facts every tool can recall | Shared memory | A decision and its reason |
| Work you pick up in another tool | Session handoffs | One private note per branch |
| A summary for people when the work ends | Session wrap-ups | What changed, what is open, a note to paste |
| A second task, started without leaving this one | Side conversations | A new tab, linked to this session |
| Shorter command output and replies | RTK and Caveman | Fewer tokens per session |
MCP (Model Context Protocol) is how coding tools connect to other tools and data. An MCP spec names the environment variables that hold credentials, so keys stay out of the repository. Each tool supports a different set of features; the capability matrix shows what each one gets.
When you do not need it
For one tool and a small setup, start with that tool's own files. Use agnostic-ai when you share a setup across tools or keep several formats current. If you stop using agnostic-ai, the generated files keep working; commit them first if Git ignores them. Copies need separate updates. A symlink shares text but cannot translate formats or setting names. One One connection in Sync writes the same connection in each tool's format:Why copies, symlinks, and one AGENTS.md have limits
Why the usual fixes fall short
AGENTS.md shares instructions with tools that read it, but cannot configure their native skills, hooks, or service connections. A custom script can translate the formats you maintain yourself.The same server, four formats
.agnostic-ai/mcps/github.yaml:name: github
type: http
url: https://api.githubcopilot.com/mcp/
Tool File Connection setting Claude Code .mcp.jsonmcpServers.github.urlCodex .codex/config.toml[mcp_servers.github] with urlGemini CLI .gemini/settings.jsonmcpServers.github.httpUrlZed .zed/settings.jsoncontext_servers.github.url
Start
Install agnostic-ai, then set up your project. Already have tool files? Import them first.