Skip to main content

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.

The CLI ships with adapters for seven AI agents. Each adapter knows where that host stores its MCP configuration and what format it expects.
AgentDetectionMCP configSkill file
Claude Code~/.claude/ exists~/.claude/mcp.json~/.claude/skills/xysq/SKILL.md
Claude DesktopOS-specific app dir existsclaude_desktop_config.json— (MCP-only host)
Cursor~/.cursor/ exists~/.cursor/mcp.json~/.cursor/rules/xysq.mdc or ~/.cursorrules
Codex~/.codex/ exists~/.codex/config.toml~/.codex/AGENTS.md
Gemini CLIgemini binary on PATH~/.gemini/settings.json~/.gemini/GEMINI.md
Copilot CLIgh-copilot binary on PATH~/.copilot/config.json~/.copilot/AGENTS.md
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: 
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.