AI Command (ai-cmd) — Workflow Guide

Documentation Navigation

This page is scenario-first (operational workflows, real run order, and troubleshooting). For the full autogenerated command/flag catalog, use the CLI Reference.

File Information

Property	Value
Binary Name	ai-cmd
Version	9.0.1
File Size	55.8MB
Author	Warith Al Maawali
License	Proprietary
Category	AI & Intelligence
Description	AI-powered command-line interface for natural language command execution
JSON Data	View Raw JSON

SHA256 Checksum

d9e36d46428a79ac7420abecbf8c0a283e1db01a59f28161b78c5e130d643115

What ai-cmd Does

ai-cmd is the user-facing entry point for all AI operations in Kodachi OS. It translates natural language queries into system commands using a 6-tier AI engine (TF-IDF → ONNX → Mistral.rs → GenAI/Ollama → Legacy LLM → Claude CLI). The service collects user feedback to improve accuracy over time and supports voice input, interactive sessions, automated suggestions, real-time streaming, and native tool calling.

Key Capabilities

Feature	Description
Natural Language Queries	Type commands in plain English instead of remembering exact syntax
Multi-Tier AI Engine	Automatic fallback from fast TF-IDF to deep semantic models and cloud LLMs
Voice Input	Hands-free operation with whisper-cpp/vosk speech recognition (requires voice-engine dependencies)
Feedback System	Correct misclassifications to improve future accuracy
Preview & Dry-Run	See what would execute before running dangerous commands
Interactive Mode	REPL for continuous command sessions
AI Suggestions	Proactive command recommendations based on system state
Mistral.rs Local LLM	Local GGUF model inference with streaming, tool calling, and 29+ model architectures
Ollama / GenAI	Multi-provider LLM via Ollama (local, privacy-safe) or cloud providers via Tor
Real-Time Streaming	Stream response tokens as they generate with `--stream` flag
Native Tool Calling	AI automatically calls system tools (tor_status, dns_status, etc.) during reasoning
AI Tier Discovery	`ai-cmd tiers` shows all available engines; `ai-cmd tools` shows callable tools

ai-cmd + ai-gateway Integration (Current Behavior)

ai-cmd is the human-facing natural language interface. ai-gateway is the machine-facing policy and execution layer used by agents.

Safe planning path (recommended first)

# ai-cmd intent resolution preview
ai-cmd query "check tor status" --dry-run --json

# ai-gateway policy/execution preview
ai-gateway run tor-switch --command tor-status --dry-run --json

Live execution path

# Requires valid online-auth state
ai-cmd query "what is my ip address" --json
ai-cmd feedback "check tor" --correct-command "tor-switch tor-status" --json

Dangerous command policy

# Dry-run always works for planning
ai-gateway run health-control --command wipe-logs --dry-run --json

# Live execution requires explicit confirmation and policy approval
ai-gateway run health-control --command wipe-logs --confirm "I understand" --json

Pentest mode examples (when required by policy)

# Optional env prefix (single command)
KODACHI_PENTEST_MODE=true ai-gateway run health-control --command wipe-logs --confirm "I understand" --json

# Normal mode (no env)
ai-gateway run health-control --command wipe-logs --dry-run --json

Bypassing gateway validation (`--no-gateway`)

Use --no-gateway to skip gateway validation and execute commands directly. This is useful when gateway validation adds unnecessary overhead or when a command's execution time exceeds the gateway timeout (e.g., dns-leak test takes ~45s).

# Skip gateway, execute command directly
ai-cmd query "check tor status" --no-gateway --dry-run

# Useful for long-running commands that may exceed gateway timeout
ai-cmd query "test dns leak" --no-gateway

# Compare: with gateway (shows "Gateway validation passed")
ai-cmd query "check tor status" --dry-run

# Compare: without gateway (shows direct "[DRY RUN] Would execute:")
ai-cmd query "check tor status" --no-gateway --dry-run

Scenario 1: First-Time Setup — From Zero to Working AI

Use ai-cmd immediately with built-in TF-IDF, then upgrade to semantic matching for better accuracy.

Step 1: Works Immediately (Tier 1: TF-IDF)

# No setup needed — works out of the box
ai-cmd query "check network connectivity"
ai-cmd query "test for dns leaks"
ai-cmd query "show tor status"

# Verify which engine is being used
ai-cmd query "check network" --json | jq '.engine'

Step 2: Upgrade to ONNX Semantic Matching (Tier 2)

# Download the ONNX model (all-MiniLM-L6-v2)
sudo ai-trainer download-model

# Expected output:
# ✓ Downloading ONNX model: all-MiniLM-L6-v2.onnx
# ✓ Downloading tokenizer files
# ✓ Model saved to: /opt/kodachi/ai-models/

