rohitg00/agentmemory · warning

Claude Code hooks fallback skipped: ${hookResult.reason}. MC

Error message

Claude Code hooks fallback skipped: ${hookResult.reason}. MCP wiring still applied.

What it means

agentmemory's `agentmemory connect claude-code` command wires the Claude Code MCP server into ~/.claude.json, and optionally installs lifecycle hooks. When --with-hooks is passed but installClaudeHooks() returns a 'skipped' result, the CLI logs this warning instead of failing, because MCP wiring already succeeded. It is informational: the connect succeeded, only the hooks add-on was not applied.

Source

Thrown at src/cli/connect/claude-code.ts:111

    writeJsonAtomic(CLAUDE_JSON, next);

    const verify = readJsonSafe<ClaudeConfig>(CLAUDE_JSON);
    if (!entryMatches(verify?.mcpServers?.["agentmemory"])) {
      p.log.error(
        `Verification failed: ${CLAUDE_JSON} did not contain mcpServers.agentmemory after write.`,
      );
      return { kind: "skipped", reason: "verification-failed" };
    }

    logInstalled("Claude Code", CLAUDE_JSON);
    p.log.info(
      "Restart Claude Code (or run `/mcp` inside a session) to pick up the new server.",
    );

    if (opts.withHooks) {
      const hookResult = installClaudeHooks(opts);
      if (hookResult.kind === "skipped") {
        p.log.warn(
          `Claude Code hooks fallback skipped: ${hookResult.reason}. MCP wiring still applied.`,
        );
      }
    }

    return { kind: "installed", mutatedPath: CLAUDE_JSON, backupPath };
  },
};

/**
 * Merge the bundled `plugin/hooks/hooks.json` into
 * `~/.claude/settings.json`'s top-level `hooks` field with absolute
 * script paths. Use this when agentmemory is NOT installed through
 * `/plugin marketplace add` (e.g. MCP standalone wiring), so the
 * hook scripts survive version bumps without `${CLAUDE_PLUGIN_ROOT}`
 * expansion (issue #508).
 *
 * Re-install strips entries whose command points under

View on GitHub (pinned to e04ba88819)

Solutions

  1. Read the interpolated hookResult.reason in the warning message — it states exactly why hooks were skipped (e.g. file missing, merge refused).
  2. Ensure Claude Code has been launched at least once so ~/.claude/settings.json exists, then re-run `agentmemory connect claude-code --with-hooks`.
  3. Check that the Claude config path (CLAUDE_JSON / settings dir) is writable by the user running the command.
  4. If hooks are not needed, ignore the warning — MCP wiring was still applied; verify with `claude mcp list` or /mcp in a session.
  5. Re-run the connect command after fixing the environment; connect is idempotent and safe to repeat.

Example fix

// before
agentmemory connect claude-code --with-hooks
// -> warning: Claude Code hooks fallback skipped: settings file not found ...

// after
claude --version        # launch once so ~/.claude/settings.json exists
ls ~/.claude/settings.json
agentmemory connect claude-code --with-hooks   # re-run; hooks installed
Defensive patterns

Strategy: validation

Validate before calling

import { existsSync } from "node:fs";
import { join } from "node:path";
const claudeDir = join(process.env.HOME ?? "", ".claude");
if (!existsSync(join(claudeDir, "settings.json"))) {
  console.error("Claude Code settings not found — launch `claude` once before `connect claude-code --with-hooks`.");
  process.exit(1);
}

Type guard

type HookInstallResult = { kind: "installed" } | { kind: "skipped"; reason: string };
function wasSkipped(r: unknown): r is { kind: "skipped"; reason: string } {
  return typeof r === "object" && r !== null && "kind" in r && (r as any).kind === "skipped";
}

Try / catch

try {
  const hookResult = installClaudeHooks(opts);
  if (hookResult.kind === "skipped") {
    console.warn(`Hooks not installed (${hookResult.reason}); MCP wiring is unaffected.`);
  }
} catch (err) {
  console.warn("Hook install failed; MCP wiring remains applied:", err);
}

Prevention

When it happens

Trigger: Running `agentmemory connect claude-code --with-hooks` when installClaudeHooks() returns { kind: "skipped", reason } — e.g. the Claude Code settings file is missing or unparseable, the target directory does not exist, or a hook-merge precondition fails.

Common situations: Users with a fresh machine where Claude Code has never been launched (no settings file), users who deleted or renamed ~/.claude, custom CLAUDE_CONFIG_DIR setups, or permission problems on the settings path. The MCP wiring still applied, so developers are confused why hooks (context injection) don't appear after a 'successful' connect.

Related errors

AI-assisted analysis of rohitg00/agentmemory@e04ba88819 (2026-08-30). Data as JSON: /api/errors/97d4a7cf9fe9823e. Report an issue: GitHub.