@mndrk/agx 1.0.2 → 1.3.0

package/.claude/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(node --check:*)",
+      "Bash(node index.js:*)",
+      "Bash(python:*)",
+      "Bash(npm publish:*)"
+    ]
+  }
+}

package/README.md

@@ -4,14 +4,55 @@ Unified AI Agent Wrapper for Gemini, Claude, and Ollama.
 
 ## Installation
 
-From the `agx` directory:
+### Via npm (recommended)
+
 ```bash
+npm install -g @mndrk/agx
+```
+
+### From source
+
+Clone the repository and link locally:
+
+```bash
+git clone https://github.com/ramarlina/agx.git
+cd agx
 npm link
 ```
-Now you can use `agx` globally.
+
+## Quick Start
+
+When you run `agx` for the first time, it will automatically start the setup wizard:
+
+```bash
+agx
+```
+
+The setup wizard will:
+1. Detect which AI providers are installed on your system
+2. Guide you through installing any missing providers
+3. Help you authenticate with your chosen providers
+4. Set your default provider
+
+After setup, you can start using agx immediately:
+
+```bash
+agx --prompt "hello world"
+```
 
 ## Usage
 
+### With Default Provider
+
+Once configured, you can run prompts without specifying a provider:
+
+```bash
+agx --prompt "explain this code"
+agx -p "summarize the file"
+```
+
+### With Specific Provider
+
 ```bash
 agx <provider> [options] --prompt "<prompt>"
 ```
@@ -44,11 +85,105 @@ Use `--` to pass arguments directly to the underlying CLI:
 agx claude -- --resume
 ```
 
+## Configuration Commands
+
+### `agx init`
+
+Run the setup wizard manually. This is useful if you want to reconfigure agx or add new providers:
+
+```bash
+agx init
+```
+
+The wizard will:
+- Detect installed providers (claude, gemini, ollama)
+- Guide you through installation and authentication
+- Let you set or change your default provider
+
+### `agx config`
+
+Open an interactive configuration menu to manage your agx settings:
+
+```bash
+agx config
+```
+
+### `agx add <provider>`
+
+Install a specific AI provider:
+
+```bash
+agx add claude    # Install Claude CLI
+agx add gemini    # Install Gemini CLI
+agx add ollama    # Install Ollama
+```
+
+### `agx login <provider>`
+
+Authenticate with a provider:
+
+```bash
+agx login claude    # Login to Claude
+agx login gemini    # Login to Gemini
+```
+
+### `agx status`
+
+View your current configuration, including installed providers and default settings:
+
+```bash
+agx status
+```
+
+Example output:
+```
+agx Configuration Status
+------------------------
+Default Provider: claude
+
+Installed Providers:
+  ✓ claude (authenticated)
+  ✓ gemini (authenticated)
+  ✓ ollama (running)
+
+Config file: ~/.agx/config.json
+```
+
+## Skill System
+
+agx includes a skill system that helps AI agents understand how to use agx effectively.
+
+### `agx skill`
+
+View the agx skill (LLM instructions):
+
+```bash
+agx skill
+```
+
+This displays the skill file that describes agx's capabilities and usage patterns for AI agents.
+
+### `agx skill install`
+
+Install the agx skill to Claude and/or Gemini so AI agents know how to use agx:
+
+```bash
+agx skill install
+```
+
+This adds the agx skill to your AI provider's skill directory, enabling features like:
+- AI agents can call other AI providers through agx
+- Cross-provider collaboration (e.g., Claude can ask Gemini for help)
+- Consistent command patterns across all providers
+
 ## LLM-Predictable Command Patterns
 
 For LLMs constructing commands, use these canonical patterns:
 
 ```bash
+# Pattern: agx --prompt "<prompt>" (uses default provider)
+agx --prompt "explain this code"
+
 # Pattern: agx <provider> --prompt "<prompt>"
 agx claude --prompt "explain this code"
 agx gemini --prompt "summarize the file"
@@ -69,7 +204,7 @@ agx claude --print --prompt "what is 2+2"
 ### Command Structure
 
 ```
-agx <provider> [--model <name>] [--yolo] [--print] --prompt "<prompt>"
+agx [provider] [--model <name>] [--yolo] [--print] --prompt "<prompt>"
 ```
 
 **Rules for LLMs:**
@@ -77,6 +212,30 @@ agx <provider> [--model <name>] [--yolo] [--print] --prompt "<prompt>"
 2. Quote the prompt with double quotes
 3. Place options before `--prompt`
 4. Use full provider names (`claude`, `gemini`, `ollama`) for clarity