# Train the model with your command database
sudo ai-trainer train --data ./data/training-data.json

# Expected output:
# ✓ Loaded 487 command examples
# ✓ Training ONNX model...
# ✓ Model accuracy: 94.2%

Step 3: Verify ONNX Engine Works

# Now queries use semantic understanding
ai-cmd query "is my connection secure?" --engine onnx
ai-cmd query "rotate my tor identity" --engine onnx
ai-cmd query "am I leaking DNS queries?" --engine onnx

# Check engine status
ai-trainer status

Why this matters: TF-IDF works well for exact or similar phrasing ("check network"). ONNX handles paraphrasing ("is my connection working?" → maps to health-control net-check) by understanding semantic meaning instead of just keywords.

Step 4: Enable Mistral.rs Local LLM (Tier 3)

# Download a small GGUF model (recommended: 1-3B params for CPU)
# Place the .gguf file in the models/ directory
ai-cmd query "analyze my security posture" --engine mistral

# Stream response in real-time
ai-cmd query "explain tor routing" --engine mistral --stream

# Adjust sampling for more creative responses
ai-cmd query "suggest security improvements" --engine mistral --temperature 0.8

# Check what model is loaded
ai-cmd model-info --json

Step 5: Enable Ollama via GenAI (Tier 4)

# Install Ollama and pull a model
ollama pull gemma:2b
ollama serve

# Query using Ollama local model
ai-cmd query "run full security audit" --engine genai

# Use a specific Ollama model
ai-cmd query "check all services" --engine genai --model llama3:8b

# List available providers
ai-cmd providers --json

Step 6: Cloud Provider via Tor (Privacy-Safe Remote AI)

# Use cloud AI routed through Tor for maximum privacy
ai-cmd query "detailed threat analysis" --engine genai --model gpt-4o --tor-proxy

# Requires: OPENAI_API_KEY env var + Tor running

Tool Calling and Tier Discovery

# AI automatically calls tools during reasoning
ai-cmd query "what's my tor status and dns config?"
# → AI calls tor_status, dns_status tools, synthesizes answer

# See available AI tools
ai-cmd tools --json

# Check which tiers are available
ai-cmd tiers --json

Scenario 2: Improving Accuracy Through the Feedback Loop

When ai-cmd misclassifies a query, use the feedback → learn → analyze cycle to fix it permanently.

Step 1: Query Gets Wrong Result

# Ask a question and get wrong command
ai-cmd query "check tor status"

# Output: ✓ tor-switch restart (confidence: 0.85)
# Wrong! Should be "tor-switch tor-status"

Step 2: Preview to See All Alternatives

# See what ai-cmd considered
ai-cmd preview "check tor status" --alternatives 5

# Expected output:
# 1. tor-switch restart (0.85)
# 2. tor-switch tor-status (0.82) ← Correct one!
# 3. health-control net-check (0.71)
# 4. dns-switch status (0.65)
# 5. routing-switch status (0.61)

Step 3: Submit Correction with Feedback

# Option A: Correct the intent (category)
ai-cmd feedback "check tor status" --correct-intent tor_status

# Option B: Correct the exact command
ai-cmd feedback "check tor status" --correct-command "tor-switch tor-status"

# Option C: Add a comment explaining why
ai-cmd feedback "check tor status" --correct-command "tor-switch tor-status" --comment "User meant status check, not restart"

# Fix similar queries to strengthen the pattern
ai-cmd feedback "is tor working" --correct-command "tor-switch tor-status"
ai-cmd feedback "tor connection check" --correct-intent tor_status
ai-cmd feedback "show tor state" --correct-command "tor-switch tor-status"

Step 5: Run Learning Cycle

# Process all feedback and retrain models
sudo ai-learner learn

# Expected output:
# ✓ Processing 4 feedback entries
# ✓ Updating intent mappings
# ✓ Retraining ONNX embeddings
# ✓ Learning cycle complete

Step 6: Verify the Fix

# Test the original query again
ai-cmd query "check tor status" --dry-run

# Expected output:
# ✓ tor-switch tor-status (confidence: 0.93)
# This is now the top match!

Step 7: Analyze Accuracy Improvement

# Check overall system accuracy
sudo ai-learner analyze --period last-7-days

# Expected output:
# ┌─────────────────────────────────────┐
# │ AI Accuracy Analysis (7 days)      │
# ├─────────────────────────────────────┤
# │ Total queries: 234                  │
# │ Correct classifications: 218        │
# │ Accuracy: 93.2% (↑ 4.1%)           │
# │ Top misclassifications:             │
# │   - "panic" → health-control (3x)   │
# │   - "secure" → dns-switch (2x)      │
# └─────────────────────────────────────┘

