Install the Plugin

Plugin

The plugin runs inside your coding agent and invokes archcore from your PATH. Install the CLI first, then install the plugin. The CLI install guide has one curl line for macOS and Linux and one PowerShell line for Windows.

With the CLI in place, archcore plugin install adds the plugin to every host it can act on. The per-host route below does the same job from each host’s own interface.

Two hosts need one extra step on either route. On Cursor you register MCP yourself. On GitHub Copilot CLI you wire the project with archcore init --agent copilot.

Install with the CLI

archcore plugin install

The command targets the four hosts that ship a plugin and prints one report per host.

Host	What install does
Claude Code	Runs claude plugin marketplace add archcore-ai/plugin, then claude plugin install archcore@archcore-plugins at user scope
Cursor	Prints the instruction to add the plugin from the Cursor marketplace or with /add-plugin. Cursor has no CLI mechanism, so no host command runs
Codex CLI	Runs codex plugin marketplace add archcore-ai/plugin, then codex plugin add archcore@archcore-plugins, machine-level
GitHub Copilot	Runs copilot plugin install archcore-ai/plugin:plugins/archcore, machine-level

Machine-level means the host’s plugin store has no repository scope, so the install changes your machine rather than the current project.

To act on a single host, name it with --agent:

archcore plugin install --agent claude-code

--agent accepts claude-code, cursor, codex-cli, and copilot. Any other agent id fails with an error naming those four.

Typing the verb is the consent for every host the command targets, so it acts the same way with or without a terminal. The CLI runs a mutating host command only after that host’s own read-only plugin listing reports the plugin’s state:

• The listing already names Archcore: the CLI reports it and changes nothing, so a rerun is a no-op.
• The host CLI is not on PATH: the CLI reads the host’s on-disk plugin registry, reports the plugin when it finds it there, and otherwise prints the exact install command for you to run.
• A host command fails or times out: the CLI prints the command it ran and continues with the next host.

archcore plugin covers the flags, the evidence tiers, and the exit codes.

Claude Code auto-update

When the CLI performs the Claude Code install, it also merges an extraKnownMarketplaces["archcore-plugins"] entry carrying "autoUpdate": true into ~/.claude/settings.json, keeping the fields already in the file. Claude Code then refreshes the plugin on its own in the background.

--scope project writes that entry into the repository’s .claude/settings.json instead, and the CLI prints that the committed file delivers the declaration to every teammate who checks it out. The flag selects the settings file and nothing else about the install.

Keep the plugin current

archcore plugin status
archcore plugin update

status reports what each host carries. update refreshes every host whose listing confirms the plugin and stays silent for the rest.

A manual archcore update runs the same update action after its binary phase, so upgrading the CLI carries the plugin along. That step never changes the exit code, archcore update --check skips it, and the unattended background update never reaches it. See archcore update.

Install during archcore init

archcore init installs the plugin for every host you check in its agent picker or name with --agent:

archcore init --agent claude-code

A host that init merely detected gets a hint naming archcore plugin install, never an install. Under --yes without --agent, and in CI, init prints the per-host commands and runs none of them.

On GitHub Copilot CLI this is the shortest route: archcore init --agent copilot --project "$PWD" writes the hooks, the project-level MCP entry, and the usage hint, and installs the plugin in the same run.

Install per host

Use this route when you prefer your host’s own interface. The plugin still calls archcore from your PATH, so the CLI stays a prerequisite.

Claude Code

From your shell:

claude plugin marketplace add archcore-ai/plugin
claude plugin install archcore@archcore-plugins

Or, from within Claude Code:

/plugin marketplace add archcore-ai/plugin
/plugin install archcore@archcore-plugins

The plugin spawns archcore mcp from your PATH through its .claude.mcp.json. If .archcore/ does not exist yet, the first MCP call initializes it.

Only an install performed by the CLI writes the autoUpdate marketplace entry described above. After a manual install, refresh the plugin with archcore plugin update, archcore update, or Claude Code’s own /plugin commands.

If archcore isn’t on PATH, the session-start hook prints install instructions and links to the CLI install guide.

Cursor

Requires Cursor 2.5+. Archcore isn’t on the official Cursor Marketplace yet, so install from GitHub via the Plugins panel:

1. Open Cursor → Plugins
2. Paste https://github.com/archcore-ai/plugin into the Search or paste link field
3. Click Add Plugin

Cursor reads the repo’s marketplace.json and installs the plugin. For team rollouts, paste the same URL under Dashboard → Settings → Plugins → Team Marketplaces → Import.

This is the only route on Cursor. Cursor exposes no command-line plugin mechanism, so archcore plugin install --agent cursor prints this instruction and runs nothing.

Cursor does not auto-register plugin MCP, so register archcore yourself. Copy docs/cursor.mcp.example.json (shipped in the plugin’s docs/ directory) into ~/.cursor/mcp.json (user-scoped) or .cursor/mcp.json (project-scoped):

{
  "mcpServers": {
    "archcore": {
      "type": "stdio",
      "command": "archcore",
      "args": ["mcp", "--project", "${workspaceFolder}"]
    }
  }
}

Keep the --project ${workspaceFolder} argument. It scopes MCP to the active project; without it, a single registration would read one project’s .archcore/ across every Cursor window.

Cursor’s hooks API differs from the Claude Code one. Supported AI agents lists the differences.

Codex CLI

Requires Codex CLI 0.117.0+. Add the marketplace, then install from inside Codex:

codex plugin marketplace add archcore-ai/plugin
codex
# then run /plugins, open Archcore, and select Install plugin

