Agent Integrations

CLI

Archcore supports 8 coding agents out of the box. Each agent integrates through three mechanisms: MCP servers, session hooks, and an instruction hint — a short “use Archcore” nudge written into the agent’s config files. All three are installed automatically (where supported) during archcore init.

Support matrix

Agent	MCP	Hooks	Instruction File
Claude Code	Yes	Yes	.claude/rules/
Cursor	Yes	Yes	AGENTS.md
GitHub Copilot	Yes	Yes	AGENTS.md
Gemini CLI	Yes	Yes	GEMINI.md
OpenCode	Yes	—	AGENTS.md
Codex CLI	Yes	—	AGENTS.md
Roo Code	Yes	—	AGENTS.md
Cline	Manual	—	AGENTS.md

MCP = agent can list, search, read, create, and update documents through Archcore tools. Hooks = agent receives document context automatically at session start. Instruction File = where the “use Archcore” instruction hint is written.

Auto-detection

archcore init detects agents by looking for their configuration directories:

Agent	Detected by
Claude Code	.claude/ directory
Cursor	.cursor/ directory
GitHub Copilot	.github/copilot-instructions.md file
Gemini CLI	.gemini/ directory
OpenCode	opencode.json file or .opencode/ directory
Codex CLI	.codex/ directory
Roo Code	.roo/ directory
Cline	.clinerules/ directory

If no agents are detected, behavior depends on the terminal:

• Interactive — Archcore prompts you with a multi-select of every supported agent, plus a Skip — configure later option. Pick the agents you want to configure, or skip.
• Non-interactive (no TTY, e.g. CI) — Archcore skips agent setup entirely and prints a hint to run archcore mcp install --agent <id> later.

There is no default agent — nothing is installed until you pick or run a manual install.

MCP config locations

Agent	ID	Config File
Claude Code	claude-code	.mcp.json
Cursor	cursor	.cursor/mcp.json
GitHub Copilot	copilot	.vscode/mcp.json
Gemini CLI	gemini-cli	.gemini/settings.json
OpenCode	opencode	opencode.json
Codex CLI	codex-cli	.codex/config.toml
Roo Code	roo-code	.roo/mcp.json
Cline	cline	VS Code globalStorage (manual)

Corrupt config handling

Archcore never silently overwrites a config it can’t parse. When it writes an agent’s MCP or hook config, the behavior depends on the file format:

• Standard JSON — .claude/settings.json, .cursor/hooks.json, .mcp.json, opencode.json, and other strict-JSON configs. If the file is corrupt or unparseable, Archcore backs it up to {path}.bak and starts fresh from a valid config. You’ll see a warning noting the backup.
• .vscode/mcp.json (GitHub Copilot) — this file is JSONC, so comments and trailing commas are valid even though they aren’t strict JSON. Archcore leaves it untouched and prints a manual-install hint instead of touching your other MCP servers.

Add *.bak to your .gitignore so these backups don’t get committed.

Instruction hint

Installing the MCP server doesn’t guarantee the agent will use it. The instruction hint is a short “use Archcore” nudge written into the agent’s instruction file. It tells the model that Archcore’s MCP tools exist and when to consult them — otherwise the tools sit idle and the agent never calls list_documents or search_documents.

The hint is opt-in during interactive archcore init (the prompt defaults to yes). In non-interactive mode it’s skipped, and Archcore points you to archcore instructions install instead.

For agents with shared instruction files (AGENTS.md, GEMINI.md), the hint is inserted inside a managed marker block:

<!-- archcore:start -->
...
<!-- archcore:end -->

The markers let Archcore update or remove the hint without clobbering your own content. Claude Code uses .claude/rules/ instead of a shared file.

Manage the hint with archcore instructions:

archcore instructions install            # write the hint to all detected agents
archcore instructions install --agent gemini-cli   # target a single host
archcore instructions remove             # strip the managed block

Removal strips only the managed block, and works even after de-init.

Manual installation

Install MCP for a specific agent:

archcore mcp install --agent cursor

Install hooks for a specific agent:

archcore hooks install --agent claude-code

Best experience

For the best experience, use an agent that supports both MCP and hooks. Claude Code, Cursor, GitHub Copilot, and Gemini CLI currently offer the most complete integration — agents receive context at session start and have full document management tools available.

Agents without hook support (OpenCode, Codex CLI, Roo Code, Cline) still work well through MCP tools. The main difference is that you’ll need to explicitly ask the agent to check for documents rather than having context injected automatically.

Plugin vs CLI integration

This page lists the CLI-level integrations — every supported agent gets MCP and (where possible) hooks.

Two of these hosts (Claude Code and Cursor) additionally support the higher-level Archcore Plugin — skills, tracks, built-in agents, and guardrails. See Supported AI agents for the plugin-specific matrix.

Next steps

• MCP server — how agents connect.
• Hooks — what the session-start hook emits.
• Commands — the archcore commands that drive integration.