Agent Integrations

CLI

Archcore supports 8 coding agents. Each one integrates through three mechanisms: MCP servers, lifecycle hooks, and an instruction hint — a short “use Archcore” nudge written into the agent’s config files. archcore init installs MCP config and hooks where the host supports them; the instruction hint is opt-in on interactive runs, written without a prompt when --agent <id> names the host, and skipped on a non-interactive run without --agent (see Instruction hint). Four hosts additionally carry the Archcore plugin: Claude Code, Cursor, Codex CLI, and GitHub Copilot.

If you are still deciding, the CLI page has the short version of this matrix.

Support matrix

Agent	MCP	Hooks	Plugin	Instruction File
Claude Code	Yes	Yes	Yes	CLAUDE.md + AGENTS.md
Cursor	Yes	Yes	UI only	AGENTS.md
GitHub Copilot	Yes	Yes	Yes	AGENTS.md
Gemini CLI	Yes	Yes	No	GEMINI.md
Codex CLI	Yes	Yes	Yes	AGENTS.md
OpenCode	Yes	No	No	AGENTS.md
Roo Code	Yes	No	No	AGENTS.md
Cline	Manual	No	No	AGENTS.md

• MCP gives the agent tools to list, search, read, create, and update documents.
• Hooks wire three lifecycle events: session start (project recap), pre-write (blocks direct writes to .archcore/ documents and injects the documents that constrain the file being edited), and post-write (structure, relation-cascade, and precision findings after a document changes).
• Plugin says whether the Archcore plugin ships for that host and whether the CLI can install it. Cursor is the “UI only” case: it manages plugins in its own interface, so the CLI runs no command there and prints the instruction to add the plugin from the Cursor UI. OpenCode’s own plugin is a different artifact and is not this surface.
• Instruction File is the file that receives the “use Archcore” hint.

Three entry points reach the plugin: archcore plugin install|update|remove|status, the delivery step inside archcore init (a host you check in the agent picker or name with --agent is the consent), and the refresh step inside archcore update, which covers each host that already carries the plugin. On Codex CLI and GitHub Copilot the plugin installs machine-level, outside the project. See the archcore plugin reference.

Hook install wiring covers five hosts. The other three do not get a hook config:

• OpenCode hooks are JavaScript plugins, so they cannot be wired declaratively. The CLI ships the archcore hooks opencode <event> commands for a plugin to delegate to, and writes no config. This is permanent, not pending.
• Roo Code supports onSave hooks only, which are not lifecycle events.
• Cline has no hooks, and its MCP config is manual (see MCP config locations).

Host limitations

A host can accept a hook config and still not run it. After a successful write, archcore hooks install prints whether that host can act on what was written. archcore doctor prints the same notes, but only for hosts whose config holds an Archcore hook command. Silence means the wiring works.

Three hosts carry a known limitation.

Codex CLI

Codex keeps hooks behind an experimental feature flag that is off by default. Enable it with codex --enable hooks, or add a [features] table to ~/.codex/config.toml:

[features]
hooks = true

Before Codex 0.129.0 the key is spelled codex_hooks = true.

Two further conditions apply: hooks are unavailable on Windows, and project-local hooks load only when the .codex/ layer is trusted.

GitHub Copilot

Copilot’s pre-write event carries only a permission decision, so it cannot receive context. The write guard runs there and still blocks direct writes to .archcore/ documents. The code-alignment injection does not run.

Copilot also reads .claude/settings.json. In a repository wired for both Copilot and Claude Code, the hooks may run twice; hooks install reports the possible duplicate.

Gemini CLI

Gemini’s tool events are wired from the published reference and are not confirmed against a running host. Its event names, tool names, and timeout unit all differ from every other host.

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.

In an interactive terminal, 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.

Without a TTY (in CI, for example), Archcore skips agent setup and prints a hint to run archcore mcp install --agent <id> later.

There is no default agent. Archcore installs nothing until you pick an agent 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	.mcp.json (shared with Claude Code)
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)

