Plugin Troubleshooting

Plugin

These issues appear when you run the plugin inside Claude Code, Cursor, Codex CLI, or GitHub Copilot CLI. For CLI-level issues (MCP not reachable, .archcore/ missing, validation errors), see CLI troubleshooting.

/archcore:* commands don’t appear

Symptom: Typing /archcore: doesn’t autocomplete, or the list is missing init, plan, document, or review.

Checks, in order:

1. Plugin is installed.

   # Claude Code
   claude plugin list
   # Cursor: check plugin settings

   You should see archcore@archcore-plugins.

2. Host was restarted. Plugins load at startup. After installing or updating, restart the host.

3. Session-start hook ran. Look at the session opening messages for a short “Archcore context loaded” line. If it is missing, the hook didn’t fire.

4. Run archcore doctor from your shell. The CLI validates .archcore/ integrity. For plugin-side install issues (missing skills, hook scripts, manifest problems), reinstall via the marketplace. See Install the plugin.

”Plugin failed to load”

Symptom: The host reports a plugin load error at session start.

Most common causes:

• The plugin package is missing the manifest its host reads: .claude-plugin/plugin.json (Claude Code), .cursor-plugin/plugin.json (Cursor), .codex-plugin/plugin.json (Codex CLI), or .plugin/plugin.json (GitHub Copilot CLI).
• A skill file’s YAML frontmatter is malformed.
• A hook script is not executable.

Fix: Reinstall from the marketplace:

claude plugin uninstall archcore@archcore-plugins
claude plugin install archcore@archcore-plugins

