feat: add AI-powered command suggestions for unrecognized commands

When a CLI command is not recognized, the CLI now asks an AI tool to
suggest the correct command. Features:

- Cascading fallback through AI tools: ollama → claude → copilot
- Address masking: 0x addresses are replaced with placeholders (0xAAAA,
  0xBBBB, etc.) before sending to AI and restored in the response
- Auto-detection of ollama models (prefers 2-5GB models)
- Dynamic extraction of available commands from Commander.js

AI tool configurations:
- ollama: auto-detects available model, uses --quiet flag
- claude: uses haiku model with --print flag
- copilot: uses claude-haiku-4.5 model with --prompt flag

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: katspaugh

src/cli.ts

@@ -29,6 +29,7 @@ import { pullTransactions } from './commands/tx/pull.js'
 import { syncTransactions } from './commands/tx/sync.js'
 import { handleError } from './utils/errors.js'
 import { setGlobalOptions, type GlobalOptions } from './types/global-options.js'
+import { getAISuggestionService } from './services/ai-suggestion-service.js'
 
 const program = new Command()
 
@@ -53,6 +54,60 @@ program
     })
   })
 
+/**
+ * Recursively extracts all commands from a Commander program/command.
+ * Returns commands in format like "config init", "wallet list", etc.
+ */
+function getAvailableCommands(cmd: Command, prefix: string = ''): string[] {
+  const commands: string[] = []
+
+  for (const subCmd of cmd.commands) {
+    const cmdName = subCmd.name()
+    const fullName = prefix ? `${prefix} ${cmdName}` : cmdName
+    const usage = subCmd.usage()
+
+    // Add the command with its usage (arguments)
+    if (usage) {
+      commands.push(`${fullName} ${usage}`)
+    } else {
+      commands.push(fullName)
+    }
+
+    // Recursively get subcommands
+    commands.push(...getAvailableCommands(subCmd, fullName))
+  }
+
+  return commands
+}
+
+// Handle unknown commands with AI suggestions
+program.on('command:*', async (operands: string[]) => {
+  const unknownCommand = operands[0]
+  const args = operands.slice(1)
+
+  console.error(`error: unknown command '${unknownCommand}'`)
+
+  // Try to get AI suggestion
+  const aiService = getAISuggestionService()
+  console.error('\nAsking AI for suggestions...')
+
+  try {
+    const availableCommands = getAvailableCommands(program)
+    const suggestion = await aiService.getSuggestion(unknownCommand, args, availableCommands)
+    if (suggestion) {
+      console.error('\nAI suggestion:')
+      console.error(suggestion)
+    } else {
+      console.error('\nNo AI tools available for suggestions.')
+      console.error(`Run 'safe --help' to see available commands.`)
+    }
+  } catch {
+    console.error(`\nRun 'safe --help' to see available commands.`)
+  }
+
+  process.exit(1)
+})
+
 // Config commands
 const config = program.command('config').description('Manage CLI configuration')
 

src/services/ai-suggestion-service.ts

