Integrating with Claude Code

Claude Code is a primary integration surface for AlienMonster. It reads your strategy repo before non-trivial changes and calls AlienMonster's MCP tools when it needs additional context.

Setup

1. Install Claude Code if you haven't already.
2. Log into AlienMonster and register the MCP server:

$ npx alienmonster login
$ npx alienmonster connect
  👾 Connecting AlienMonster MCP...
  ✅ Claude Code: registered via `claude mcp add`

connect fetches a long-lived bearer token from the server and adds the AlienMonster MCP server to Claude Code via claude mcp add. Verify with:

$ claude mcp list
  alienmonster  https://alienmonster.ai/mcp  (connected)

The PreToolUse hook

init adds a PreToolUse hook to .claude/settings.json. The hook runs alienmonster status before each of Claude Code's tool calls. If your local cache is behind the server, Claude Code sees a stale-cache warning before it acts.

See Agent config files for the exact hook payload.

Reading the CLAUDE.md managed section

Claude Code reads CLAUDE.md at the start of every session. AlienMonster's managed section in that file inlines your project's strategy context and tells Claude to consult the repo before making non-trivial changes.

Your own content in CLAUDE.md (below the marker) is untouched by regeneration.

Typical agent behavior

When you ask Claude Code for a non-trivial change, it consults the strategy before acting. For example:

> Add Stripe webhook handling to the checkout flow.

⚙ get_relevant_powers(feature_description: "stripe webhook handling")

Before I start — the strategy repo says you chose Paddle over Stripe:

  [.alienmonster/decisions.md · DEC-DEC-001]
  Paddle chosen over Stripe for automatic EU VAT handling.

Do you want to proceed with Stripe anyway, or should I scaffold Paddle
webhooks instead?

The tool get_relevant_powers is one of nine user-visible tools — see MCP integration.

Reconnecting after a release

MCP connection state may need refreshing after AlienMonster deploys an update. If Claude Code reports "connection expired" or tool calls start failing, re-run npx alienmonster connect to restore the link. Your strategy data persists server-side across deploys — you're only re-establishing the connector.

Debugging: agent is not reading strategy

• Check that CLAUDE.md exists at repo root and contains the AlienMonster managed section. Re-run npx alienmonster init if missing.
• Verify MCP registration: claude mcp list should show alienmonster. If missing, re-run npx alienmonster connect.
• Check sync state: npx alienmonster status. If your cache is stale, run npx alienmonster sync.
• For more failure modes, see Troubleshooting.

Last verified: 2026-04-24