The plugin installs machine-level, outside the project. archcore plugin install --agent codex-cli runs the same marketplace add and follows it with codex plugin add archcore@archcore-plugins.

Codex registers MCP automatically. The plugin’s manifest references .codex.mcp.json, which runs archcore mcp from your PATH. That config uses no env-var substitution and no plugin-relative paths.

Enable hooks. Codex gates them behind its hooks feature. 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. Without this feature, skills, MCP tools, and agents work normally, but the write guard, code-alignment injection, and post-write checks won’t fire.

GitHub Copilot CLI

Two steps, both required:

copilot plugin install archcore-ai/plugin:plugins/archcore
archcore init --agent copilot --project "$PWD"

Step 2 is not optional. On Copilot the plugin ships no MCP server, so a project that skips it loads skills and hooks but has no document tools at all. Copilot launches a plugin’s MCP server in the plugin install directory with no project path (github/copilot-cli#4234), which would serve the plugin cache instead of your repository.

archcore init --agent copilot writes the project-level MCP entry, the hooks, and the usage hint, and installs the plugin in the same run. Restart the session afterwards so Copilot connects the tools.

The plugin installs machine-level, outside the project. The copilot binary is often absent from PATH on a VS Code-managed install; the CLI then prints the install command instead of running it, and step 1 stays yours to run.

Copilot CLI only. VS Code agent mode has no self-serve plugin install, and cloud-agent sandboxes do not load plugin hooks.

Local development (any host)

Clone the plugin repo:

git clone https://github.com/archcore-ai/plugin

On Claude Code, load the cloned directory for the session:

claude --plugin-dir /path/to/plugin

Cursor has no --plugin-dir flag. Symlink the repo into Cursor’s local plugins directory, then reload the window:

ln -s /path/to/plugin ~/.cursor/plugins/local/archcore
# then in Cursor: Cmd/Ctrl+Shift+P → "Developer: Reload Window"

On Codex CLI, point a local marketplace at the checkout:

codex plugin marketplace add /path/to/plugin
codex plugin add archcore@archcore-plugins

If you want hooks active, launch with codex --enable hooks, or add [features] with hooks = true to ~/.codex/config.toml (codex_hooks = true before Codex 0.129.0).

On GitHub Copilot CLI, load the plugin directory directly:

copilot --plugin-dir /path/to/plugin/plugins/archcore

All four manifests (.claude-plugin/plugin.json, .cursor-plugin/plugin.json, .codex-plugin/plugin.json, .plugin/plugin.json) sit under plugins/archcore/.

Use local mode when you work on skills or hooks. The plugin calls archcore from PATH. To test against a locally built CLI binary, put its directory ahead of the installed one on PATH (e.g. export PATH="$(pwd)/cli/bin:$PATH").

Offline / pinned CLI

The plugin always runs whichever archcore is on your shell’s PATH. In an offline or air-gapped environment, install the CLI by any supported method (curl, PowerShell, or build from source), then put it on PATH before you launch your coding agent. The CLI install guide covers each method.

To pin a specific binary, install it to a directory you control and put that directory first on PATH.

Plugin environment variables

Variable	Effect
ARCHCORE_DISABLE_INJECTION	=1 turns off the pre-edit context injection globally.
ARCHCORE_HIDE_EMPTY_NUDGE	=1 suppresses the session-start nudge that suggests /archcore:init.
ARCHCORE_HIDE_WIRING_NUDGE	=1 suppresses the Copilot advisory about a project with no MCP wiring.

Verify

1. Ask the CLI what each host reports:

   archcore plugin status

   One line per host, for example:

   Claude Code: installed (the host reports it)
   Cursor: not installed
   Codex CLI: not installed (the host reports it)
   GitHub Copilot: installed (on-disk registry; the host CLI is not on PATH)

   The command covers all four hosts, reads each host’s own listing when its CLI is on PATH, falls back to the on-disk plugin registry when it is not, and always exits 0.

2. Restart your coding agent so the session-start hook can run.

3. In a fresh conversation, type /archcore: and check that autocomplete lists four commands: init, plan, document, and review.

4. Run a read-only command against a real project:

   /archcore:review

   On a branch with changes you get a review of those changes against .archcore/. On the default branch you get the project health dashboard.

5. Record a real decision:

   /archcore:document use PostgreSQL as the primary database

   The agent classifies it as an ADR, creates a draft in .archcore/ through MCP rather than a direct file write, and offers a rule and guide continuation.

If /archcore:* commands don’t appear, check Troubleshooting.

Uninstall

Remove the plugin from every host that carries it:

archcore plugin remove

On a host whose CLI is on PATH, the command runs that host’s own uninstall. On Claude Code it also deletes the extraKnownMarketplaces["archcore-plugins"] entry the CLI wrote and leaves the rest of ~/.claude/settings.json untouched. The archcore-plugins marketplace registration itself stays, because other plugins may still use it. A host whose listing shows no plugin is skipped in silence. A host whose CLI is off PATH but whose on-disk registry names the plugin gets its exact uninstall command printed.

By hand, per host:

Host	Uninstall
Claude Code	/plugin uninstall archcore@archcore-plugins
Cursor	Remove Archcore from plugin settings, then delete the archcore entry from your Cursor MCP config
Codex CLI	codex plugin remove archcore@archcore-plugins
GitHub Copilot CLI	copilot plugin uninstall archcore

The archcore CLI is a separate install. To remove it as well, use the same script that installed it.

Next steps

• Supported AI agents confirms which features your host supports.
• Plugin skills documents the outcome, examples, and flags for each command.
• archcore plugin is the full command reference for install, update, remove, and status.