> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xysq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Supported agents

> Where the CLI writes MCP config and skill files for each supported AI agent.

The CLI ships with adapters for seven AI agents. Each adapter knows where that host stores its MCP configuration and what format it expects.

| Agent                             | Detection                       | MCP config                              | Skill file                                     |
| --------------------------------- | ------------------------------- | --------------------------------------- | ---------------------------------------------- |
| [Claude Code](#claude-code)       | `~/.claude/` exists             | `~/.claude/mcp.json`                    | `~/.claude/skills/xysq/SKILL.md`               |
| [Claude Desktop](#claude-desktop) | OS-specific app dir exists      | `claude_desktop_config.json`            | — (MCP-only host)                              |
| [Cursor](#cursor)                 | `~/.cursor/` exists             | `~/.cursor/mcp.json`                    | `~/.cursor/rules/xysq.mdc` or `~/.cursorrules` |
| [Codex](#codex)                   | `~/.codex/` exists              | `~/.codex/config.toml`                  | `~/.codex/AGENTS.md`                           |
| [Gemini CLI](#gemini-cli)         | `gemini` binary on PATH         | `~/.gemini/settings.json`               | `~/.gemini/GEMINI.md`                          |
| [Copilot CLI](#copilot-cli)       | `gh-copilot` binary on PATH     | `~/.copilot/config.json`                | `~/.copilot/AGENTS.md`                         |
| [Antigravity](#antigravity)       | `~/.gemini/antigravity/` exists | `~/.gemini/antigravity/mcp_config.json` | — (MCP-only host)                              |

## Detection

Detection runs in parallel across every adapter. Each adapter reports `installed: true | false` based on a single host-specific signal. The CLI uses two kinds of signal:

* **Directory presence** — for agents whose presence on the system maps reliably to a known directory (`~/.claude`, `~/.cursor`, `~/.codex`).
* **Binary on PATH** — for agents whose config directories are commonly created by other tools (e.g., `~/.gemini` is shared with Antigravity and Google Cloud SDK). For these we check the actual CLI binary instead.

If you want to install for an agent the CLI didn't auto-detect, pass it explicitly:

```bash theme={"dark"}
xysq install codex                    # force-install even if codex isn't on PATH
```

## Claude Code

* **Detection:** `~/.claude/` directory exists.
* **MCP config:** `~/.claude/mcp.json`, JSON, under `mcpServers.xysq`.
* **Skill:** `~/.claude/skills/xysq/SKILL.md` — its own directory, clean overwrite on install, clean delete on uninstall.

The MCP entry shape is the canonical `type: "http"` MCP server format with the API key inlined in the `Authorization` header.

## Claude Desktop

* **Detection:**
  * macOS: `~/Library/Application Support/Claude/`
  * Windows: `%APPDATA%\Claude\`
  * Linux: `~/.config/Claude/`
* **MCP config:** `claude_desktop_config.json` in that directory.
* **Skill:** none — Claude Desktop has no skill surface. MCP-only.

## Cursor

* **Detection:** `~/.cursor/` directory exists.
* **MCP config:** `~/.cursor/mcp.json`, JSON.
* **Skill (dual-path):**
  * **Modern** (Cursor 0.40+): `~/.cursor/rules/xysq.mdc` — own file, clean overwrite.
  * **Legacy:** `~/.cursorrules` — delimited-block merge that preserves your other rules.

The adapter picks the modern path if `~/.cursor/rules/` exists at install time; otherwise it merges into `.cursorrules`.

## Codex

* **Detection:** `~/.codex/` directory exists.
* **MCP config:** `~/.codex/config.toml`, TOML, under the `[mcp_servers.xysq]` table.
* **Skill:** `~/.codex/AGENTS.md` — delimited-block merge.

Note: TOML round-tripping is best-effort. Comments around `[mcp_servers]` may not survive exactly. If you've heavily customized that section, run `xysq doctor` after install to verify.

## Gemini CLI

* **Detection:** the `gemini` binary is on `PATH`. Directory presence alone is not enough (`~/.gemini/` is shared with Antigravity and other Google tooling).
* **MCP config:** `~/.gemini/settings.json`, JSON.
* **Skill:** `~/.gemini/GEMINI.md` — delimited-block merge.

If Gemini CLI is installed but doesn't show up in `xysq install`, confirm `which gemini` returns a path.

## Copilot CLI

* **Detection:** the `gh-copilot` binary is on `PATH`. (Copilot CLI ships as a `gh` extension and registers this binary.)
* **MCP config:** `~/.copilot/config.json`, JSON.
* **Skill:** `~/.copilot/AGENTS.md` — delimited-block merge.

If Copilot CLI is installed but doesn't show up, the `gh-copilot` extension may not be active. Run `gh extension list` to confirm.

## Antigravity

* **Detection:** `~/.gemini/antigravity/` directory exists.
* **MCP config:** `~/.gemini/antigravity/mcp_config.json`, JSON. Note that Antigravity uses `serverUrl` (not `url`) as the field name inside each server entry.
* **Skill:** none — Antigravity reads system prompts differently. MCP-only.

## Merge semantics for shared host files

Three agents share their skill location with content the user may have authored: Codex's `AGENTS.md`, Gemini CLI's `GEMINI.md`, and Cursor's legacy `.cursorrules`. The CLI wraps xysq's contribution in delimiters so it can be cleanly replaced or removed:

```
<existing user content above>

<!-- xysq:start version=8 -->
… skill content from /skill/download …
<!-- xysq:end -->

<existing user content below>
```

* On `install`: the block is replaced in place if it exists, or appended at the end with one blank-line separator.
* On `uninstall`: the block is removed; everything outside is preserved byte-for-byte.
* If you edit the contents *inside* the block, `doctor` reports drift and `update-skills` refuses to overwrite without `--force`.

## Backups

The first time the CLI modifies any config file in its history, it copies the original to `~/.xysq/backups/<agent>-<timestamp>.bak`. The last 5 per agent are retained. To restore from backup, copy the file back manually — there's no dedicated restore command in v1.