Plugin Troubleshooting

Plugin

Common issues specific to running the plugin inside Claude Code, Cursor, or Codex CLI. For CLI-level issues (MCP not reachable, .archcore/ missing, validation errors), see CLI troubleshooting.

/archcore:* commands don’t appear

Symptom: Typing /archcore:help does nothing, or the autocomplete doesn’t list Archcore skills.

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 — you should see a short “Archcore context loaded” line. If not, 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.

”Plugin failed to load”

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

Most common causes:

• The plugin package is missing .claude-plugin/plugin.json (Claude Code) or .cursor-plugin/plugin.json (Cursor).
• 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 .mcp.json at its root running archcore mcp from your PATH. If MCP is unreachable, one of these is usually the cause:

1. Plugin didn’t load cleanly. Run /plugin — archcore should be listed. If 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. Benign — 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 would read one project’s .archcore/ across every Cursor window. Verify 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”.

This is the PreToolUse hook doing its job. The fix is to 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 genuinely need to edit settings.json or .sync-state.json, those paths are allowed — only document files (*.md) are blocked.

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 gives a 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 check-code-alignment hook (PreToolUse on Write|Edit) runs the injection. It exits silently when:

• The edit target lives under .archcore/ (the sister hook check-archcore-write handles that case).
• The path is outside your configured source roots. Defaults: src, lib, app, pkg, cmd, internal, apps, packages, modules, components. Override via .archcore/settings.json → codeAlignment.sourceRoots (JSON array of directory names).
• No .archcore/ documents reference that path.
• The env var ARCHCORE_DISABLE_INJECTION=1 is set.

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 is non-blocking by design — if it errors, it exits silently rather than holding up the edit. So absence of output ≠ broken hook; it usually means “nothing relevant to inject.”

Cascade warnings overwhelm the output

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

This means a lot of documents are linked to the one you just changed. That’s working-as-intended — but you can reduce noise by:

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

There’s 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 — 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 an under-development feature flag (default off). Enable it:

codex features enable plugin_hooks

After enabling, restart the Codex session so the new hook configuration is picked up. 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 plugin_hooks is not enabled (see above). Without the feature flag, none of the hooks fire — 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 spawning 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).

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.

That’s deliberate — the matcher is Write|Edit. If you truly need to bypass (one-off rename, recovering from a corrupted state), edit the file from a separate shell with vim/$EDITOR; the plugin doesn’t intercept shells.

Next steps

• How plugin works — understand what each hook is doing before debugging.
• CLI troubleshooting — for MCP/validate issues.
• Supported AI agents — for host-specific differences.