Why this matters: Each correction teaches the model. After enough feedback and a learning cycle, similar queries will be classified correctly automatically. The system learns from your corrections and improves over time.

Scenario 3: Safe Execution of Dangerous Commands

Use preview, thresholds, and dry-run to prevent accidental execution of destructive commands.

Preview Before Executing

# Always preview dangerous commands first
ai-cmd preview "enable panic mode" --alternatives 3

# Expected output:
# 1. health-control panic --mode hard (0.91)
# 2. health-control net-block (0.84)
# 3. health-control mac-randomize (0.76)

Use High Confidence Threshold

# Require 95% confidence for destructive operations
ai-cmd query "enable panic mode" --threshold 0.95

# If confidence is below threshold:
# ⚠ health-control panic (confidence: 0.91) — below threshold 0.95
# Command not executed. Use --threshold 0.9 or lower to execute.

# If confidence meets threshold:
# ✓ health-control panic --mode hard (confidence: 0.96) — executing

Dry-Run for Safety Validation

# See what WOULD execute without actually doing it
ai-cmd query "block all internet traffic" --dry-run

# Expected output:
# [DRY RUN] Would execute:
# Command: health-control net-block
# Confidence: 0.94
# Effect: Blocks all network interfaces
# Reversible: Yes (health-control net-restore)

# More examples
ai-cmd query "wipe temporary data" --dry-run
ai-cmd query "randomize mac address" --dry-run
ai-cmd query "enable medium panic mode" --dry-run

Safe Execution Pattern

# 1. Preview to see alternatives
ai-cmd preview "block internet" --alternatives 5

# 2. Dry-run to see exact effect
ai-cmd query "block internet" --dry-run

# 3. Execute with high threshold only after review
ai-cmd query "block all internet traffic" --threshold 0.95

Why this matters: Panic mode, internet blocking, and data wiping are irreversible or disruptive. Preview and threshold ensure you never trigger them accidentally from a vague query.

Scenario 4: Hands-Free Voice Control

Set up voice input for situations where you can't use the keyboard (accessibility, emergency, multi-tasking).

Step 1: Check Dependencies

# Verify voice support is available
ai-cmd voice --check-deps

# Expected output:
# Checking voice input dependencies...
# ✓ whisper-cpp: installed
# ✗ vosk: not installed
# ✓ microphone detected: device0 (Realtek Audio)
#
# To install missing dependencies:
# sudo apt install vosk-api vosk-model-small-en-us-0.15

Step 2: Install Missing Dependencies

# Install whisper-cpp (recommended)
sudo apt install whisper-cpp

# Or install vosk for faster offline recognition
sudo apt install vosk-api vosk-model-small-en-us-0.15

# List available microphones
ai-cmd voice --list-devices

# Expected output:
# Available audio input devices:
# 0: Realtek Audio (default)
# 1: USB Microphone
# 2: Built-in Microphone

Step 3: Single Voice Command

# Capture one voice command
ai-cmd voice

# Expected interaction:
# 🎤 Listening... (say your command)
# [You speak: "check network connectivity"]
# Recognized: "check network connectivity"
# ✓ health-control net-check (confidence: 0.89)
# [Command executes]

Step 4: Continuous Listening Mode

# Keep listening for multiple commands
ai-cmd voice --continuous

# Expected interaction:
# 🎤 Continuous listening mode (say "exit" to stop)
# [You speak: "check tor status"]
# ✓ tor-switch tor-status
# 🎤 Next command...
# [You speak: "rotate tor circuit"]
# ✓ tor-switch new-circuit
# 🎤 Next command...
# [You speak: "exit"]
# Voice input terminated.

Step 5: Configure Voice Provider

# Use specific speech recognition provider
ai-cmd voice --provider whisper-cpp --continuous

# Use vosk for faster recognition (less accurate)
ai-cmd voice --provider vosk --continuous

# Adjust timeout for slower speech
ai-cmd voice --timeout 10 --continuous

# Expected output:
# 🎤 Using provider: whisper-cpp
# 🎤 Timeout: 10 seconds
# 🎤 Listening...

Combined with AI Monitoring

# Use voice to act on ai-monitor suggestions
ai-cmd voice
# Speak: "show proactive suggestions"

# ai-monitor might suggest:
# → "DNS leak detected — run 'dns-leak fix'"
# → "Tor circuit is stale — run 'tor-switch new-circuit'"

# Then use voice to execute:
ai-cmd voice
# Speak: "fix dns leak"

Why this matters: Voice control is critical for: - Accessibility: Users with mobility limitations - Emergency: Fast execution when under time pressure - Multi-tasking: Security operations while monitoring other screens - Stealth: Operate system quietly without keyboard noise

