Parallel AI model consultation with intelligent failover. CLI & MCP Server. Automatic retry, real-time cost tracking.
npm install @light-merlin-dark/aia``
█████╗ ██╗ █████╗
██╔══██╗██║██╔══██╗
███████║██║███████║
██╔══██║██║██╔══██║
██║ ██║██║██║ ██║
╚═╝ ╚═╝╚═╝╚═╝ ╚═╝
Parallel AI model consultation with intelligent failover
CLI & MCP Server • Query multiple models simultaneously • Automatic retry and cost tracking
`
- Query multiple AI models in parallel (GPT-4, Claude, 50+ models via OpenRouter)
- Automatic retry with intelligent failover (60s timeout, 90s retry with exponential backoff)
- Real-time cost tracking with configurable pricing (per-model token usage and cost breakdown)
- Encrypted credential storage (AES-256-GCM, local-only key management)
- Plugin architecture for easy provider integration
`bash`
npm install -g @light-merlin-dark/aia
`bashFirst run launches interactive setup
aia consult "Explain async/await in JavaScript"
All consultations return structured JSON with usage stats and cost breakdowns.
Core Commands
$3
`bash
Single model (uses configured default)
aia consult "Your question here"
aia c "Your question here" # Short aliasMultiple models in parallel
aia consult "Compare approaches" -m gpt-4-turbo claude-sonnet-4 openrouter/google/gemini-2-proAttach files for context
aia consult "Review this implementation" -f src/api.ts src/types.tsAttach directories
aia consult "Analyze codebase" -d src/ -d tests/Best-of selection (evaluates responses and picks best)
aia consult "Critical decision" -m gpt-4 claude-3-opus --best-of
`$3
`bash
View current config (secrets masked)
aia config listSet default model
aia config set-default anthropic/claude-sonnet-4Set default service (used when no model specified)
aia config set-default-service anthropicConfigure pricing for cost tracking ($ per 1M tokens)
aia services cost set openai gpt-4-turbo --input 10 --output 30
aia services cost listManage services interactively
aia servicesBackup and restore
aia config backup my-backup
aia config list-backups
aia config restore my-backupReset configuration
aia reset
`$3
`bash
System health check
aia doctorView logs with filtering
aia config view-logs --level ERROR --search timeout --lines 50
`Configuration
Configuration is stored encrypted in
~/.aia/config.enc:`json
{
"services": {
"openai": {
"apiKey": "sk-...",
"models": ["gpt-4-turbo", "o3-mini"],
"pricing": {
"gpt-4-turbo": {
"inputCostPerMillion": 10,
"outputCostPerMillion": 30
}
}
},
"anthropic": {
"apiKey": "sk-ant-...",
"models": ["claude-sonnet-4-20250514"],
"pricing": {
"claude-sonnet-4-20250514": {
"inputCostPerMillion": 3,
"outputCostPerMillion": 15
}
}
},
"default": {
"service": "anthropic"
}
}
}
`Optional environment variables:
-
OPENAI_API_KEY - OpenAI API key
- ANTHROPIC_API_KEY - Anthropic API key
- OPENROUTER_API_KEY - OpenRouter API key
- AIA_CONFIG_DIR - Custom config directoryPlugin System
Built-in providers:
- OpenAI: O3-mini, GPT-4, GPT-4 Turbo, GPT-3.5-turbo
- Anthropic: Claude Sonnet 4, Claude Opus 4, Claude 3 models
- OpenRouter: Gateway to 50+ models (Gemini, Mixtral, Llama, etc.)
Create custom plugins:
`typescript
import { AIProviderPlugin } from 'aia/types';const myPlugin: AIProviderPlugin = {
name: 'my-provider',
version: '1.0.0',
async listModels() {
return ['model-1', 'model-2'];
},
async execute(model, prompt, options) {
// Your API integration
return {
content: response,
metadata: { tokensUsed: 100 }
};
},
validateConfig(config) {
return !!config.apiKey;
},
getRequiredEnvVars() {
return ['MY_PROVIDER_API_KEY'];
}
};
export default myPlugin;
`MCP Server
AIA includes an MCP server for integration with Claude Code, Claude Desktop, and other MCP-compatible tools.
$3
`bash
Install as MCP server
aia install
`$3
Core Consultation:
-
consult - Query multiple models with file attachments and cost tracking
- config-list - View configuration (secrets masked)
- config-get - Get service-specific configuration
- config-set - Update configuration values
- config-remove - Remove servicesModel Management:
-
config-add-model - Add models to services
- config-set-default - Set default model
- config-set-default-service - Set default service
- config-clear-default - Clear default model
- config-set-pricing - Configure cost tracking
- config-get-pricing - View pricing informationDiagnostics:
-
doctor - System health check with plugin status
- config-view-logs - View and filter server logs
- config-backup - Backup configuration
- config-list-backups - List available backupsSee MCP Usage Guide for detailed examples.
Response Format
All consultation responses include structured data:
`json
{
"responses": [
{
"model": "gpt-4-turbo",
"provider": "openai",
"content": "...",
"usage": {
"promptTokens": 150,
"completionTokens": 350,
"totalTokens": 500
}
}
],
"failed": [],
"durationMs": 3456,
"bestIndex": 0,
"costs": [
{
"model": "gpt-4-turbo",
"promptCost": 0.0015,
"completionCost": 0.0105,
"totalCost": 0.012
}
],
"totalCost": 0.012
}
`Development
`bash
Clone and install
git clone https://github.com/light-merlin-dark/ai-advisor.git
cd ai-advisor
make installDevelopment
make dev # Run CLI in development
make mcp-dev # Run MCP server
make test # Run test suite
make lint # Lint codeRelease
make release # Full release workflow (lint, test, build, publish)
`$3
`
aia/
├── src/ # Core application code
├── plugins/ # Provider plugin implementations
├── scripts/ # Development automation
├── tests/ # Test suites
└── docs/ # Documentation
``- AES-256-GCM encryption for credentials
- Local-only key management (keys never leave your machine)
- Path validation against directory traversal
- Input sanitization for safe handling
- Automatic rate limiting per provider
- Parallel execution with Promise.allSettled
- Connection pooling (reused HTTP clients per provider)
- Lazy plugin loading (loaded only when needed)
- Smart timeouts (60s first attempt, 90s retry)
- Minimal orchestration overhead (<100ms)
MIT
---
Built by Robert E. Beckner III (Merlin)