+5. Provider is optional if a default is configured
+
+## Configuration File
+
+agx stores its configuration in `~/.agx/config.json`:
+
+```json
+{
+  "defaultProvider": "claude",
+  "providers": {
+    "claude": {
+      "installed": true,
+      "authenticated": true
+    },
+    "gemini": {
+      "installed": true,
+      "authenticated": true
+    },
+    "ollama": {
+      "installed": true
+    }
+  }
+}
+```
 
 ## Ollama Support
 

package/index.js

@@ -1,9 +1,746 @@
 #!/usr/bin/env node
 
-const { spawn } = require('child_process');
+const { spawn, execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+// Config paths
+const CONFIG_DIR = path.join(process.env.HOME || process.env.USERPROFILE, '.agx');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+
+// agx skill - instructions for LLMs on how to use agx
+const AGX_SKILL = `---
+name: agx
+description: Use agx to run AI agents (Claude, Gemini, Ollama) from the command line
+---
+
+# agx - Unified AI Agent CLI
+
+Use \`agx\` to run AI agents from the command line. It wraps Claude Code, Gemini CLI, and Ollama.
+
+## Syntax
+
+\`\`\`bash
+agx <provider> [options] --prompt "<prompt>"
+agx [options] --prompt "<prompt>"   # uses default provider
+\`\`\`
+
+## Providers
+
+| Provider | Aliases | Description |
+|----------|---------|-------------|
+| claude | c, cl | Anthropic Claude Code |
+| gemini | g, gem | Google Gemini CLI |
+| ollama | o, ol | Local Ollama models |
+
+## Common Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| --prompt | -p | The prompt to send |
+| --model | -m | Model name to use |
+| --yolo | -y | Skip permission prompts |
+| --print | | Non-interactive output |
+| --interactive | -i | Force interactive mode |
+
+## Examples
+
+\`\`\`bash
+# Simple prompt
+agx claude --prompt "explain this code"
+
+# Use default provider
+agx --prompt "what does this function do?"
+
+# Skip confirmations
+agx c --yolo --prompt "fix the tests"
+
+# Specify model
+agx ollama --model qwen3:8b --prompt "write a function"
+
+# Non-interactive (just output)
+agx gemini --print --prompt "summarize README.md"
+\`\`\`
+
+## When to use agx
+
+- Quick AI queries from terminal
+- Running prompts across different AI providers
+- Scripting AI interactions
+- When you need --yolo mode to skip confirmations
+`;
+
+// ANSI colors
+const c = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+  red: '\x1b[31m',
+  magenta: '\x1b[35m'
+};
+
+// Check if a command exists
+function commandExists(cmd) {
+  try {
+    execSync(`which ${cmd}`, { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Load config
+function loadConfig() {
+  try {
+    if (fs.existsSync(CONFIG_FILE)) {
+      return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+    }
+  } catch {}
+  return null;
+}
+
+// Save config
+function saveConfig(config) {
+  if (!fs.existsSync(CONFIG_DIR)) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  }
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
+}
+
+// Interactive prompt helper
+function prompt(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  return new Promise(resolve => {
+    rl.question(question, answer => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+// Detect available providers
+function detectProviders() {
+  return {
+    claude: commandExists('claude'),
+    gemini: commandExists('gemini'),
+    ollama: commandExists('ollama')
+  };
+}
+
+// Print provider status
+function printProviderStatus(providers) {
+  console.log(`\n${c.bold}Detected Providers:${c.reset}\n`);
+
+  const status = (installed) => installed
+    ? `${c.green}✓ installed${c.reset}`
+    : `${c.dim}✗ not found${c.reset}`;
+
+  console.log(`  ${c.cyan}claude${c.reset}  │ Anthropic Claude Code  │ ${status(providers.claude)}`);
+  console.log(`  ${c.cyan}gemini${c.reset}  │ Google Gemini CLI      │ ${status(providers.gemini)}`);
+  console.log(`  ${c.cyan}ollama${c.reset}  │ Local Ollama           │ ${status(providers.ollama)}`);
+}
+
+// Run a command with inherited stdio (interactive)
+function runInteractive(cmd, args = [], options = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, {
+      stdio: 'inherit',
+      shell: true,
+      ...options
+    });
+    child.on('close', (code) => resolve(code === 0));
+    child.on('error', () => resolve(false));
+  });
+}
+
+// Run a command silently and return success
+function runSilent(cmd) {
+  try {
+    execSync(cmd, { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Check if ollama server is running
+function isOllamaRunning() {
+  try {
+    execSync('curl -s http://localhost:11434/api/tags', { stdio: 'ignore', timeout: 2000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Get list of ollama models
+function getOllamaModels() {
+  try {
+    const result = execSync('ollama list 2>/dev/null', { encoding: 'utf8' });
+    const lines = result.trim().split('\n').slice(1); // skip header
+    return lines.map(l => l.split(/\s+/)[0]).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+// ==================== SKILL ====================
+
+// View the agx skill
+function showSkill() {
+  console.log(AGX_SKILL);
+}
+
+// Check if skill is installed for a provider
+function isSkillInstalled(provider) {
+  const skillDir = path.join(
+    process.env.HOME || process.env.USERPROFILE,
+    provider === 'claude' ? '.claude' : '.gemini',
+    'skills',
+    'agx'
+  );
+  return fs.existsSync(path.join(skillDir, 'SKILL.md'));
+}
+
+// Install agx skill to a provider's skills directory
+function installSkillTo(provider) {
+  const baseDir = path.join(
+    process.env.HOME || process.env.USERPROFILE,
+    provider === 'claude' ? '.claude' : '.gemini',
+    'skills',
+    'agx'
+  );
+
+  if (!fs.existsSync(baseDir)) {
+    fs.mkdirSync(baseDir, { recursive: true });
+  }
+
+  fs.writeFileSync(path.join(baseDir, 'SKILL.md'), AGX_SKILL);
+  return baseDir;
+}
+
+// Handle skill command
+async function handleSkillCommand(args) {
+  const subCmd = args[1];
+
+  if (!subCmd || subCmd === 'view' || subCmd === 'show') {
+    // Show skill content
+    console.log(`\n${c.bold}${c.cyan}/agx${c.reset} - ${c.dim}LLM instructions for using agx${c.reset}\n`);
+
+    // Check installation status
+    const claudeInstalled = isSkillInstalled('claude');
+    const geminiInstalled = isSkillInstalled('gemini');
+
+    if (claudeInstalled || geminiInstalled) {
+      console.log(`${c.green}Installed:${c.reset}`);
+      if (claudeInstalled) console.log(`  ${c.dim}~/.claude/skills/agx/SKILL.md${c.reset}`);
+      if (geminiInstalled) console.log(`  ${c.dim}~/.gemini/skills/agx/SKILL.md${c.reset}`);
+      console.log('');
+    }
+
+    console.log(c.dim + '─'.repeat(60) + c.reset);
+    console.log(AGX_SKILL);
+    console.log(c.dim + '─'.repeat(60) + c.reset);
+
+    if (!claudeInstalled && !geminiInstalled) {
+      console.log(`\n${c.dim}Install with: ${c.reset}agx skill install`);
+    }
+    console.log('');
+    return;
+  }
+
+  if (subCmd === 'install' || subCmd === 'add') {
+    const target = args[2]; // optional: claude, gemini, or all
+
+    console.log(`\n${c.bold}Install agx skill${c.reset}\n`);
+
+    if (!target || target === 'all') {
+      // Install to all available
+      const providers = detectProviders();
+      let installed = 0;
+
+      if (providers.claude) {
+        const dest = installSkillTo('claude');
+        console.log(`${c.green}✓${c.reset} Installed to ${c.dim}${dest}${c.reset}`);
+        installed++;
+      }
+
+      if (providers.gemini) {
+        const dest = installSkillTo('gemini');
+        console.log(`${c.green}✓${c.reset} Installed to ${c.dim}${dest}${c.reset}`);
+        installed++;
+      }
+
+      if (installed === 0) {
+        console.log(`${c.yellow}No providers installed.${c.reset} Run ${c.cyan}agx init${c.reset} first.`);
+      } else {
+        console.log(`\n${c.dim}LLMs can now use /agx to learn how to run agx commands.${c.reset}\n`);
+      }
+    } else if (target === 'claude' || target === 'gemini') {
+      const dest = installSkillTo(target);
+      console.log(`${c.green}✓${c.reset} Installed to ${c.dim}${dest}${c.reset}`);
+      console.log(`\n${c.dim}LLMs can now use /agx to learn how to run agx commands.${c.reset}\n`);
+    } else {
+      console.log(`${c.yellow}Unknown target:${c.reset} ${target}`);
+      console.log(`${c.dim}Usage: agx skill install [claude|gemini|all]${c.reset}\n`);
+    }
+    return;
+  }
+
+  // Unknown subcommand
+  console.log(`${c.bold}agx skill${c.reset} - Manage the agx skill for LLMs\n`);
+  console.log(`${c.dim}Commands:${c.reset}`);
+  console.log(`  ${c.cyan}agx skill${c.reset}              View the skill content`);
+  console.log(`  ${c.cyan}agx skill install${c.reset}      Install to all providers`);
+  console.log(`  ${c.cyan}agx skill install claude${c.reset}  Install to Claude only`);
+  console.log('');
+}
+
+// ==================== PROVIDERS ====================
+
+// Provider installation info
+const PROVIDERS = {
+  claude: {
+    name: 'Claude Code',
+    installCmd: 'npm install -g @anthropic-ai/claude-code',
+    description: 'Anthropic Claude AI assistant'
+  },
+  gemini: {
+    name: 'Gemini CLI',
+    installCmd: 'npm install -g @google/gemini-cli',
+    description: 'Google Gemini AI assistant'
+  },
+  ollama: {
+    name: 'Ollama',
+    installCmd: process.platform === 'darwin'
+      ? 'brew install ollama'
+      : 'curl -fsSL https://ollama.ai/install.sh | sh',
+    description: 'Local AI models'
+  }
+};
+
+// Install a provider
+async function installProvider(provider) {
+  const info = PROVIDERS[provider];
+  if (!info) return false;
+
+  console.log(`\n${c.cyan}Installing ${info.name}...${c.reset}\n`);
+  console.log(`${c.dim}$ ${info.installCmd}${c.reset}\n`);
+
+  const success = await runInteractive(info.installCmd);
+
+  if (success && commandExists(provider)) {
+    console.log(`\n${c.green}✓${c.reset} ${info.name} installed successfully!`);
+    return true;
+  } else {
+    console.log(`\n${c.red}✗${c.reset} Installation failed. Try manually:`);
+    console.log(`  ${c.dim}${info.installCmd}${c.reset}`);
+    return false;
+  }
+}
+
+// Login/authenticate a provider
+async function loginProvider(provider) {
+  console.log('');
+
+  if (provider === 'claude') {
+    console.log(`${c.cyan}Launching Claude Code for authentication...${c.reset}`);
+    console.log(`${c.dim}This will open a browser to log in with your Anthropic account.${c.reset}\n`);
+    await runInteractive('claude');
+    return true;
+  }
+
+  if (provider === 'gemini') {
+    console.log(`${c.cyan}Launching Gemini CLI for authentication...${c.reset}`);
+    console.log(`${c.dim}This will open a browser to log in with your Google account.${c.reset}\n`);
+    await runInteractive('gemini');
+    return true;
+  }
+
+  if (provider === 'ollama') {
+    // Check if server is running
+    if (!isOllamaRunning()) {
+      console.log(`${c.yellow}Ollama server is not running.${c.reset}`);
+      const startIt = await prompt(`Start it now? [Y/n]: `);
+      if (startIt.toLowerCase() !== 'n') {
+        console.log(`\n${c.cyan}Starting Ollama server in background...${c.reset}`);
+        spawn('ollama', ['serve'], {
+          detached: true,
+          stdio: 'ignore'
+        }).unref();
+        // Wait a moment for startup
+        await new Promise(r => setTimeout(r, 2000));
+        if (isOllamaRunning()) {
+          console.log(`${c.green}✓${c.reset} Ollama server started!`);
+        } else {
+          console.log(`${c.yellow}Server may still be starting. Run ${c.reset}ollama serve${c.yellow} manually if needed.${c.reset}`);
+        }
+      }
+    } else {
+      console.log(`${c.green}✓${c.reset} Ollama server is running`);
+    }
+
+    // Check for models
+    const models = getOllamaModels();
+    if (models.length === 0) {
+      console.log(`\n${c.yellow}No models installed.${c.reset}`);
+      console.log(`\n${c.bold}Popular models:${c.reset}`);
+      console.log(`  ${c.cyan}1${c.reset}) qwen3:8b      ${c.dim}(4.9 GB) - Great all-rounder${c.reset}`);
+      console.log(`  ${c.cyan}2${c.reset}) llama3.2:3b   ${c.dim}(2.0 GB) - Fast & lightweight${c.reset}`);
+      console.log(`  ${c.cyan}3${c.reset}) codellama:7b  ${c.dim}(3.8 GB) - Code specialist${c.reset}`);
+      console.log(`  ${c.cyan}4${c.reset}) mistral:7b    ${c.dim}(4.1 GB) - Good general model${c.reset}`);
+      console.log(`  ${c.cyan}5${c.reset}) Skip for now`);
+
+      const choice = await prompt(`\nWhich model to pull? [1]: `);
+      const modelMap = {
+        '1': 'qwen3:8b',
+        '2': 'llama3.2:3b',
+        '3': 'codellama:7b',
+        '4': 'mistral:7b',
+        '': 'qwen3:8b'
+      };
+      const model = modelMap[choice];
+      if (model) {
+        console.log(`\n${c.cyan}Pulling ${model}...${c.reset}`);
+        console.log(`${c.dim}This may take a few minutes depending on your connection.${c.reset}\n`);
+        await runInteractive(`ollama pull ${model}`);
+      }
+    } else {
+      console.log(`${c.green}✓${c.reset} Found ${models.length} model(s): ${c.dim}${models.slice(0, 3).join(', ')}${models.length > 3 ? '...' : ''}${c.reset}`);
+    }
+    return true;
+  }
+
+  return false;
+}
+
+// Run onboarding
+async function runOnboarding() {
+  console.log(`
+${c.bold}${c.cyan}╭─────────────────────────────────────────╮${c.reset}
+${c.bold}${c.cyan}│${c.reset}   ${c.bold}Welcome to agx${c.reset}                       ${c.cyan}│${c.reset}
+${c.bold}${c.cyan}│${c.reset}   ${c.dim}Unified AI Agent CLI${c.reset}                 ${c.cyan}│${c.reset}
+${c.bold}${c.cyan}╰─────────────────────────────────────────╯${c.reset}
+`);
+
+  let providers = detectProviders();
+  printProviderStatus(providers);
+
+  const missing = Object.entries(providers)
+    .filter(([_, installed]) => !installed)
+    .map(([name]) => name);
+
+  let available = Object.entries(providers)
+    .filter(([_, installed]) => installed)
+    .map(([name]) => name);
+
+  // Offer to install missing providers
+  if (missing.length > 0) {
+    console.log(`\n${c.bold}Would you like to install any providers?${c.reset}\n`);
+
+    for (const provider of missing) {
+      const info = PROVIDERS[provider];
+      const answer = await prompt(`  Install ${c.cyan}${provider}${c.reset} (${info.description})? [y/N]: `);
+
+      if (answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes') {
+        const success = await installProvider(provider);
+        if (success) {
+          providers[provider] = true;
+          available.push(provider);
+        }
+      }
+    }
+
+    // Re-detect after installations
+    providers = detectProviders();
+    available = Object.entries(providers)
+      .filter(([_, installed]) => installed)
+      .map(([name]) => name);
+  }
+
+  // No providers available
+  if (available.length === 0) {
+    console.log(`\n${c.yellow}⚠${c.reset}  No AI providers installed.\n`);
+    console.log(`${c.dim}Run ${c.reset}agx init${c.dim} again to install providers.${c.reset}\n`);
+    process.exit(0);
+  }
+
+  console.log(`\n${c.green}✓${c.reset} Available providers: ${c.bold}${available.join(', ')}${c.reset}`);
+
+  // Ask for default provider
+  let defaultProvider = available[0];
+
+  if (available.length > 1) {
+    console.log(`\n${c.bold}Choose your default provider:${c.reset}`);
+    available.forEach((p, i) => {
+      console.log(`  ${c.cyan}${i + 1}${c.reset}) ${p}`);
+    });
+
+    const choice = await prompt(`\nEnter number [${c.dim}1${c.reset}]: `);
+    const idx = parseInt(choice) - 1;
+    if (idx >= 0 && idx < available.length) {
+      defaultProvider = available[idx];
+    }
+  }
+
+  // Save config
+  const config = {
+    version: 1,
+    defaultProvider,
+    initialized: true,
+    providers: providers
+  };
+  saveConfig(config);
+
+  console.log(`\n${c.green}✓${c.reset} Configuration saved to ${c.dim}~/.agx/config.json${c.reset}`);
+  console.log(`${c.green}✓${c.reset} Default provider: ${c.bold}${c.cyan}${defaultProvider}${c.reset}`);
+
+  // Show quick start
+  console.log(`
+${c.bold}Quick Start:${c.reset}
+
+  ${c.dim}# Use default provider (${defaultProvider})${c.reset}
+  ${c.cyan}agx --prompt "hello world"${c.reset}
+
+  ${c.dim}# Or specify a provider${c.reset}
+  ${c.cyan}agx ${defaultProvider} --prompt "explain this code"${c.reset}
+
+  ${c.dim}# Interactive mode${c.reset}
+  ${c.cyan}agx ${defaultProvider} -i --prompt "let's chat"${c.reset}
+
+  ${c.dim}# Show help${c.reset}
+  ${c.cyan}agx --help${c.reset}
+
+${c.dim}Run ${c.reset}agx init${c.dim} anytime to reconfigure.${c.reset}
+`);
+
+  process.exit(0);
+}
+
+// Show current config status
+async function showConfigStatus() {
+  const config = loadConfig();
+  const providers = detectProviders();
+
+  console.log(`\n${c.bold}agx Configuration${c.reset}\n`);
+
+  if (config) {
+    console.log(`  Config file: ${c.dim}~/.agx/config.json${c.reset}`);
+    console.log(`  Default provider: ${c.cyan}${config.defaultProvider}${c.reset}`);
+  } else {
+    console.log(`  ${c.yellow}Not configured${c.reset} - run ${c.cyan}agx init${c.reset}`);
+  }
+
+  printProviderStatus(providers);
+  console.log('');
+}
+
+// Run config menu
+async function runConfigMenu() {
+  const config = loadConfig();
+  const providers = detectProviders();
+
+  console.log(`\n${c.bold}agx Configuration${c.reset}\n`);
+
+  console.log(`${c.bold}What would you like to do?${c.reset}\n`);
+  console.log(`  ${c.cyan}1${c.reset}) Install a new provider`);
+  console.log(`  ${c.cyan}2${c.reset}) Login to a provider`);
+  console.log(`  ${c.cyan}3${c.reset}) Change default provider`);
+  console.log(`  ${c.cyan}4${c.reset}) Show status`);
+  console.log(`  ${c.cyan}5${c.reset}) Run full setup wizard`);
+  console.log(`  ${c.cyan}q${c.reset}) Quit`);
+
+  const choice = await prompt(`\nChoice: `);
+
+  switch (choice) {
+    case '1': {
+      // Install a provider
+      const missing = ['claude', 'gemini', 'ollama'].filter(p => !providers[p]);
+      if (missing.length === 0) {
+        console.log(`\n${c.green}✓${c.reset} All providers are already installed!`);
+        break;
+      }
+      console.log(`\n${c.bold}Available to install:${c.reset}\n`);
+      missing.forEach((p, i) => {
+        console.log(`  ${c.cyan}${i + 1}${c.reset}) ${p} - ${PROVIDERS[p].description}`);
+      });
+      const pChoice = await prompt(`\nChoice: `);
+      const idx = parseInt(pChoice) - 1;
+      if (idx >= 0 && idx < missing.length) {
+        await installProvider(missing[idx]);
+      }
+      break;
+    }
+    case '2': {
+      // Login to a provider
+      const installed = Object.keys(providers).filter(p => providers[p]);
+      if (installed.length === 0) {
+        console.log(`\n${c.yellow}No providers installed.${c.reset} Install one first.`);
+        break;
+      }
+      console.log(`\n${c.bold}Login to:${c.reset}\n`);
+      installed.forEach((p, i) => {
+        console.log(`  ${c.cyan}${i + 1}${c.reset}) ${p}`);
+      });
+      const pChoice = await prompt(`\nChoice: `);
+      const idx = parseInt(pChoice) - 1;
+      if (idx >= 0 && idx < installed.length) {
+        await loginProvider(installed[idx]);
+      }
+      break;
+    }
+    case '3': {
+      // Change default provider
+      const installed = Object.keys(providers).filter(p => providers[p]);
+      if (installed.length === 0) {
+        console.log(`\n${c.yellow}No providers installed.${c.reset}`);
+        break;
+      }
+      console.log(`\n${c.bold}Set default provider:${c.reset}\n`);
+      installed.forEach((p, i) => {
+        const current = config?.defaultProvider === p ? ` ${c.dim}(current)${c.reset}` : '';
+        console.log(`  ${c.cyan}${i + 1}${c.reset}) ${p}${current}`);
+      });
+      const pChoice = await prompt(`\nChoice: `);
+      const idx = parseInt(pChoice) - 1;
+      if (idx >= 0 && idx < installed.length) {
+        const newConfig = { ...config, defaultProvider: installed[idx] };
+        saveConfig(newConfig);
+        console.log(`\n${c.green}✓${c.reset} Default provider set to ${c.cyan}${installed[idx]}${c.reset}`);
+      }
+      break;
+    }
+    case '4':
+      await showConfigStatus();
+      break;
+    case '5':
+      await runOnboarding();
+      break;
+    case 'q':
+    case 'Q':
+      break;
+    default:
+      console.log(`${c.yellow}Invalid choice${c.reset}`);
+  }
+
+  console.log('');
+  process.exit(0);
+}
+
+// Check for commands or first run
+async function checkOnboarding() {
+  const args = process.argv.slice(2);
+  const cmd = args[0];
+
+  // Init/setup command
+  if (cmd === 'init' || cmd === 'setup') {
+    await runOnboarding();
+    return true;
+  }
+
+  // Config menu
+  if (cmd === 'config') {
+    await runConfigMenu();
+    return true;
+  }
+
+  // Status command
+  if (cmd === 'status') {
+    await showConfigStatus();
+    process.exit(0);
+    return true;
+  }
+
+  // Skill command
+  if (cmd === 'skill') {
+    await handleSkillCommand(args);
+    process.exit(0);
+    return true;
+  }
+
+  // Login command
+  if (cmd === 'login') {
+    const provider = args[1];
+    if (!provider) {
+      console.log(`${c.yellow}Usage:${c.reset} agx login <provider>`);
+      console.log(`${c.dim}Providers: claude, gemini, ollama${c.reset}`);
+      process.exit(1);
+    }
+    if (!['claude', 'gemini', 'ollama'].includes(provider)) {
+      console.log(`${c.red}Unknown provider:${c.reset} ${provider}`);
+      process.exit(1);
+    }
+    if (!commandExists(provider)) {
+      console.log(`${c.yellow}${provider} is not installed.${c.reset}`);
+      const answer = await prompt(`Install it now? [Y/n]: `);
+      if (answer.toLowerCase() !== 'n') {
+        await installProvider(provider);
+      } else {
+        process.exit(1);
+      }
+    }
+    await loginProvider(provider);
+    process.exit(0);
+    return true;
+  }
+
+  // Add/install command
+  if (cmd === 'add' || cmd === 'install') {
+    const provider = args[1];
+    if (!provider) {
+      console.log(`${c.yellow}Usage:${c.reset} agx add <provider>`);
+      console.log(`${c.dim}Providers: claude, gemini, ollama${c.reset}`);
+      process.exit(1);
+    }
+    if (!['claude', 'gemini', 'ollama'].includes(provider)) {
+      console.log(`${c.red}Unknown provider:${c.reset} ${provider}`);
+      process.exit(1);
+    }
+    if (commandExists(provider)) {
+      console.log(`${c.green}✓${c.reset} ${provider} is already installed!`);
+      const answer = await prompt(`Run login/setup? [Y/n]: `);
+      if (answer.toLowerCase() !== 'n') {
+        await loginProvider(provider);
+      }
+    } else {
+      const success = await installProvider(provider);
+      if (success) {
+        const answer = await prompt(`\nRun login/setup? [Y/n]: `);
+        if (answer.toLowerCase() !== 'n') {
+          await loginProvider(provider);
+        }
+      }
+    }
+    process.exit(0);
+    return true;
+  }
+
+  // First run detection
+  const config = loadConfig();
+  if (!config && !args.includes('--help') && !args.includes('-h')) {
+    console.log(`${c.cyan}First time using agx? Let's get you set up!${c.reset}\n`);
+    await runOnboarding();
+    return true;
+  }
+
+  return false;
+}
+
+// Main execution
+(async () => {
+  if (await checkOnboarding()) return;
 
 const args = process.argv.slice(2);
 let provider = args[0];
+const config = loadConfig();
 
 // Normalize provider aliases
 const PROVIDER_ALIASES = {
@@ -20,18 +757,21 @@ const PROVIDER_ALIASES = {
 
 const VALID_PROVIDERS = ['gemini', 'claude', 'ollama'];
 
-// Handle help/version before provider check
-if (args.includes('--help') || args.includes('-h') || !provider) {
+// Handle help
+if (args.includes('--help') || args.includes('-h')) {
+  const defaultNote = config?.defaultProvider
+    ? `\n  Default provider: ${config.defaultProvider} (from ~/.agx/config.json)`
+    : '';
   console.log(`agx - Unified AI Agent CLI
 
 SYNTAX:
-  agx <provider> [options] "<prompt>"
+  agx [options] --prompt "<prompt>"          Use default provider
   agx <provider> [options] --prompt "<prompt>"
 
 PROVIDERS:
   gemini, gem, g     Google Gemini
   claude, cl, c      Anthropic Claude
-  ollama, ol, o      Local Ollama (via Claude interface)
+  ollama, ol, o      Local Ollama (via Claude interface)${defaultNote}
 
 OPTIONS:
   --prompt, -p <text>    The prompt to send (recommended for clarity)
@@ -43,7 +783,17 @@ OPTIONS:
   --debug, -d            Enable debug output
   --mcp <config>         MCP config file (claude/ollama only)
 
+COMMANDS:
+  init, setup            Run setup wizard
+  config                 Configuration menu
+  add <provider>         Install a provider (claude, gemini, ollama)
+  login <provider>       Login/authenticate to a provider
+  status                 Show current configuration
+  skill                  View agx skill (LLM instructions)
+  skill install          Install skill to Claude/Gemini
+
 EXAMPLES:
+  agx --prompt "hello"                        Use default provider
   agx claude --prompt "explain this code"
   agx gemini -m gemini-2.0-flash --prompt "hello"
   agx ollama --model qwen3:8b --prompt "write a poem"
@@ -57,15 +807,40 @@ NOTE: For predictable LLM usage, always use --prompt or -p flag.`);
   process.exit(0);
 }
 
+// Detect if first arg is a provider or an option
+const isProviderArg = provider && PROVIDER_ALIASES[provider.toLowerCase()];
+
+// If no provider specified, use default from config
+if (!provider || (!isProviderArg && provider.startsWith('-'))) {
+  if (config?.defaultProvider) {
+    // Shift: treat current args as options, use default provider
+    if (provider && provider.startsWith('-')) {
+      // First arg is an option, not a provider
+      provider = config.defaultProvider;
+    } else if (!provider) {
+      provider = config.defaultProvider;
+    }
+  } else {
+    console.log(`${c.yellow}No provider specified and no default configured.${c.reset}`);
+    console.log(`\nRun ${c.cyan}agx init${c.reset} to set up, or specify a provider:\n`);
+    console.log(`  ${c.dim}agx claude --prompt "hello"${c.reset}`);
+    console.log(`  ${c.dim}agx gemini --prompt "hello"${c.reset}`);
+    console.log(`  ${c.dim}agx ollama --prompt "hello"${c.reset}\n`);
+    process.exit(1);
+  }
+}
+
 // Resolve provider
-provider = PROVIDER_ALIASES[provider.toLowerCase()];
-if (!provider) {
-  console.error(`Error: Unknown provider "${args[0]}"`);
+const resolvedProvider = PROVIDER_ALIASES[provider.toLowerCase()];
+if (!resolvedProvider) {
+  console.error(`${c.red}Error:${c.reset} Unknown provider "${provider}"`);
   console.error(`Valid providers: ${VALID_PROVIDERS.join(', ')}`);
   process.exit(1);
 }
+provider = resolvedProvider;
 
-const remainingArgs = args.slice(1);
+// Determine remaining args - if first arg wasn't a provider, include it
+const remainingArgs = isProviderArg ? args.slice(1) : args;
 const translatedArgs = [];
 const rawArgs = [];
 let env = { ...process.env };
@@ -223,9 +998,17 @@ child.on('exit', (code) => {
 
 child.on('error', (err) => {
   if (err.code === 'ENOENT') {
-    console.error(`Error: "${command}" command not found.`);
+    console.error(`${c.red}Error:${c.reset} "${command}" command not found.`);
+    console.error(`\n${c.dim}Install it first:${c.reset}`);
+    if (command === 'claude') {
+      console.error(`  npm install -g @anthropic-ai/claude-code`);
+    } else if (command === 'gemini') {
+      console.error(`  npm install -g @anthropic-ai/gemini-cli`);
+    }
   } else {
-    console.error(`Failed to start ${command}:`, err);
+    console.error(`${c.red}Failed to start ${command}:${c.reset}`, err.message);
   }
   process.exit(1);
 });
+
+})();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mndrk/agx",
-  "version": "1.0.2",
+  "version": "1.3.0",
   "description": "Unified AI Agent Wrapper for Gemini, Claude, and Ollama",
   "main": "index.js",
   "bin": {