Scenario 5: Scripting Integration with JSON Output

Use ai-cmd in automated scripts by leveraging JSON output for reliable parsing.

Basic JSON Output

# Get structured JSON instead of human-readable text
ai-cmd query "check tor status" --json

# Expected output:
{
  "success": true,
  "command": "tor-switch tor-status",
  "confidence": 0.94,
  "intent": "tor_status",
  "engine": "onnx",
  "execution_time_ms": 127,
  "output": "Tor is running\nCircuits: 3 active\nUptime: 2h 34m"
}

Parsing with jq

# Extract specific fields
RESULT=$(ai-cmd query "check dns leaks" --json)
STATUS=$(echo "$RESULT" | jq -r '.success')
CONFIDENCE=$(echo "$RESULT" | jq -r '.confidence')

if [ "$STATUS" = "true" ] && (( $(echo "$CONFIDENCE > 0.85" | bc -l) )); then
  echo "DNS check completed with high confidence"
else
  echo "WARNING: DNS check uncertain or failed!"
  # Trigger automated response
  ai-cmd query "secure dns configuration" --threshold 0.8 --json
fi

Automated Security Monitoring Script

#!/bin/bash
# security-monitor.sh - Automated AI-driven security checks

CHECKS=(
  "check network connectivity"
  "test dns leaks"
  "verify tor status"
  "check system integrity"
  "show security score"
)

RESULTS=()

for check in "${CHECKS[@]}"; do
  echo "Running: $check"
  RESULT=$(ai-cmd query "$check" --json)

  # Parse result
  SUCCESS=$(echo "$RESULT" | jq -r '.success')
  CONFIDENCE=$(echo "$RESULT" | jq -r '.confidence')

  # Store for analysis
  RESULTS+=("$RESULT")

  # Alert on failures
  if [ "$SUCCESS" != "true" ]; then
    echo "ALERT: $check failed!"
    # Send notification or trigger remediation
    ai-cmd query "enable network protection" --threshold 0.9 --json
  fi
done

# Generate report
echo "${RESULTS[@]}" | jq -s '.' > security-report.json
echo "Security scan complete. Report saved to security-report.json"

Batch Processing from File

# Create file with queries (one per line)
cat > security-checks.txt <<EOF
check network connectivity
test for dns leaks
verify tor circuit is working
check vpn connection status
show current security score
EOF

# Process all queries and collect results
cat security-checks.txt | while read query; do
  ai-cmd query "$query" --json >> results.json
  sleep 1  # Rate limiting
done

# Analyze results
jq -s '[.[] | select(.success == false)]' results.json

Integration with Cron Jobs

# Add to crontab for automated checks
crontab -e

# Run security check every hour
0 * * * * /usr/bin/ai-cmd query "check system health" --json >> /var/log/kodachi/hourly-health.log

# Run comprehensive scan daily at 3 AM
0 3 * * * /opt/kodachi/scripts/security-monitor.sh

Why this matters: JSON output enables: - Reliable parsing: No risk of output format changes breaking scripts - Automation: Integrate AI queries into monitoring systems - Alerting: Trigger actions based on query results - Reporting: Generate structured security reports

Scenario 6: Downloading and Setting Up All AI Engine Tiers

ai-cmd uses a 4-tier engine system. Each tier offers different accuracy/speed tradeoffs. Here's how to set up each one.

Tier 1: TF-IDF (No Setup Required)

# Works immediately out of the box — no downloads needed
ai-cmd query "check network" --engine tfidf
ai-cmd query "test dns leaks" --engine tfidf
ai-cmd query "tor status" --engine tfidf

# Verify it's working
ai-cmd query "show tor circuits" --engine tfidf --json | jq '.engine'

# Expected output:
# "tfidf"

Best for: Exact or similar keyword matches. Fastest (~1ms), zero setup, no dependencies.

How it works: TF-IDF (Term Frequency-Inverse Document Frequency) scores queries based on keyword overlap with known commands. Works well for queries that contain command names or direct synonyms.

Tier 2: ONNX Semantic Model (Download + Train)

The ONNX model (all-MiniLM-L6-v2) provides semantic understanding, allowing ai-cmd to match queries even when phrased differently.

Step 1: Download ONNX Model

# Download the ONNX model and tokenizer
sudo ai-trainer download-model

# Expected output:
# Downloading ONNX model: all-MiniLM-L6-v2.onnx
# ✓ Downloaded: /opt/kodachi/ai-models/all-MiniLM-L6-v2.onnx (84.3 MB)
# Downloading tokenizer files...
# ✓ Downloaded: vocab.txt (226 KB)
# ✓ Downloaded: tokenizer.json (466 KB)
# Model setup complete!