For local dev installs, ensure bin/* scripts are executable (chmod +x bin/*).

MCP server not found (Claude Code)

Symptom: Commands run but the agent reports “MCP tool not available” or “server not connected”.

The plugin ships .claude.mcp.json at its root, referenced from .claude-plugin/plugin.json, which runs archcore mcp from your PATH. If MCP is unreachable, check these causes:

1. Plugin didn’t load cleanly. Run /plugin; archcore should be listed. If it is not, reinstall:

   claude plugin uninstall archcore@archcore-plugins
   claude plugin install archcore@archcore-plugins

2. archcore not on PATH. From a shell:

   archcore --version

   If this fails, install the CLI via https://docs.archcore.ai/cli/install/ and restart Claude Code so it inherits the updated PATH.
3. Duplicate-server warning in /plugin UI. If /plugin shows “Errors (1)” with an archcore MCP message, a user- or project-registered archcore has the same command. The warning is harmless, because both registrations resolve to the same binary on PATH. To silence it, remove the redundant user registration (claude mcp remove archcore) or the project .mcp.json entry.

For issues that are clearly CLI-side (.archcore/ validation, archcore doctor errors).

CLI-level MCP troubleshooting →

MCP server not found (Cursor)

Cursor does not auto-register plugin-provided MCP. Copy docs/cursor.mcp.example.json from the plugin 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. Without it, a single registration reads one project’s .archcore/ across every Cursor window. Then verify that the CLI itself resolves:

archcore --version

If that fails, install via https://docs.archcore.ai/cli/install/ and relaunch Cursor.

Cursor: MCP attached to the wrong project

Symptom: MCP tools answer from a different project’s .archcore/ than the one currently open in Cursor.

Your Cursor MCP registration is missing the --project ${workspaceFolder} argument (or has a literal path baked in). Without it, Cursor reuses the first registration across every window and the MCP server reads whichever .archcore/ that initial registration was scoped to. Re-copy the docs/cursor.mcp.example.json template and restart Cursor.

Writes blocked unexpectedly

Symptom: The agent tries to fix a typo in a .archcore/ file and gets blocked. The hook says “use MCP tools instead”.

The PreToolUse hook blocks that edit by design. Use update_document with the new content instead of Edit. Ask the agent:

Use update_document to correct the typo in the frontmatter title.

If you need to edit settings.json or .sync-state.json, those paths are allowed. The hook blocks only document files (*.md).

Validation fails after every write

Symptom: Every time a skill creates or updates a document, the post-mutation hook reports a validation error.

1. Run archcore doctor from the shell. The CLI reports the precise error.
2. Common causes: slug with uppercase letters, missing title/status frontmatter, tag with forbidden characters.
3. Skills should handle all three; if they don’t, file a bug on the plugin repo.

Automatic context injection didn’t fire

Symptom: You expected the agent to see relevant rules / ADRs before editing src/..., but it didn’t, and no context summary was printed.

The pre-write hook runs the injection, through archcore hooks <host> pre-tool-use. It stays silent when:

• The edit target lives under .archcore/. That path is the write guard’s business.
• The path is outside your configured source roots. Defaults: src, lib, app, pkg, cmd, internal, apps, packages, modules, components. Set codeAlignment.sourceRoots in .archcore/settings.json to replace that list (a JSON array of directory names).
• No .archcore/ documents reference that path.
• The env var ARCHCORE_DISABLE_INJECTION=1 is set.
• The host is GitHub Copilot, whose pre-write event carries only a permission decision.
• The installed CLI is older than v0.7.0. The launcher exits silently rather than risk a usage error reading as a deny.

To verify it’s enabled, unset the env var and ensure the edited file is under one of the configured roots. To turn it off temporarily:

export ARCHCORE_DISABLE_INJECTION=1

The hook never blocks an edit: if it errors, it exits silently. Absence of output does not mean the hook is broken. It usually means the hook found nothing relevant to inject.

”Update your CLI” nudge at session start

Symptom: A session opens with a message that your .archcore/settings.json uses a newer setting (e.g. global sources) that the installed archcore CLI is too old to understand, and that MCP and context are unavailable until you update.

A project that declares global sources carries a globals field in settings.json. An older, pre-globals CLI uses a strict config parser that rejects unknown fields, so every config-loading command (mcp, hooks, doctor) fails. The host launches archcore mcp directly, so the plugin can’t wrap that crash. The session-start hook is the one place where it can turn the cryptic failure into a clear nudge.

Fix: Update the CLI, then restart the host:

# macOS / Linux / WSL
curl -fsSL https://archcore.ai/install.sh | bash
# Windows (PowerShell)
irm https://archcore.ai/install.ps1 | iex

archcore --version   # verify

The advisory is rate-limited to once per 24h and fires only on the strict parser’s exact field-rejection signature. A current CLI that understands globals never triggers it, even in projects that declare globals.

A declared global source is missing

Symptom: The session-start context shows a warning that a global source named in settings.json couldn’t be found, and only local documents were loaded.

With a current CLI, a missing global doesn’t block your session. The hook degrades to a local-only context summary and names the missing source, so your own documents still load. The MCP server itself still fails fast on a missing global; see CLI troubleshooting.

Fix: Clone or vendor the source so its path resolves, or remove the entry from globals if it’s no longer needed.

Cascade warnings overwhelm the output

Symptom: Every mutation dumps a long “cascade dependents may need review” block.

Many documents link to the one you just changed. The warnings are intended. To reduce the noise:

• Split the updated document into smaller, more focused pieces.
• Accept some cascade drift deliberately (status accepted on the dependent means “I’ve reviewed this”).

There is no global mute. The warning is intentional friction.

Cursor-specific: afterMCPExecution not firing

Symptom: On Cursor, validation and cascade checks don’t run after MCP calls.

Cursor only fires afterMCPExecution for successful MCP calls. If the MCP call itself failed (invalid frontmatter, for example), the hook won’t fire, and you’ll see the MCP error directly.

Codex CLI-specific: hooks not firing

Symptom: On Codex CLI, the validation, cascade, precision, and pre-edit context-injection hooks don’t run.

Codex hooks are gated by Codex’s 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. After you enable the feature, restart the Codex session so it picks up the new hook configuration. If hooks still don’t fire, verify your Codex version is 0.117.0 or later (codex --version).

Codex CLI-specific: apply_patch writes not blocked

Symptom: On Codex CLI, you used Codex’s apply_patch tool to edit a .archcore/*.md file directly and the hook didn’t block it.

The Codex hooks file (hooks/codex.hooks.json) uses the matcher Write|Edit|apply_patch precisely to cover all three Codex write surfaces. If the matcher doesn’t appear to be catching apply_patch, the most likely cause is that Codex’s hooks feature is not enabled (see above). Without the feature, no hook fires, including the PreToolUse write guard.

Codex CLI-specific: MCP server not found

Symptom: On Codex CLI, MCP tool calls fail with “server not found” or similar.

The plugin ships .codex.mcp.json, referenced from the manifest’s mcpServers field. The command is archcore from PATH. Codex inherits the shell’s PATH when it spawns the MCP server, so the CLI must be installed globally.

Checks, in order:

1. Manifest references .codex.mcp.json. Open .codex-plugin/plugin.json and verify "mcpServers": "./.codex.mcp.json" is present.
2. .codex.mcp.json exists at plugin root. It should ship with the marketplace install. If missing, reinstall: codex plugin uninstall archcore, then codex plugin marketplace add archcore-ai/plugin and re-install Archcore from /plugins.
3. archcore is on PATH in the shell that launched Codex. Run archcore --version from that shell; if it fails, install via https://docs.archcore.ai/cli/install/ and re-launch Codex.

Codex CLI-specific: path env var

When wiring custom hooks or scripts that reference the plugin root on Codex, use ${PLUGIN_ROOT} — the host-neutral, canonical name. There is no ${CODEX_PLUGIN_ROOT} (and ${CLAUDE_PLUGIN_ROOT} is Claude-only).

Copilot-specific: no Archcore MCP tools in the session

Symptom: On GitHub Copilot CLI, the plugin loaded and the commands appear, but every Archcore operation reports that the document tools are unavailable. A session-start line says the project is not wired.

On Copilot the plugin ships no MCP server, so the project-level entry is the only source of document tools. Wire the project once:

archcore init --agent copilot --project "$PWD"

Restart the session afterwards so Copilot connects the server. Copilot discovers .mcp.json from the working directory up to the git root, and also reads ${COPILOT_HOME:-~/.copilot}/mcp-config.json, so a repository-root file wires a subdirectory session too.

The advisory is rate-limited to once per 24 hours per project. Suppress it with ARCHCORE_HIDE_WIRING_NUDGE=1.

Copilot-specific: no context before a source edit

Symptom: On GitHub Copilot CLI, the write guard blocks direct .archcore/ edits, but no rules or ADRs appear before a source-file edit.

Copilot’s preToolUse event carries only a permission decision, so it cannot receive advisory context (github/copilot-cli#2585). The write guard runs; the code-alignment injection does not. This is a host limitation, not a misconfiguration.

Copilot-specific: hooks appear to run twice

Symptom: Session-start context or post-write findings are printed twice.

Copilot also reads .claude/settings.json. A repository wired for both Copilot and Claude Code runs both configurations. The cost is duplicated output, never a wrong verdict.

Claude Code-specific: both Write and Edit blocked

Symptom: On Claude Code, you can’t fix a file manually even though you know what you’re doing.

The matcher is Write|Edit, so the hook blocks both. If you need to bypass it (a one-off rename, or recovery from a corrupted state), edit the file from a separate shell with vim or $EDITOR. The plugin doesn’t intercept shells.

Next steps

• How the plugin works explains what each hook does.
• CLI troubleshooting covers MCP and validation issues.
• Supported AI agents lists host-specific differences.