@@ -0,0 +1,280 @@
+import { spawn } from 'child_process'
+
+interface AITool {
+  name: string
+  command: string
+  args: (prompt: string) => string[]
+  available?: boolean
+}
+
+interface AddressMapping {
+  placeholder: string
+  original: string
+}
+
+/**
+ * Service for getting AI-powered command suggestions when a command is not recognized.
+ * Uses cascading fallback through multiple AI CLI tools.
+ */
+export class AISuggestionService {
+  private aiTools: AITool[] = [
+    {
+      name: 'ollama',
+      command: 'ollama',
+      args: (prompt: string) => ['run', '__AUTO_DETECT__', '--quiet', prompt],
+    },
+    {
+      name: 'claude',
+      command: 'claude',
+      args: (prompt: string) => ['--print', '--model', 'haiku', prompt],
+    },
+    {
+      name: 'copilot',
+      command: 'copilot',
+      args: (prompt: string) => ['--prompt', prompt, '--model', 'claude-haiku-4.5'],
+    },
+  ]
+
+  private ollamaModel: string | null = null
+
+  /**
+   * Detects the best available ollama model (prefers 3B-8B models for speed/quality balance).
+   */
+  private async detectOllamaModel(): Promise<string | null> {
+    if (this.ollamaModel !== null) {
+      return this.ollamaModel || null
+    }
+
+    try {
+      const output = await this.runCommand('ollama', ['list'], 5000)
+      const lines = output.split('\n').slice(1) // Skip header
+
+      // Parse model names and sizes, prefer smaller capable models
+      const models: { name: string; sizeGB: number }[] = []
+      for (const line of lines) {
+        const match = line.match(/^(\S+)\s+\S+\s+([\d.]+)\s*GB/)
+        if (match) {
+          models.push({ name: match[1], sizeGB: parseFloat(match[2]) })
+        }
+      }
+
+      if (models.length === 0) {
+        this.ollamaModel = ''
+        return null
+      }
+
+      // Sort by size (prefer 2-5GB models, then larger ones)
+      models.sort((a, b) => {
+        const aScore = a.sizeGB >= 2 && a.sizeGB <= 5 ? 0 : a.sizeGB < 2 ? 1 : 2
+        const bScore = b.sizeGB >= 2 && b.sizeGB <= 5 ? 0 : b.sizeGB < 2 ? 1 : 2
+        if (aScore !== bScore) return aScore - bScore
+        return a.sizeGB - b.sizeGB
+      })
+
+      this.ollamaModel = models[0].name
+      return this.ollamaModel
+    } catch {
+      this.ollamaModel = ''
+      return null
+    }
+  }
+
+  private addressMappings: AddressMapping[] = []
+  private placeholderIndex = 0
+
+  /**
+   * Strips ANSI escape codes from a string.
+   */
+  private stripAnsi(str: string): string {
+    // eslint-disable-next-line no-control-regex
+    return str.replace(/\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g, '')
+  }
+
+  /**
+   * Masks all 0x addresses in the input with placeholders like 0xAAAA, 0xBBBB, etc.
+   */
+  maskAddresses(input: string): string {
+    this.addressMappings = []
+    this.placeholderIndex = 0
+
+    // Match Ethereum addresses (0x followed by 40 hex characters) or shorter hex strings starting with 0x
+    const addressRegex = /0x[a-fA-F0-9]+/g
+
+    return input.replace(addressRegex, (match) => {
+      // Check if we already have a mapping for this address
+      const existing = this.addressMappings.find((m) => m.original === match)
+      if (existing) {
+        return existing.placeholder
+      }
+
+      const placeholder = this.generatePlaceholder()
+      this.addressMappings.push({ placeholder, original: match })
+      return placeholder
+    })
+  }
+
+  /**
+   * Unmasks placeholders back to original addresses in the AI response.
+   */
+  unmaskAddresses(response: string): string {
+    let result = response
+    for (const mapping of this.addressMappings) {
+      // Replace all occurrences of the placeholder (case-insensitive)
+      const regex = new RegExp(mapping.placeholder, 'gi')
+      result = result.replace(regex, mapping.original)
+    }
+    return result
+  }
+
+  /**
+   * Generates a placeholder like 0xAAAA, 0xBBBB, 0xCCCC, etc.
+   */
+  private generatePlaceholder(): string {
+    const letters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
+    const letter = letters[this.placeholderIndex % letters.length]
+    const repeat = Math.floor(this.placeholderIndex / letters.length) + 1
+    this.placeholderIndex++
+    return `0x${letter.repeat(4 * repeat)}`
+  }
+
+  /**
+   * Checks if a command exists on the system.
+   */
+  private async commandExists(command: string): Promise<boolean> {
+    return new Promise((resolve) => {
+      const check = spawn('which', [command], {
+        stdio: ['pipe', 'pipe', 'pipe'],
+      })
+      check.on('close', (code) => {
+        resolve(code === 0)
+      })
+      check.on('error', () => {
+        resolve(false)
+      })
+    })
+  }
+
+  /**
+   * Runs a command and returns its output.
+   */
+  private runCommand(command: string, args: string[], timeoutMs: number = 30000): Promise<string> {
+    return new Promise((resolve, reject) => {
+      const proc = spawn(command, args, {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: { ...process.env, NO_COLOR: '1' },
+      })
+
+      let stdout = ''
+      let stderr = ''
+
+      proc.stdout?.on('data', (data) => {
+        stdout += data.toString()
+      })
+
+      proc.stderr?.on('data', (data) => {
+        stderr += data.toString()
+      })
+
+      const timeout = setTimeout(() => {
+        proc.kill('SIGTERM')
+        reject(new Error('Command timed out'))
+      }, timeoutMs)
+
+      proc.on('close', (code) => {
+        clearTimeout(timeout)
+        if (code === 0 && stdout.trim()) {
+          resolve(stdout.trim())
+        } else {
+          reject(new Error(stderr || `Command exited with code ${code}`))
+        }
+      })
+
+      proc.on('error', (err) => {
+        clearTimeout(timeout)
+        reject(err)
+      })
+    })
+  }
+
+  /**
+   * Gets a command suggestion from AI tools using cascading fallback.
+   * @param invalidCommand The command that was not recognized
+   * @param args The arguments that were passed
+   * @param availableCommands List of available commands to help the AI
+   * @returns AI suggestion or null if all tools fail
+   */
+  async getSuggestion(
+    invalidCommand: string,
+    args: string[],
+    availableCommands: string[]
+  ): Promise<string | null> {
+    const fullCommand = [invalidCommand, ...args].join(' ')
+    const maskedCommand = this.maskAddresses(fullCommand)
+
+    const prompt = `I'm using a CLI tool called "safe" for managing Safe Smart Account (multisig wallets). The user tried to run this command but it was not recognized:
+
+safe ${maskedCommand}
+
+Available commands are:
+${availableCommands.map((cmd) => `- safe ${cmd}`).join('\n')}
+
+Based on the invalid command, suggest what the user probably meant to type. Be very concise - just provide the corrected command and a one-line explanation. If you can't determine what they meant, say so briefly.`
+
+    for (const tool of this.aiTools) {
+      try {
+        const exists = await this.commandExists(tool.command)
+        if (!exists) {
+          continue
+        }
+
+        let toolArgs = tool.args(prompt)
+
+        // Handle ollama model auto-detection
+        if (tool.name === 'ollama' && toolArgs.includes('__AUTO_DETECT__')) {
+          const model = await this.detectOllamaModel()
+          if (!model) {
+            continue
+          }
+          toolArgs = toolArgs.map((arg) => (arg === '__AUTO_DETECT__' ? model : arg))
+        }
+
+        let response = await this.runCommand(tool.command, toolArgs)
+
+        if (response) {
+          // Strip ANSI escape codes (e.g., from ollama's spinner)
+          response = this.stripAnsi(response).trim()
+          const unmaskedResponse = this.unmaskAddresses(response)
+          return unmaskedResponse
+        }
+      } catch {
+        // Tool failed, try next one
+        continue
+      }
+    }
+
+    return null
+  }
+
+  /**
+   * Gets available AI tools on the system.
+   */
+  async getAvailableTools(): Promise<string[]> {
+    const available: string[] = []
+    for (const tool of this.aiTools) {
+      if (await this.commandExists(tool.command)) {
+        available.push(tool.name)
+      }
+    }
+    return available
+  }
+}
+
+// Singleton instance
+let instance: AISuggestionService | null = null
+
+export function getAISuggestionService(): AISuggestionService {
+  if (!instance) {
+    instance = new AISuggestionService()
+  }
+  return instance
+}