Step 2: Download to Custom Directory (Optional)

# Store models in a different location
sudo ai-trainer download-model --output-dir ./custom-models

# Expected output:
# Using custom output directory: ./custom-models
# ✓ Model saved to: ./custom-models/all-MiniLM-L6-v2.onnx

Step 3: Force Re-Download (If Corrupted)

# Re-download if files are corrupted or incomplete
sudo ai-trainer download-model --force

# Expected output:
# ⚠ Existing model found. --force flag set, re-downloading...
# ✓ Model re-downloaded successfully

Step 4: Train with Command Data

# Train the model with your command database
sudo ai-trainer train --data ./data/training-data.json

# Expected output:
# Loading training data from: ./data/training-data.json
# ✓ Loaded 487 command examples
# ✓ Loaded 42 intents
# Training ONNX embeddings...
# ✓ Processed 487/487 examples
# ✓ Model accuracy: 94.2%
# ✓ Training complete in 23.4s

Step 5: Verify ONNX Engine Works

# Test semantic understanding
ai-cmd query "is my connection secure?" --engine onnx
ai-cmd query "rotate my tor identity" --engine onnx
ai-cmd query "am I leaking DNS queries?" --engine onnx

# Verify engine in use
ai-cmd query "check network" --engine onnx --json | jq '.engine'

# Expected output:
# "onnx"

Step 6: Check ONNX Status

# Verify ONNX model is loaded
ai-trainer status

# Expected output:
# AI Engine Status:
# ┌──────────────────────────────────────┐
# │ TF-IDF:        ✓ Active              │
# │ ONNX Model:    ✓ Active              │
# │   - Model:     all-MiniLM-L6-v2      │
# │   - Size:      84.3 MB               │
# │   - Accuracy:  94.2%                 │
# │ LLM (GGUF):    ✗ Not configured      │
# │ Claude API:    ✗ Not configured      │
# └──────────────────────────────────────┘

Best for: Understanding paraphrased queries and semantic similarity. Runs locally, ~10ms per query, no internet required.

How it works: ONNX model converts queries to 384-dimensional embeddings and compares them to pre-computed command embeddings using cosine similarity. This allows matching based on meaning rather than keywords.

Tier 3: Local LLM with GGUF Model (Download GGUF File)

Local LLMs provide advanced reasoning and multi-step analysis while remaining offline.

Step 1: Create Models Directory

# Create directory for GGUF models
mkdir -p ./models

Step 2: Download Compatible GGUF Model

Compatible models include: - Qwen2.5-3B-Instruct (3B params, ~1.8 GB) — Default, best balance - Qwen2.5-1.5B-Instruct (1.5B params, ~0.9 GB) — Small, fast inference - Phi-3.5-mini-instruct (3.8B params, ~2.3 GB) — Large, advanced reasoning - Gemma-2 (2B params, 1.6 GB) — Lightweight

# Option A: Download Qwen2.5-3B-Instruct (default, recommended)
wget -O ./models/Qwen2.5-3B-Instruct-Q4_K_M.gguf \
  "https://huggingface.co/Qwen/Qwen2.5-3B-Instruct-GGUF/resolve/main/qwen2.5-3b-instruct-q4_k_m.gguf"

# Option B: Download Qwen2.5-1.5B-Instruct (small, fast)
wget -O ./models/Qwen2.5-1.5B-Instruct-Q4_K_M.gguf \
  "https://huggingface.co/Qwen/Qwen2.5-1.5B-Instruct-GGUF/resolve/main/qwen2.5-1.5b-instruct-q4_k_m.gguf"

# Option C: Download Phi-3.5-mini-instruct (large, advanced reasoning)
wget -O ./models/Phi-3.5-mini-instruct-Q4_K_M.gguf \
  "https://huggingface.co/microsoft/Phi-3.5-mini-instruct-gguf/resolve/main/Phi-3.5-mini-instruct-Q4_K_M.gguf"

# Verify download
ls -lh ./models/

Step 3: Test with Downloaded Model

# Test with Qwen2.5-3B-Instruct (default)
ai-cmd query "what security measures should I enable?" --engine llm --model-path ./models/Qwen2.5-3B-Instruct-Q4_K_M.gguf

# Expected output:
# [LLM Reasoning]
# Based on your query, I recommend enabling:
# 1. DNS leak protection (dns-leak fix)
# 2. Tor routing (tor-switch enable)
# 3. Network monitoring (health-control net-check)
#
# ✓ Suggested command: dns-leak fix
# Confidence: 0.88

Step 4: Test with Different Models

