ruvbot is not installed. Install it with: npm install ruvbot

Error message

ruvbot is not installed. Install it with: npm install ruvbot@0.1.8
ruvbot is an optional peer dependency of @claude-flow/guidance.

What it means

The ruvbot integration (AIDefenceGate and friends) lazily dynamic-imports the 'ruvbot' package on first use; if module resolution fails it throws this error with install instructions because ruvbot is an optional peer dependency that @claude-flow/guidance does not install for you. The failed import is not cached, so the error repeats until the package is actually present.

Source

Thrown at v3/@claude-flow/guidance/src/ruvbot-integration.ts:183

 * Module specifiers kept in variables so TypeScript does not attempt
 * compile-time resolution of this optional peer dependency.
 */
const RUVBOT_MODULE = 'ruvbot';
const RUVBOT_CORE_MODULE = 'ruvbot/core';

/**
 * Attempt to dynamically import the ruvbot package.
 * Throws a descriptive error if the package is not installed.
 */
async function requireRuvBot(): Promise<Record<string, unknown>> {
  if (ruvbotModuleCache) return ruvbotModuleCache;

  try {
    const mod = await import(RUVBOT_MODULE) as Record<string, unknown>;
    ruvbotModuleCache = mod;
    return mod;
  } catch {
    throw new Error(
      'ruvbot is not installed. Install it with: npm install ruvbot@0.1.8\n' +
      'ruvbot is an optional peer dependency of @claude-flow/guidance.',
    );
  }
}

/**
 * Attempt to dynamically import ruvbot/core sub-export.
 */
async function requireRuvBotCore(): Promise<Record<string, unknown>> {
  try {
    return await import(RUVBOT_CORE_MODULE) as Record<string, unknown>;
  } catch {
    // Fall back to the main export
    return requireRuvBot();
  }
}

View on GitHub (pinned to fa13ee4ad6)

Solutions

Install the expected version: npm install ruvbot@0.1.8
If you do not use AI-defence features, do not construct AIDefenceGate — nothing else needs ruvbot
If you ship code paths that use the gate, declare ruvbot in your own package.json dependencies so installs are deterministic
Verify resolution in the target environment: node -e "import('ruvbot').then(() => console.log('ok'), e => process.exit(1))"

Example fix

// before
const gate = new AIDefenceGate({}); // first use throws: ruvbot not installed
// after (shell)
// npm install ruvbot@0.1.8
// after (optional runtime feature-detect)
const hasRuvbot = await import('ruvbot').then(() => true, () => false);
const gate = hasRuvbot ? new AIDefenceGate({}) : null;

Defensive patterns

Strategy: validation

Validate before calling

// feature-detect before enabling ruvbot-backed gates
const hasRuvbot = await import('ruvbot').then(() => true, () => false);
if (config.enableAiDefence && !hasRuvbot) {
  throw new Error('AI defence requested but ruvbot is not installed. Run: npm install ruvbot@0.1.8');
}

Type guard

async function canUseAIDefence(): Promise<boolean> {
  try {
    await import('ruvbot');
    return true;
  } catch {
    return false;
  }
}

Try / catch

try {
  const gate = new AIDefenceGate({});
} catch (err) {
  if (err instanceof Error && err.message.startsWith('ruvbot is not installed')) {
    // degrade gracefully or fail config validation; installing is the real fix
    logger.warn('AI defence disabled: optional dependency ruvbot missing');
  } else {
    throw err;
  }
}

Prevention

Declare ruvbot in package.json dependencies if any shipped code path constructs AIDefenceGate
Add a CI check that optional peers resolve when the feature flag is on
Docker/production installs prune optional peer deps — install ruvbot explicitly

When it happens

Trigger: Constructing or first-using AIDefenceGate / RuvBotMemoryAdapter / RuvBotGuidanceBridge without ruvbot installed; CI images or --production installs that prune optional peer deps; monorepo hoisting that removes the package from the resolution path.

Common situations: Enabling AI-defence features (prompt-injection, jailbreak, PII detection) in an environment where the dependency was never added; fresh clones relying on a colleague's global install; Docker images built from a trimmed dependency tree.

Related errors

AI-assisted analysis of ruvnet/ruflo@fa13ee4ad6 (2026-08-18). Data as JSON: /api/errors/7bf5e811732a0127. Report an issue: GitHub.