Type to search the docs and updates.

Browse documentation

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 needUseExample
Project instructions.agnostic-ai/AGNOSTIC_AI.mdWhere code lives and how to test it
A coding conventionA ruleUse the project's commit format
Steps for a repeatable taskA skillPrepare a release
A specialist to delegate toAn agentReview a change for defects
Limits on what an agent may read, run, or callAgent capabilitiesLet a reviewer read but not edit
A command at a tool eventA hookFormat a file after an edit
Tool settingsSettingsChoose a model or permissions
One model choice for every toolModel rolesUse a fast model for lookups
An outside service or data sourceAn MCP connectionRead an issue tracker
Guidance for code review botsReviewsFlag missing tests
Facts every tool can recallShared memoryA decision and its reason
Work you pick up in another toolSession handoffsOne private note per branch
A summary for people when the work endsSession wrap-upsWhat changed, what is open, a note to paste
A second task, started without leaving this oneSide conversationsA new tab, linked to this session
Shorter command output and repliesRTK and CavemanFewer 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.

Why copies, symlinks, and one AGENTS.md have limits

Why the usual fixes fall short

Copies need separate updates. A symlink shares text but cannot translate formats or setting names. One 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

One connection in .agnostic-ai/mcps/github.yaml:

name: github
type: http
url: https://api.githubcopilot.com/mcp/

Sync writes the same connection in each tool's format:

ToolFileConnection setting
Claude Code.mcp.jsonmcpServers.github.url
Codex.codex/config.toml[mcp_servers.github] with url
Gemini CLI.gemini/settings.jsonmcpServers.github.httpUrl
Zed.zed/settings.jsoncontext_servers.github.url

Start

Install agnostic-ai, then set up your project. Already have tool files? Import them first.