# Use small model for faster inference
ai-cmd query "analyze network routing" --engine llm --model-path ./models/Qwen2.5-1.5B-Instruct-Q4_K_M.gguf

# Use large model for complex reasoning
ai-cmd query "explain my current threat model" --engine llm --model-path ./models/Phi-3.5-mini-instruct-Q4_K_M.gguf

# Interactive session with LLM
ai-cmd interactive --engine llm --model-path ./models/Qwen2.5-3B-Instruct-Q4_K_M.gguf

Best for: Complex reasoning, multi-step analysis, and natural conversation. Runs locally, ~500ms per query, no internet required.

How it works: GGUF models are quantized large language models that run on CPU/GPU. They understand context, reason about multi-step problems, and explain their recommendations.

Tier 4: Claude API (Cloud — Opt-In Only)

Claude provides state-of-the-art reasoning and expert-level analysis but requires internet connectivity.

Step 1: Install Claude CLI

# Visit https://claude.ai/code for installation instructions

# For Debian/Ubuntu (example):
curl -fsSL https://claude.ai/install.sh | bash

# Verify installation
claude --version

# Expected output:
# claude-cli 0.6.2

Step 2: Authenticate with Claude

# Login to Claude (requires browser)
claude login

# Expected interaction:
# Opening browser for authentication...
# ✓ Successfully authenticated
# Session saved to: ~/.claude/session.json

Step 3: Use Claude Engine

# Use Claude for advanced reasoning
ai-cmd query "analyze my current threat model" --engine claude

# Expected output:
# [Claude Analysis]
# Based on your system configuration, your current threat model shows:
#
# Strengths:
# - Tor routing provides network anonymity
# - DNS leak protection is active
# - System integrity monitoring enabled
#
# Vulnerabilities:
# - VPN not configured (single-layer anonymity)
# - Browser fingerprinting not addressed
# - No encrypted DNS (DoH/DoT)
#
# ✓ Recommended command: dns-switch enable-doh
# Confidence: 0.91

# Interactive mode with Claude
ai-cmd interactive --engine claude --threshold 0.7

Step 4: Verify Claude Integration

# Check Claude API status
ai-trainer status

# Expected output:
# AI Engine Status:
# ┌──────────────────────────────────────┐
# │ TF-IDF:        ✓ Active              │
# │ ONNX Model:    ✓ Active              │
# │ LLM (GGUF):    ✓ Active (Qwen2.5-3B) │
# │ Claude API:    ✓ Active              │
# │   - Session:   Valid until 2026-03-09│
# └──────────────────────────────────────┘

Best for: Expert-level analysis, complex decision-making, and nuanced threat modeling. Requires internet, ~1000ms per query.

How it works: Queries are sent to Claude's API with context about Kodachi commands. Claude reasons about the query and recommends appropriate commands with detailed explanations.

Engine Comparison Table

Tier	Engine	Setup	Speed	Accuracy	Network	Use Case
1	`tfidf`	None	~1ms	Good	No	Exact keyword matches
2	`onnx`	`ai-trainer download-model` + train	~10ms	Very Good	No	Semantic understanding
3	`llm`	Download GGUF file	~500ms	Excellent	No	Complex reasoning
4	`claude`	Install CLI + login	~1000ms	State-of-art	Yes	Expert analysis

Auto Engine Selection

# Let ai-cmd automatically pick the best available engine
ai-cmd query "check tor status" --engine auto

# Auto mode priority order:
# 1. Try Claude (if configured)
# 2. Try LLM (if GGUF model exists)
# 3. Try ONNX (if model downloaded)
# 4. Fallback to TF-IDF (always available)

# Verify which engine was used
ai-cmd query "check tor status" --engine auto --json | jq '.engine'

# Expected output:
# "onnx"  (if ONNX is the highest tier available)

Recommendation: Use --engine auto for best results. The system will automatically use the most capable engine available while falling back gracefully if higher tiers aren't configured.

Scenario 7: Interactive Mode with Different Engines

Instead of running individual queries, use interactive REPL mode for continuous command sessions. This keeps the AI engine loaded in memory for faster responses.

Basic Interactive Session (Auto Engine)

# Start interactive mode with automatic engine selection
ai-cmd interactive

# Expected interaction:
# ai-cmd v9.0.1 - Interactive Mode
# Engine: auto (currently: onnx)
# Type 'help' for commands, 'exit' to quit
#
# ai-cmd> check network connectivity
# ✓ health-control net-check (confidence: 0.92)
# [Output: Network is active, no leaks detected]
#
# ai-cmd> rotate tor circuit
# ✓ tor-switch new-circuit (confidence: 0.88)
# [Output: New Tor circuit established]
#
# ai-cmd> exit
# Goodbye!

Interactive with ONNX (Semantic Understanding)