Codex CLI is the only agent whose MCP config is TOML. Its hooks live in a separate file, .codex/hooks.json, so the hook writer never rewrites the config.toml that the MCP wiring owns.

Cline stores its MCP config in VS Code’s globalStorage rather than in a project file, so you add the Archcore server through Cline’s MCP settings interface. Archcore prints a hint when it detects Cline.

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:

• JSON covers every JSON target Archcore writes: .claude/settings.json, .cursor/hooks.json, .mcp.json, opencode.json, and the rest. 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 naming the backup. When the backup write itself fails, the install aborts: the original is never overwritten without a confirmed backup.
• .codex/config.toml (Codex CLI) is TOML and sits outside the .bak policy. Codex hook wiring lives in a separate .codex/hooks.json, so one writer owns each file.

All config writes are atomic (temp file plus rename), so a crash mid-write cannot truncate a live config.

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

Wrapped hook commands

Archcore recognizes its own hook entries by the literal archcore hooks command prefix. A command you wrapped, for example sh -c 'archcore hooks cursor session-start 2>/dev/null', no longer starts with that prefix, so Archcore classifies it as foreign: re-runs and doctor --fix leave it untouched, and it stops receiving automatic command updates. You own what you wrapped.

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. Without the hint, 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). archcore init --agent <id> writes the hint for the named host without a prompt, interactive or not. On a non-interactive run without --agent, Archcore skips the hint and points you to archcore instructions install.

Where the hint lands

Agent	Instruction file(s)
Claude Code	CLAUDE.md and AGENTS.md
Gemini CLI	GEMINI.md
Cursor, OpenCode, Codex CLI, Roo Code, Cline, GitHub Copilot	AGENTS.md

The six AGENTS.md agents share one file, written once.

Claude Code gets both files. It reads CLAUDE.md natively and does not auto-read AGENTS.md, so CLAUDE.md is what delivers the nudge. Archcore writes the AGENTS.md block as well, so the repository carries the standard that the plugin and the six other hosts converge on. CLAUDE.md holds the full nudge body directly, with no @import, so the two files stay uncoupled. Claude Code loads only CLAUDE.md, so the second file adds no duplicated context cost.

Managed marker block

Archcore inserts the hint inside a managed marker block in every target (CLAUDE.md, AGENTS.md, GEMINI.md):

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

Archcore touches only the span between the markers. Your content outside them stays untouched, and a second write is idempotent, so Claude Code and a co-installed AGENTS.md agent collapse into one block rather than two.

Upgrading from an earlier CLI

Earlier versions wrote an Archcore-owned .claude/rules/archcore.md. That file is deprecated: re-wiring removes it, and so does archcore instructions remove --agent claude-code. Removing Claude Code alone strips its CLAUDE.md block and deletes the legacy file. The shared AGENTS.md block stays for the AGENTS.md agents’ own removal.

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

The install prints any host limitation that would keep the written config from taking effect.

Full integration vs MCP only

Claude Code, Cursor, GitHub Copilot, Gemini CLI, and Codex CLI support both MCP and hooks. On those hosts the agent receives context at session start, gets the documents that constrain a file before it edits the file, and has the full document management tools.

OpenCode, Roo Code, and Cline work through MCP tools alone. On those hosts you ask the agent to check for documents instead of having context injected at session start.

Plugin vs CLI integration

This page lists the CLI-level integrations. Every supported agent gets MCP and, where possible, hooks.

Four of these hosts (Claude Code, Cursor, Codex CLI, and GitHub Copilot) additionally carry the higher-level Archcore plugin with its skills, tracks, built-in agents, and guardrails. archcore plugin delivers it on three of them and prints the UI instruction on Cursor. See Supported AI agents for the plugin-specific matrix.

Next steps

• MCP server explains how agents connect.
• Hooks covers what the hooks emit and how to install them.
• Commands lists the archcore commands that drive integration.