AI SUITE GUIDE
ai-cmd Guide
The human-facing natural language command interface for Kodachi OS. It translates plain English into system commands through a 9-tier AI engine, with feedback learning, voice input, interactive sessions, real-time streaming, and native tool calling.
Natural language
9-tier engine
Voice input
Feedback learning
ai-cmd at a glance
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 9-tier AI engine: TF-IDF, ONNX Intent Classifier, ONNX Semantic, Mistral.rs, GenAI / Ollama, Local LLM (legacy), Claude Code, OpenAI Codex CLI, and OpenCode. It collects user feedback to improve accuracy over time and supports voice input, interactive sessions, automated suggestions, real-time streaming, and native tool calling.
Reference and verification
This is a scenario-first guide: operational workflows, real run order, and troubleshooting. For the full autogenerated command and flag catalog, use the ai-cmd CLI Reference, or read the raw signer JSON.
SHA256 (v9.8.4): 395cb5ae0f48cb7d87ac7e4952421e441d88ce25c886ab3007b4d8a9e4087e75
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 9-tier AI engine. 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.
Engine Tiers (canonical order)
This is the authoritative order reported by ai-cmd tiers. Availability and selection depend on the command mode and configured engines; Codex and OpenCode are explicit choices. Tier numbers throughout this guide refer to this table.
| Tier | Engine | Role |
|---|---|---|
| 1 | TF-IDF | Always available, no setup. Keyword/statistical match |
| 2 | ONNX Intent Classifier | Fast-path intent classification (12 categories, under 5 ms, routes directly to tools) |
| 3 | ONNX Semantic | Neural semantic command matching (download plus train) |
| 4 | Mistral.rs | Local GGUF LLM reasoning (slow-path) |
| 5 | GenAI / Ollama | Multi-provider LLM via Ollama (local) or configured external providers |
| 6 | Local LLM (legacy) | GGUF via llama-cpp-2, deprecated in favor of the Mistral.rs tier |
| 7 | Claude Code | Claude CLI, available when configured |
| 8 | OpenAI Codex CLI | Codex CLI, explicit opt-in when configured |
| 9 | OpenCode | OpenCode CLI, explicit opt-in when configured |
External provider privacy boundary
Local engines process prompts on the device. A configured external provider or provider CLI may transmit the prompt and relevant query context to that provider. Select those engines only when that data transfer is acceptable.
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 local Ollama or configured external providers; external providers may receive prompts and query context |
| 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 3)
# 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 4)
# 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 5)
# 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: External Cloud Provider via Tor
Tor can conceal the network origin from the provider, but the provider still receives the submitted prompt and relevant query context.
# Route the provider connection through Tor; prompt data still leaves the device
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-tor (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-tor (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"
Step 4: Submit Related Corrections
# 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-hard (0.91)
# 2. health-control block-internet (0.84)
# 3. health-control mac-change-all (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-hard (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-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 block-internet
# Confidence: 0.94
# Effect: Blocks all network interfaces
# Reversible: Yes (health-control unblock-internet)
# 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-tor-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-switch fix-dns'"
# → "Tor circuit is stale, run 'tor-switch new-tor-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's engine has 9 tiers (see the canonical Engine Tiers table). Tiers 2 and 5 use the ONNX classifier and optional GenAI provider paths; Codex and OpenCode are explicit CLI choices. Tier numbers here match that canonical table.
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 3: 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 6: Local LLM (legacy) with GGUF Model (Download GGUF File)
Local LLMs provide advanced reasoning and multi-step analysis while remaining offline.
Step 1: Create Models Directory
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-switch fix-dns)
# 2. Tor routing (tor-switch start-tor)
# 3. Network monitoring (health-control net-check)
#
# ✓ Suggested command: dns-switch fix-dns
# 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 7: Claude Code (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 dnscrypt-set
# 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 (~60%) | No | Exact keyword matches |
| 2 | onnx |
ai-trainer download-model + train |
~10ms | Very Good (~85%) | No | Semantic embedding match |
| 3 | onnx-classifier |
Same ONNX setup | <5ms | Excellent (~90%) | No | Intent fast-path classifier head (12 categories) |
| 4 | llm |
Download GGUF file (deprecated) | ~500ms | Good (~80%) | No | Legacy LLM (use mistral) |
| 5 | mistral |
Download GGUF file | ~200ms | Excellent (~85%) | No | Local LLM reasoning |
| 6 | genai |
Configure Ollama or cloud provider | ~300ms | Excellent (~90%) | Optional | Multi-provider LLM |
| 7 | claude |
Install CLI + login | ~1000ms | State-of-art (~98%) | Yes | Expert analysis (opt-in only) |
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 ONNX (if model downloaded)
# 2. Try Mistral.rs (if GGUF model exists)
# 3. Try GenAI/Ollama (if configured)
# 4. Try Legacy LLM (if configured)
# 5. Fallback to TF-IDF (always available)
# Note: Claude CLI requires explicit --engine claude (opt-in only, not in auto mode)
# 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. Interactive mode accepts auto plus seven engine values: tfidf, onnx, onnx-classifier, llm, mistral, genai, and claude. It does not expose the codex or opencode engines.
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-tor-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-tor-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 start-tor (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 connect openvpn (confidence: 0.94)
# ✓ Suggested: dns-switch dnscrypt-set (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 connect 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 block-internet (confidence: 0.82), below threshold 0.9
# Command not executed. Did you mean:
# 1. health-control block-internet (0.82)
# 2. routing-switch disconnect (0.79)
# Execute anyway? [y/N]: n
#
# ai-cmd> block all internet traffic
# ✓ health-control block-internet (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-tor-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-switch fix-dns │
# │ Reason: DNS leak detected on interface wlan0 │
# │ Impact: Privacy compromise │
# │ Confidence: 0.96 │
# │ │
# │ 🔔 RECOMMENDED │
# │ 2. health-control mac-change-all │
# │ Reason: Connected to public WiFi │
# │ Impact: Prevent tracking │
# │ Confidence: 0.89 │
# │ │
# │ 3. tor-switch new-tor-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-switch fix-dns (0.96), DNS leak detected
# 2. health-control mac-change-all (0.89), Public WiFi detected
# 3. tor-switch new-tor-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-switch fix-dns", "reason": "DNS leak detected on interface wlan0", "priority": "urgent", "confidence": 0.96, "impact": "privacy_compromise"
}, {
"command": "health-control mac-change-all", "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-switch fix-dns" (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
Scenario 9: Common Security Operations via Natural Language
Everyday security tasks using ai-cmd instead of remembering exact binary commands.
Network Security Operations
# Check network connectivity
ai-cmd query "check if my connection is secure"
ai-cmd query "is my internet working"
ai-cmd query "test network connectivity"
# Test for DNS leaks
ai-cmd query "test for dns leaks"
ai-cmd query "check if my dns is leaking"
ai-cmd query "verify dns privacy"
# Get IP address information
ai-cmd query "what is my current ip address"
ai-cmd query "show my public ip"
ai-cmd query "get ip geolocation"
Without ai-cmd you would need:
health-control net-check # instead of "check connection"
dns-leak test # instead of "test dns leaks"
ip-fetch fetch # instead of "what is my ip"
Tor Operations
# Start/stop Tor
ai-cmd query "start tor service"
ai-cmd query "stop tor"
ai-cmd query "restart tor daemon"
# Rotate Tor circuit
ai-cmd query "rotate my tor circuit"
ai-cmd query "get a new tor identity"
ai-cmd query "change tor exit node"
# Configure Tor exit country
ai-cmd query "change tor exit country to germany"
ai-cmd query "use swiss tor exit nodes"
ai-cmd query "route through netherlands tor"
# Check Tor status
ai-cmd query "check tor status"
ai-cmd query "is tor working"
ai-cmd query "show tor circuits"
Without ai-cmd you would need:
tor-switch start-tor # instead of "start tor"
tor-switch new-tor-circuit # instead of "rotate circuit"
tor-switch set-exit-node DE # instead of "exit country germany"
tor-switch tor-status # instead of "check tor status"
Emergency Operations (Always Use --dry-run First!)
# Enable panic mode (preview first!)
ai-cmd query "enable panic mode" --dry-run
ai-cmd query "activate medium panic mode" --dry-run
ai-cmd query "trigger hard panic" --dry-run
# Block internet traffic
ai-cmd query "block all internet traffic" --dry-run
ai-cmd query "disable all network interfaces" --dry-run
ai-cmd query "cut off internet connection" --dry-run
# MAC address randomization
ai-cmd query "randomize my mac address" --dry-run
ai-cmd query "change hardware address" --dry-run
ai-cmd query "spoof mac address" --dry-run
# Only execute after reviewing dry-run output
ai-cmd query "enable medium panic mode" --threshold 0.95
Without ai-cmd you would need:
health-control panic-medium # instead of "medium panic mode"
health-control block-internet # instead of "block internet"
health-control mac-change-all # instead of "randomize mac"
System Health and Security Scoring
# Check system health
ai-cmd query "check system health"
ai-cmd query "verify system status"
ai-cmd query "run health diagnostics"
# Get security score
ai-cmd query "show security score"
ai-cmd query "what is my security rating"
ai-cmd query "calculate system security"
# Verify system integrity
ai-cmd query "verify system integrity"
ai-cmd query "check for file modifications"
ai-cmd query "validate system files"
Without ai-cmd you would need:
health-control security-status # instead of "check system health"
health-control security-score # instead of "show security score"
integrity-check check-all # instead of "verify integrity"
DNS Management
# Switch DNS servers
ai-cmd query "switch to cloudflare dns"
ai-cmd query "use google dns servers"
ai-cmd query "configure custom dns"
# Enable secure DNS
ai-cmd query "enable dns over https"
ai-cmd query "activate dnscrypt"
ai-cmd query "secure dns configuration"
# Check DNS status
ai-cmd query "show current dns servers"
ai-cmd query "check dns configuration"
ai-cmd query "get dns status"
Without ai-cmd you would need:
dns-switch switch --names cloudflare # instead of "switch to cloudflare"
dns-switch dnscrypt-set # instead of "enable dns over https"
dns-switch status # instead of "show dns servers"
VPN and Routing
# Enable VPN
ai-cmd query "enable vpn connection"
ai-cmd query "connect to vpn"
ai-cmd query "start vpn service"
# Check routing status
ai-cmd query "show current routing"
ai-cmd query "check vpn status"
ai-cmd query "display routing configuration"
# Switch routing modes
ai-cmd query "route through tor"
ai-cmd query "enable vpn routing"
ai-cmd query "use direct connection"
Without ai-cmd you would need:
routing-switch connect openvpn # instead of "enable vpn"
routing-switch status # instead of "show routing"
routing-switch connect tor # instead of "route through tor"
Comparison: Natural Language vs Raw Commands
| Natural Language (ai-cmd) | Raw Binary Command | Ease of Remembering |
|---|---|---|
| "check if my connection is secure" | health-control net-check |
✓ Easy |
| "test for dns leaks" | dns-leak test |
✓ Easy |
| "rotate my tor circuit" | tor-switch new-tor-circuit |
✓ Easy |
| "change tor exit country to germany" | tor-switch set-exit-node DE |
✓ Easy |
| "show security score" | health-control security-score |
✓ Easy |
| "enable medium panic mode" | health-control panic-medium |
✓ Easy |
| "randomize mac address" | health-control mac-change-all |
✓ Easy |
| "enable dns over https" | dns-switch dnscrypt-set |
✓ Easy |
Why use ai-cmd for daily operations:
- No memorization: Just describe what you want in plain English
- Forgiving syntax: "check tor" and "is tor working" both work
- Faster typing: Natural language is often shorter than exact commands
- Discoverable: Use
ai-cmd suggestto learn new commands - Safe: Preview and dry-run prevent accidental dangerous operations
Scenario 10: Security-First Routing (Fast Path vs Slow Path)
KAICS uses a two-path routing system that prioritizes speed for common queries while maintaining deep reasoning for complex scenarios.
Understanding the Routing System
# Check available AI tiers
ai-cmd tiers --json
# Expected output:
{
"tiers": [
{"name": "tfidf", "available": true, "speed": "1ms", "type": "builtin"}, {"name": "onnx", "available": true, "speed": "5ms", "type": "intent_classifier"}, {"name": "mistral", "available": true, "speed": "200ms", "type": "local_llm"}, {"name": "genai", "available": false, "speed": "300ms", "type": "ollama"}, {"name": "llm", "available": false, "speed": "500ms", "type": "legacy"}, {"name": "claude", "available": false, "speed": "1000ms", "type": "cloud"}
], "default_path": "fast", "onnx_classifier": {
"loaded": true, "model": "distilbert-intent-v1.0.0", "intents": 12
}
}
Fast Path Examples (ONNX Intent Classifier)
The ONNX intent classifier handles ~80% of queries using direct tool mapping with <5ms inference time.
# Network status query (NetworkStatus intent)
ai-cmd query "check network connectivity"
# Intent: NetworkStatus (confidence: 0.92 ≥ 0.75)
# Route: FAST PATH → health-control net-check
# Time: 4ms
# Tor control query (TorControl intent)
ai-cmd query "rotate my tor circuit"
# Intent: TorControl (confidence: 0.89 ≥ 0.80)
# Route: FAST PATH → tor-switch new-tor-circuit
# Time: 3ms
# DNS management query (DnsManagement intent)
ai-cmd query "test for dns leaks"
# Intent: DnsManagement (confidence: 0.94 ≥ 0.75)
# Route: FAST PATH → dns-leak test
# Time: 4ms
# Security check query (SecurityCheck intent)
ai-cmd query "show security score"
# Intent: SecurityCheck (confidence: 0.88 ≥ 0.70)
# Route: FAST PATH → health-control security-score
# Time: 5ms
# System info query (SystemInfo intent)
ai-cmd query "what is my ip address"
# Intent: SystemInfo (confidence: 0.91 ≥ 0.70)
# Route: FAST PATH → ip-fetch fetch
# Time: 3ms
# View intent classification details
ai-cmd query "check network" --json | jq '.routing'
# Expected output:
{
"path": "fast", "classifier": "onnx", "intent": "NetworkStatus", "confidence": 0.92, "threshold": 0.75, "inference_time_ms": 4
}
Slow Path Examples (Mistral.rs → GenAI → Legacy LLM)
Complex queries that require multi-step reasoning route through local LLM engines.
# Complex help request (HelpRequest intent)
ai-cmd query "what's the best way to secure my connection on public wifi?"
# Intent: HelpRequest (confidence: 0.65 ≥ 0.60)
# Route: SLOW PATH → Mistral.rs analysis
# Time: 240ms
# Output: [Detailed explanation of VPN+Tor setup, MAC randomization, etc.]
# Ambiguous query (Unknown intent)
ai-cmd query "make my system safer"
# Intent: Unknown (confidence: 0.42 < 0.50)
# Route: SLOW PATH → Mistral.rs reasoning
# Time: 310ms
# Output: [AI suggests specific commands based on current system state]
# Complex threat analysis
ai-cmd query "analyze my current threat model and recommend improvements"
# Intent: HelpRequest (confidence: 0.71 ≥ 0.60)
# Route: SLOW PATH → Mistral.rs deep analysis
# Time: 450ms
# Output: [Comprehensive threat assessment with actionable steps]
# View routing details for slow path
ai-cmd query "explain tor routing" --json | jq '.routing'
# Expected output:
{
"path": "slow", "classifier": "onnx", "intent": "HelpRequest", "confidence": 0.65, "threshold": 0.60, "llm_engine": "mistral", "inference_time_ms": 240, "reasoning_steps": 3
}
Emergency Action Safety (High Confidence Required)
Emergency intents require very high confidence (≥0.95) for safety.
# Vague emergency query (confidence too low)
ai-cmd query "block internet"
# Intent: EmergencyAction (confidence: 0.82 < 0.95)
# Route: BLOCKED (below safety threshold)
# Output: ⚠ Emergency action requires confidence ≥0.95 (got 0.82)
# Suggestion: Be more specific, e.g., "block all internet traffic"
# Specific emergency query (confidence meets threshold)
ai-cmd query "block all internet traffic immediately"
# Intent: EmergencyAction (confidence: 0.97 ≥ 0.95)
# Route: FAST PATH → health-control block-internet
# Time: 5ms
# Output: ✓ All network interfaces blocked
# Preview emergency commands before executing
ai-cmd preview "enable panic mode" --alternatives 3
# Shows top 3 panic mode options with confidence scores
# Allows review before execution
# Force execution with explicit threshold override
ai-cmd query "enable medium panic" --threshold 0.90
# Lowers threshold to 0.90 (only if you're sure!)
Fast Path vs Slow Path Comparison
| Query Type | Example | Intent | Path | Time | Engine |
|---|---|---|---|---|---|
| Network check | "check network" | NetworkStatus | FAST | 4ms | ONNX → tool |
| Tor control | "rotate tor circuit" | TorControl | FAST | 3ms | ONNX → tool |
| DNS test | "test dns leaks" | DnsManagement | FAST | 4ms | ONNX → tool |
| Security info | "show security score" | SecurityCheck | FAST | 5ms | ONNX → tool |
| Help request | "how to secure wifi" | HelpRequest | SLOW | 240ms | ONNX → Mistral.rs |
| Ambiguous | "make system safer" | Unknown | SLOW | 310ms | ONNX → Mistral.rs |
| Emergency | "panic mode" | EmergencyAction | FAST* | 5ms | ONNX → tool (≥0.95) |
* Emergency actions require confidence ≥0.95 or explicit threshold override
Routing Strategy Best Practices
# Default (auto routing), let system decide
ai-cmd query "check tor status"
# Uses FAST PATH if ONNX classifier is confident
# Force FAST PATH (skip LLM reasoning)
ai-cmd query "check network" --engine onnx
# Always uses ONNX classifier, even for low-confidence queries
# Force SLOW PATH (deep reasoning)
ai-cmd query "check network" --engine mistral
# Bypasses ONNX classifier, goes straight to Mistral.rs
# Explicit Claude (opt-in only, NOT in auto mode)
ai-cmd query "analyze threat model" --engine claude
# Requires manual selection, never auto-selected
# Check routing decision for any query
ai-cmd preview "your query here" --json | jq '.routing'
When to use each path:
- FAST PATH (auto): Common operations, quick checks, daily use
- SLOW PATH (mistral): Complex questions, troubleshooting, learning
- EXPLICIT CLAUDE: Expert analysis, sensitive decisions, threat modeling (manual only)
Fast Path Benefits:
- ⚡ Ultra-fast response (<5ms)
- 🔒 100% local processing
- 📊 Handles 80% of queries
- 💾 Minimal resource usage
Slow Path Benefits:
- 🧠 Deep reasoning and analysis
- 📚 Multi-step problem solving
- 🎯 Handles ambiguous queries
- 💡 Educational explanations
Scenario 11: AI Policy Management
The AI policy system provides fine-grained control over intent classification, tool execution, and safety thresholds.
Viewing Current Policy
# Check current AI policy
ai-cmd policy
# Expected output:
AI Policy Configuration
────────────────────────────────────────────
Version: 1.0.0
Risk Mode: safe
Policy File: results/ai-policy.json
Signature: Valid (RSA-SHA256)
Intent Thresholds:
NetworkStatus: 0.75
TorControl: 0.80
VpnControl: 0.80
DnsManagement: 0.75
SecurityCheck: 0.70
SystemInfo: 0.70
FileManagement: 0.80
ServiceControl: 0.85
ConfigurationChange: 0.85
HelpRequest: 0.60
EmergencyAction: 0.95
Unknown: 0.00
Tool Allowlist (9 binaries):
✓ health-control
✓ tor-switch
✓ dns-leak
✓ dns-switch
✓ routing-switch
✓ ip-fetch
✓ integrity-check
✓ permission-guard
✓ online-auth
# View policy as JSON
ai-cmd policy --json > current-policy.json
Generating AI Policy from Learning Data
# Generate policy after learning cycle
sudo ai-learner learn --output-policy
# Expected output:
✓ Processing 142 feedback entries
✓ Analyzing intent confidence patterns
✓ Calculating optimal thresholds
✓ Generating AI policy file
✓ Policy saved to: results/ai-policy.json
✓ Policy signature: 8f3a9c2b...
✓ Verification: Valid
# Verify policy integrity
ai-admin diagnostics --full
# Expected output:
Policy Integrity Check:
✓ File exists: results/ai-policy.json
✓ Valid JSON structure
✓ Signature verification: PASS
✓ Schema validation: PASS
✓ Threshold ranges: VALID (0.00-1.00)
✓ Tool allowlist: 9 binaries
✓ Risk mode: safe
Understanding Intent Thresholds
# Test query against current policy
ai-cmd query "check network connectivity" --dry-run --json | jq '.policy_check'
# Expected output:
{
"intent": "NetworkStatus", "confidence": 0.92, "threshold": 0.75, "meets_threshold": true, "action": "execute", "tool": "health-control net-check", "allowed_by_policy": true
}
# Test emergency action query
ai-cmd query "enable panic mode" --dry-run --json | jq '.policy_check'
# Expected output:
{
"intent": "EmergencyAction", "confidence": 0.88, "threshold": 0.95, "meets_threshold": false, "action": "block", "reason": "Confidence below safety threshold for emergency actions"
}
Policy Risk Modes
The policy file supports two risk modes:
Safe Mode (default):
- Emergency actions require ≥0.95 confidence
- Service control requires ≥0.85 confidence
- Configuration changes require ≥0.85 confidence
- Conservative tool allowlist
Advanced Mode:
- Emergency actions require ≥0.90 confidence
- Lower thresholds for experienced users
- Extended tool allowlist
# Switching risk modes requires editing policy file
sudo nano results/ai-policy.json
# Change: "risk_mode": "safe" → "risk_mode": "advanced"
# Verify policy after manual edit
ai-admin diagnostics --full
Policy-Based Query Examples
# Query allowed by policy (confidence meets threshold)
ai-cmd query "check tor status"
# Intent: TorControl (0.89 ≥ 0.80) → ALLOWED
# Query blocked by policy (confidence below threshold)
ai-cmd query "tor"
# Intent: TorControl (0.62 < 0.80) → BLOCKED (too vague)
# Suggestion: Be more specific, e.g., "check tor status"
# Emergency action blocked by policy (safety threshold)
ai-cmd query "panic"
# Intent: EmergencyAction (0.78 < 0.95) → BLOCKED
# Suggestion: Use explicit command, e.g., "enable medium panic mode"
# Override policy threshold (use carefully!)
ai-cmd query "panic" --threshold 0.75
# Executes despite policy threshold (manual override)
# Tool not in allowlist
ai-cmd query "run custom script"
# Intent: ServiceControl (0.87 ≥ 0.85) → BLOCKED
# Reason: "custom-script" not in tool allowlist
Policy Audit and History
# Show policy change history
ai-admin db info
# Expected output:
timestamp | version | risk_mode | change_reason
────────────────────────────────────────────────────────────
2026-02-09 14:23:11 | 1.0.0 | safe | Generated after learning cycle
2026-02-08 08:15:42 | 0.9.9 | safe | Manual threshold adjustment
2026-02-07 12:34:19 | 0.9.8 | advanced | Switched to advanced mode
# Export policy for backup
cp results/ai-policy.json backups/ai-policy-$(date +%Y%m%d).json
# Restore policy from backup
sudo cp backups/ai-policy-20260209.json results/ai-policy.json
ai-admin diagnostics --full
Policy Best Practices:
- ✓ Regenerate policy after major learning cycles
- ✓ Verify policy integrity with
ai-admin diagnostics --full - ✓ Backup policy files before making manual changes
- ✓ Use safe mode (default) unless you're an expert user
- ✓ Never lower EmergencyAction threshold below 0.90
- ✗ Don't manually edit policy without verification
- ✗ Don't add unknown binaries to tool allowlist
Scenario 12: Model Management and Selection
KAICS supports multiple model types across different tiers, with automated download and selection.
Downloading Models
# Download ONNX intent classifier model (Tier 2, required for FAST PATH)
sudo ai-trainer download-model
# Expected output:
Downloading ONNX intent classifier model...
✓ Model: distilbert-intent-v1.0.0.onnx (84.3 MB)
✓ Tokenizer: vocab.txt (226 KB)
✓ Config: model-config.json (1.2 KB)
✓ Saved to: /opt/kodachi/ai-models/
✓ Model ready for use
# Download Mistral.rs LLM models (Tier 4, for SLOW PATH reasoning)
sudo ai-trainer download-model --llm default
# Downloads: Qwen3-1.7B-Q4_K_M (1.7B params, ~1.1 GB) Best balance for 4 GB systems
sudo ai-trainer download-model --llm small
# Downloads: Qwen3-1.7B-Q4_K_S (1.7B params, ~1.0 GB) Faster inference, smallest footprint
sudo ai-trainer download-model --llm large
# Downloads: Phi-3.5-mini-instruct (3.8B params, ~2.3 GB) 128K context, advanced reasoning
sudo ai-trainer download-model --llm xlarge
# Downloads: Qwen3-8B-Q4_K_M (8B params, ~4.8 GB) 8B class tuned for SPEED, needs 8+ GB RAM
sudo ai-trainer download-model --llm xlarge-hq
# Downloads: Qwen3-8B-Q5_K_M (8B params, ~5.6 GB) 8B class tuned for QUALITY, needs 16+ GB RAM
# Same Qwen3-8B weights as xlarge, higher-precision quantization, ~15% slower
# List all available models
sudo ai-trainer download-model --show-models
# Expected output:
Available Models:
────────────────────────────────────────────
ONNX Models (Tier 3):
✓ all-MiniLM-L6-v2 ~90 MB Embeddings model (semantic search)
LLM Models (Tier 4):
○ Qwen3-1.7B-Q4_K_M.gguf ~1.1 GB default (recommended, balanced)
○ Qwen3-1.7B-Q4_K_S.gguf ~1.0 GB small (fastest tiny model)
○ Phi-3.5-mini-instruct.gguf ~2.3 GB large (128K context)
○ Qwen3-8B-Q4_K_M.gguf ~4.8 GB xlarge (8B SPEED, 8+ GB RAM)
○ Qwen3-8B-Q5_K_M.gguf ~5.6 GB xlarge-hq (8B QUALITY, 16+ GB RAM)
Use --llm [default|small|large|xlarge|xlarge-hq] to download
Using Downloaded Models
# Auto-detect and use best available model
ai-cmd query "check security status" --engine auto
# Auto-selects ONNX for FAST PATH or Mistral.rs for SLOW PATH
# Force ONNX intent classifier (FAST PATH)
ai-cmd query "check tor status" --engine onnx
# Uses distilbert-intent classifier
# Force Mistral.rs with default model (SLOW PATH)
ai-cmd query "explain threat model" --engine mistral
# Uses Qwen3-1.7B-Q4_K_M (if downloaded as `default`); if you downloaded xlarge-hq
# instead, the dashboard model selector will route to Qwen3-8B-Q5_K_M.
# Use specific GGUF model file
ai-cmd query "analyze network" --use models/Phi-3.5-mini-instruct-Q4_K_M.gguf
# Loads and uses specified model
# Stream responses from LLM
ai-cmd query "explain tor routing" --engine mistral --stream
# Real-time token streaming from Mistral.rs
# Adjust LLM temperature for creativity
ai-cmd query "suggest security improvements" --engine mistral --temperature 0.8
# Higher temperature = more creative responses
Model Status and Information
# Check all loaded models
ai-trainer status
# Expected output:
AI Engine Status
────────────────────────────────────────────
Tier 1 (TF-IDF):
Status: ✓ Active
Type: Built-in statistical matching
Speed: ~1ms
Setup: None required
Tier 2 (ONNX Intent Classifier):
Status: ✓ Active
Model: distilbert-intent-v1.0.0
Size: 84.3 MB
Accuracy: 94.2% on test set
Speed: ~5ms
Intents: 12 categories
Location: /opt/kodachi/ai-models/
Tier 3 (ONNX Semantic):
Status: ✓ Active
Model: all-MiniLM-L6-v2.onnx
Speed: ~10ms
Tier 4 (Mistral.rs):
Status: ✓ Active
Model: Qwen3-1.7B-Q4_K_M.gguf # (or Qwen3-8B-* if xlarge/xlarge-hq downloaded)
Size: 1.1 GB # 4.8 GB for xlarge, 5.6 GB for xlarge-hq
Parameters: 1.7B # 8B for xlarge tiers
Quantization: Q4_K_M # Q5_K_M for xlarge-hq
Speed: ~200ms # ~1-3 tokens/sec on CPU for 8B tiers
Location: ./models/
Tier 5 (Ollama / GenAI):
Status: ✗ Not configured
Providers: None detected
Tier 6 (Legacy LLM):
Status: ✗ Deprecated (use Mistral.rs)
Tier 7 (Claude CLI):
Status: ✗ Not configured
Required: claude-cli + API key
# Check specific model info
ai-cmd model-info --json
# Expected output:
{
"onnx_classifier": {
"loaded": true, "model": "distilbert-intent-v1.0.0", "size_mb": 84.3, "intents": 12, "accuracy": 0.942, "inference_time_ms": 5
}, "mistral_llm": {
"loaded": true, "model": "Qwen3-1.7B-Q4_K_M.gguf", "size_gb": 1.1, "parameters": "1.7B", "quantization": "Q4_K_M", "inference_time_ms": 200
}
}
Model Recommendations by Use Case
# CPU-only systems / 4 GB RAM
sudo ai-trainer download-model # ONNX embeddings model
sudo ai-trainer download-model --llm small # Qwen3-1.7B Q4_K_S (~1.0 GB)
ai-cmd query "check network" --engine auto # Uses ONNX + small Qwen3
# 8 GB RAM systems (balanced)
sudo ai-trainer download-model # ONNX embeddings model
sudo ai-trainer download-model --llm default # Qwen3-1.7B Q4_K_M (~1.1 GB)
ai-cmd query "analyze security" --engine auto # Uses ONNX + default Qwen3
# 8-16 GB RAM systems, want better answers and willing to wait
sudo ai-trainer download-model # ONNX embeddings model
sudo ai-trainer download-model --llm xlarge # Qwen3-8B Q4_K_M (~4.8 GB) SPEED-tuned 8B
ai-cmd query "threat analysis" --engine mistral # Uses 8B model, ~2-3 tokens/sec on CPU
# 16+ GB RAM systems (best local quality)
sudo ai-trainer download-model # ONNX embeddings model
sudo ai-trainer download-model --llm xlarge-hq # Qwen3-8B Q5_K_M (~5.6 GB) QUALITY-tuned 8B
ai-cmd query "threat analysis" --engine mistral # Best local-LLM output, ~1.5-2 tokens/sec on CPU
# 32+ GB RAM systems with reasoning workloads
sudo ai-trainer download-model # ONNX embeddings model
sudo ai-trainer download-model --llm large # Phi-3.5-mini (~2.3 GB), 128K context
ai-cmd query "long-context reasoning" --engine mistral
# Low storage / embedded systems
sudo ai-trainer download-model # ONNX only (~90 MB)
ai-cmd query "check tor" --engine onnx # FAST PATH only
# Privacy-critical environments (no cloud)
sudo ai-trainer download-model # ONNX embeddings model
sudo ai-trainer download-model --llm default # Qwen3-1.7B-Q4_K_M (or xlarge / xlarge-hq for stronger offline reasoning)
# Never use --engine claude or genai with cloud providers
# Expert analysis (opt-in cloud)
sudo ai-trainer download-model # ONNX classifier
# Install Claude CLI separately
ai-cmd query "analyze threat model" --engine claude --tor-proxy
# Routes the connection through Tor; Claude still receives the prompt
Model Update and Maintenance
# Force re-download if model is corrupted
sudo ai-trainer download-model --force
sudo ai-trainer download-model --llm default --force
# Verify model integrity
ai-admin diagnostics --full
# Expected output:
Model Integrity Check:
✓ ONNX model: Valid (SHA256 match)
✓ ONNX tokenizer: Valid
✓ Mistral model: Valid (GGUF header OK)
✓ Model files readable
✓ Disk space: 12.4 GB available
# Clean up old model versions
sudo ai-admin tune cleanup --days 30
# Backup current models
tar -czf models-backup-$(date +%Y%m%d).tar.gz /opt/kodachi/ai-models/ ./models/
Model Management Best Practices:
- ✓ Download ONNX model first (required for FAST PATH)
- ✓ Use
--llm defaultfor balanced performance (Qwen3-1.7B Q4_K_M, ~2 GB RAM) - ✓ Use
--llm smallfor low-RAM systems (Qwen3-1.7B Q4_K_S, ~1.8 GB RAM) - ✓ Use
--llm largefor 128K-context reasoning (Phi-3.5-mini) - ✓ Use
--llm xlargeon 8+ GB systems for SPEED-optimized 8B (Qwen3-8B Q4_K_M) - ✓ Use
--llm xlarge-hqon 16+ GB systems for QUALITY-optimized 8B (Qwen3-8B Q5_K_M) - ✓ Verify model integrity after download
- ✓ Backup models before updates
- ✗ Don't mix model versions (incompatible formats)
- ✗ Don't manually edit model files
- ✗ Don't pick xlarge-hq on 8 GB RAM hosts: the loader has no pre-load RAM guard and inference will OOM
Related Workflows
- Complete AI Training Cycle, Train → Query → Feedback → Learn → Analyze
- Troubleshooting AI Accuracy, Diagnose and fix classification issues
- ai-trainer Scenarios, Model training and snapshot management
- ai-learner Scenarios, Learning cycle and accuracy analysis
- ai-discovery Scenarios, Command pattern discovery and training data generation
- ai-monitor Scenarios, System monitoring and proactive suggestions
- Full CLI Reference: ai-cmd Binary Commands, Complete command reference with all flags and options
Key Takeaways
- Start Simple: ai-cmd works immediately with TF-IDF, no setup required
- Upgrade Gradually: Add ONNX for better accuracy, LLM for reasoning, Claude for expert analysis
- Use Feedback: Correct mistakes to improve accuracy over time
- Be Safe: Always use
--dry-runand high--thresholdfor dangerous commands - Voice Control: Enable hands-free operation for accessibility and emergency use
- Script Integration: Use
--jsonoutput for reliable automation - Interactive Sessions: Use REPL mode for faster multi-query workflows
- Proactive Suggestions: Let AI recommend commands based on system state
- Natural Language: Focus on describing what you want, not memorizing exact syntax
Troubleshooting
| Problem | Cause | Solution |
|---|---|---|
| "Command not found" | ai-cmd not in PATH | Run from installation directory or add to PATH |
| Low confidence on all queries | ONNX model not trained | Run sudo ai-trainer download-model && sudo ai-trainer train --data ./data/training-data.json |
| Wrong command matched | Insufficient training data | Use ai-cmd feedback to correct, then ai-learner learn |
| Slow responses (>1s) | Falling through to LLM tiers | Check ONNX model status with ai-cmd tiers |
| Voice input not working | Missing voice-engine dependencies | Install whisper-cpp or vosk, verify with ai-cmd tiers |
--stream shows no output |
LLM tier not configured | Streaming requires Mistral.rs or GenAI tier; check ai-cmd tiers |
| JSON output malformed | Piping issue | Ensure --json flag is before the query argument |