# Use ONNX engine for consistent semantic matching
ai-cmd interactive --engine onnx

# Now you can use natural language freely:
# ai-cmd> is my internet working?
# ✓ health-control net-check (confidence: 0.89)
#
# ai-cmd> am I leaking DNS queries?
# ✓ dns-leak test (confidence: 0.94)
#
# ai-cmd> give me a new tor identity
# ✓ tor-switch new-circuit (confidence: 0.91)

Why ONNX interactive: ONNX is fast (~10ms) and accurate for semantic matching. Perfect for interactive sessions where you don't want to wait for LLM inference but still want natural language understanding.

Interactive with Local LLM (Deep Reasoning)

# Use local GGUF model for complex, multi-step queries
ai-cmd interactive --engine llm --model-path ./models/Qwen2.5-3B-Instruct-Q4_K_M.gguf

# Expected interaction:
# ai-cmd v9.0.1 - Interactive Mode
# Engine: llm (model: Qwen2.5-3B-Instruct-Q4_K_M.gguf)
# Loading model... ✓
#
# ai-cmd> what should I do to improve my security?
# [LLM Reasoning]
# To improve security, I recommend:
# 1. Enable Tor routing for anonymity
# 2. Configure DNS leak protection
# 3. Randomize MAC address
# 4. Enable system integrity monitoring
#
# ✓ Suggested: tor-switch enable (confidence: 0.87)
# Execute? [y/N]: y
#
# ai-cmd> explain why my DNS might be leaking
# [LLM Explanation]
# DNS leaks occur when queries bypass your VPN/Tor tunnel...
# Common causes: systemd-resolved, NetworkManager DNS, browser DNS-over-HTTPS
#
# ✓ Suggested: dns-leak test (confidence: 0.93)

Why LLM interactive: Local LLM provides detailed explanations and multi-step reasoning. Use when you need help understanding security concepts or want recommendations beyond simple command matching.

Interactive with Claude (Expert Mode)

# Use Claude for state-of-the-art analysis
ai-cmd interactive --engine claude --threshold 0.7

# Expected interaction:
# ai-cmd v9.0.1 - Interactive Mode
# Engine: claude (requires network)
#
# ai-cmd> analyze my threat model given I'm on public wifi
# [Claude Analysis]
# Public WiFi presents several threats:
# 1. Passive monitoring: ISP/network admin can see unencrypted traffic
# 2. Active MITM: Attacker could intercept connections
# 3. DNS hijacking: Malicious DNS responses
#
# Recommended protections:
# - Enable VPN + Tor (dual-layer anonymity)
# - Force encrypted DNS (DoH/DoT)
# - Disable IPv6 to prevent leaks
# - Randomize MAC address
#
# ✓ Suggested: routing-switch enable-vpn (confidence: 0.94)
# ✓ Suggested: dns-switch enable-doh (confidence: 0.91)
#
# ai-cmd> what's the optimal tor+vpn configuration?
# [Claude Recommendation]
# The optimal configuration depends on your threat model:
#
# High anonymity (recommended for journalists/activists):
#   VPN → Tor → Internet
#   - Hides Tor usage from ISP
#   - VPN can't see destination
#
# Moderate anonymity (general privacy):
#   Tor → VPN → Internet
#   - VPN can't correlate entry/exit
#   - Bypasses Tor blocks
#
# ✓ Suggested: routing-switch set-chain vpn-tor (confidence: 0.88)

Why Claude interactive: Claude provides expert-level analysis, detailed explanations, and nuanced recommendations. Use when you need guidance on complex security decisions or threat modeling.

Interactive with High Confidence Threshold

# Only execute commands when confidence is very high
ai-cmd interactive --threshold 0.9

# Expected interaction:
# ai-cmd v9.0.1 - Interactive Mode
# Engine: auto (threshold: 0.9)
#
# ai-cmd> block internet
# ⚠ health-control net-block (confidence: 0.82) — below threshold 0.9
# Command not executed. Did you mean:
# 1. health-control net-block (0.82)
# 2. routing-switch disable (0.79)
# Execute anyway? [y/N]: n
#
# ai-cmd> block all internet traffic
# ✓ health-control net-block (confidence: 0.95) — executing
# [Output: All network interfaces blocked]

Why high threshold: Prevents accidental execution of dangerous commands from vague queries. Forces you to be more specific, reducing the risk of unintended actions.

When to Use Interactive Mode

Scenario	Best Engine	Threshold
Quick security checks	`--engine onnx`	`--threshold 0.7`
Learning about security	`--engine llm`	`--threshold 0.8`
Troubleshooting issues	`--engine llm` or `claude`	`--threshold 0.7`
Emergency operations	`--engine onnx`	`--threshold 0.95`
Scripting/automation	Single queries with `--json`	N/A

