Troubleshooting

The most common failure modes, grouped by activity. For each, you'll see the symptom, the likely cause, the command to fix it, and a link to deeper docs.

Capture issues

Facilitator is not responding in Claude.ai

Symptom: You ask Claude.ai to run a strategy session and nothing happens.

Likely cause: The AlienMonster connector is not active or the token is invalid.

Fix: In Claude.ai, open Customize → Connectors and verify AlienMonster appears as connected. If not, reconnect using the guide at Capturing strategy in Claude.ai.

Session won't start from Claude Code

Symptom: You say "run a brainstorm session" in Claude Code; it doesn't call any tools.

Likely cause: MCP registration is missing or auth expired.

Fix:

$ claude mcp list
  (alienmonster missing?)
$ npx alienmonster connect

See Capturing strategy in Claude Code.

Integration issues

Coding agent is not reading my strategy

Symptom: Your agent makes changes that contradict a recorded decision or ignore a risk you captured.

Likely cause: The managed section in CLAUDE.md, AGENTS.md, or .cursorrules is missing or stale.

Fix: Re-run init — it refreshes managed sections without touching your own content.

$ npx alienmonster init
  ✅ Refreshed AlienMonster-managed section in CLAUDE.md

See Agent config files.

MCP tools not available in Claude Code

Symptom: Tool calls fail with "tool not found" or claude mcp list doesn't show AlienMonster.

Fix:

$ npx alienmonster connect
  ✅ Claude Code: registered via `claude mcp add`

See Integrating with Claude Code.

Cursor does not see AlienMonster

Symptom: Cursor's MCP panel doesn't list AlienMonster.

Likely cause: ~/.cursor/mcp.json missing the entry, or Cursor was open when connect ran.

Fix: Run npx alienmonster connect, then restart Cursor. See Integrating with Cursor.

MCP connection shows "Connection expired"

Symptom: Claude.ai (or another client) shows a "Connection has expired" or "Connection issue" message on the AlienMonster connector.

Cause: AlienMonster's MCP server state refreshes when we deploy updates. Your connector's stored credentials may need to be re-established after a release.

Fix: Click Connect or Reconnect on the connector card. If that doesn't work, remove the connector and re-add it through Settings → MCP → Claude.ai.

This reconnection only takes a few seconds and doesn't delete any of your strategy data — primitives, sessions, and repo files are stored server-side and persist across deploys.

Sync issues

Status shows "behind N revisions"

Symptom: alienmonster status reports the local cache is behind the server.

Likely cause: Expected — someone pushed a primitive (via MCP or the web UI) after your last sync.

Fix:

$ npx alienmonster sync

Or keep npx alienmonster watch running in the background for continuous auto-sync. See Sync model.

Sync lock held by another process

Symptom: sync or export fails with "Locked at .alienmonster/.sync-lock".

Likely cause: Another AlienMonster process (another sync, a watch, or an export) is currently writing in the same directory.

Fix: Wait a few seconds and retry. Dead-process locks auto-release after 30 seconds. If the lock persists indefinitely, verify no alienmonster process is still running — if not, you can safely delete .alienmonster/.sync-lock.

Auth expired

Symptom: Commands fail with "Session expired" or exit code 3.

Likely cause: Your token has expired (they last about 30 days).

Fix:

$ npx alienmonster logout
$ npx alienmonster login

Cache looks corrupted

Symptom: Files in .alienmonster/ look truncated, mismatched, or strangely edited.

Fix: Run a full rewrite from the server:

$ npx alienmonster export

If that still shows issues, file a bug. See Sync model for the server-authoritative model.

Didn't find your issue?

If none of the above matched, drop a note in your AlienMonster-internal support channel (or email daniel@alienmonster.ai) with alienmonster status --json output and the command that failed.