Interactive mode benefits: - Faster: Engine stays loaded in memory - Contextual: Multiple related queries in one session - Exploratory: Try different phrasings and see results immediately - Learning: Get immediate feedback on query understanding

Scenario 8: AI Suggestions for Command Discovery

ai-cmd can proactively suggest commands based on system state, recent activity, and common workflows.

Basic Suggestions

# Get AI-generated command suggestions
ai-cmd suggest

# Expected output:
# AI Command Suggestions:
# ┌──────────────────────────────────────────────────────┐
# │ 1. health-control net-check                          │
# │    Reason: Regular network security check            │
# │    Confidence: 0.87                                  │
# │                                                      │
# │ 2. tor-switch new-circuit                           │
# │    Reason: Tor circuit age: 4h 23m (recommended: 1h)│
# │    Confidence: 0.92                                  │
# │                                                      │
# │ 3. dns-leak test                                     │
# │    Reason: Last DNS leak test: 8 hours ago          │
# │    Confidence: 0.85                                  │
# └──────────────────────────────────────────────────────┘

Proactive Suggestions with System Monitoring

# Get proactive suggestions based on system state
ai-cmd suggest --proactive

# Expected output:
# Proactive AI Suggestions (analyzing system state...):
# ┌──────────────────────────────────────────────────────┐
# │ ⚠ URGENT                                             │
# │ 1. dns-leak fix                                      │
# │    Reason: DNS leak detected on interface wlan0      │
# │    Impact: Privacy compromise                        │
# │    Confidence: 0.96                                  │
# │                                                      │
# │ 🔔 RECOMMENDED                                       │
# │ 2. health-control mac-randomize                      │
# │    Reason: Connected to public WiFi                  │
# │    Impact: Prevent tracking                          │
# │    Confidence: 0.89                                  │
# │                                                      │
# │ 3. tor-switch new-circuit                           │
# │    Reason: Current circuit through high-risk exit    │
# │    Impact: Improved anonymity                        │
# │    Confidence: 0.84                                  │
# │                                                      │
# │ ℹ MAINTENANCE                                        │
# │ 4. integrity-check check-all                           │
# │    Reason: Last integrity check: 3 days ago          │
# │    Impact: System validation                         │
# │    Confidence: 0.78                                  │
# └──────────────────────────────────────────────────────┘

Limit Number of Suggestions

# Get top 5 suggestions only
ai-cmd suggest --limit 5

# Get top 3 most urgent suggestions
ai-cmd suggest --proactive --limit 3

# Expected output:
# Top 3 AI Suggestions:
# 1. dns-leak fix (0.96) — DNS leak detected
# 2. health-control mac-randomize (0.89) — Public WiFi detected
# 3. tor-switch new-circuit (0.84) — Stale Tor circuit

Suggestions with JSON Output

# Get suggestions in JSON format for scripting
ai-cmd suggest --proactive --limit 5 --json

# Expected output:
{
  "suggestions": [
    {
      "command": "dns-leak fix",
      "reason": "DNS leak detected on interface wlan0",
      "priority": "urgent",
      "confidence": 0.96,
      "impact": "privacy_compromise"
    },
    {
      "command": "health-control mac-randomize",
      "reason": "Connected to public WiFi",
      "priority": "recommended",
      "confidence": 0.89,
      "impact": "prevent_tracking"
    }
  ],
  "generated_at": "2026-02-09T14:32:18Z"
}

Use Suggestions in Scripts

#!/bin/bash
# auto-suggest-execute.sh - Execute high-confidence suggestions

# Get proactive suggestions
SUGGESTIONS=$(ai-cmd suggest --proactive --json)

# Parse and execute urgent suggestions (confidence > 0.9)
echo "$SUGGESTIONS" | jq -r '.suggestions[] | select(.confidence > 0.9 and .priority == "urgent") | .command' | while read cmd; do
  echo "Auto-executing: $cmd"
  eval "$cmd"
done

Combine Suggestions with ai-monitor

# ai-monitor detects issues, ai-cmd suggests fixes
# Terminal 1: Run monitoring
ai-monitor status --verbose

# Terminal 2: Check suggestions based on monitoring
ai-cmd suggest --proactive

# Expected workflow:
# ai-monitor detects: "DNS leak on wlan0"
# ai-cmd suggests: "dns-leak fix" (confidence: 0.96)
# User executes: ai-cmd query "fix dns leak"

Why suggestions matter: - Proactive security: Catch issues before they become problems - Command discovery: Learn new commands and workflows - Automation: Build scripts that respond to system state - Maintenance: Remember periodic checks and updates