Skip to content

unified cli hub

Jump to bottom
hbt edited this page Jun 22, 2025 · 1 revision

Unified Agentic CLI Hub

Status: Concept
Priority: High
Estimated Effort: Large (6+ months)
Dependencies: Research into existing CLI tools with JSON output support

Vision

Create a universal CLI tool that acts as a meta-agent, orchestrating multiple agentic AI providers (Claude Code, Aider, Amazon Q, etc.) through a unified interface. This addresses vendor lock-in risks while optimizing costs and reliability through intelligent provider routing.

Requirements

Functional Requirements

  • Multi-Provider Support: Integrate Claude Code, Aider, and other agentic CLI tools
  • JSON Standardization: Normalize output formats across all providers
  • Smart Routing: Automatically select optimal provider based on task type, cost, and performance
  • Cost Tracking: Real-time usage monitoring with budget controls
  • Workflow Presets: YAML-based configuration for common development workflows
  • Fallback Logic: Graceful degradation when primary providers fail

Non-Functional Requirements

  • Performance: <200ms overhead for provider routing decisions
  • Reliability: 99.9% uptime with fallback providers
  • Cost Optimization: Target 40% cost reduction vs individual tool subscriptions
  • Extensibility: Plugin architecture for custom providers
  • Observability: Full logging and analytics for all operations

Constraints and Limitations

  • Dependent on provider APIs and their stability
  • JSON output format compliance varies by provider
  • Rate limiting and API costs from multiple providers
  • Initial development complexity for adapter pattern

Technical Approach

Core Architecture

Unified CLI Hub
├── Provider Adapters (Claude Code, Aider, Custom)
├── Output Normalizer (JSON standardization)
├── Task Router (intelligent provider selection)
├── Configuration Manager (presets, costs, settings)
└── Monitoring & Analytics (usage, performance, costs)

Key Technologies

  • Language: Go (leveraging existing FH/HBT CLI patterns)
  • Configuration: YAML for workflow presets
  • Output Format: JSON with standardized schema
  • Plugin System: Go plugins or external binary adapters
  • Cost Tracking: SQLite for local storage, optional cloud sync

Provider Adapter Pattern

Each provider implements a standard interface:

type Provider interface {
    Execute(ctx context.Context, task Task) (*Result, error)
    GetCapabilities() []TaskType
    GetCostEstimate(task Task) (*CostEstimate, error)
    HealthCheck() error
}

Implementation Plan

Phase 1: Foundation (2-3 months)

  • Core CLI framework with plugin architecture
  • Basic Claude Code adapter with JSON output parsing
  • Simple Aider adapter for comparison
  • Configuration system for provider settings
  • Cost tracking foundation (local storage)
  • Basic task routing (manual provider selection)

Phase 2: Intelligence (2-3 months)

  • Smart provider routing based on task analysis
  • Workflow preset system with YAML configuration
  • Advanced cost optimization algorithms
  • Performance monitoring and analytics
  • Fallback and retry logic
  • Integration with existing FH/HBT CLI patterns

Phase 3: Ecosystem (2+ months)

  • Plugin marketplace and custom provider SDK
  • Advanced analytics dashboard
  • Multi-team and enterprise features
  • ML-powered provider selection optimization
  • Community contributions and partnerships

Success Criteria

Technical KPIs

  • Provider adapter response time < 200ms overhead
  • 99.9% JSON output format compliance across providers
  • Cost tracking accuracy within 1%
  • Zero data loss during provider switches

User Experience KPIs

  • Single command replaces 3+ separate tools
  • 30% reduction in context switching
  • Sub-second task routing decisions
  • 24/7 availability through fallback providers

Business KPIs

  • 40% cost reduction vs individual subscriptions
  • 2x faster task completion through smart routing
  • Zero vendor lock-in dependencies
  • Community adoption and contribution growth

Risks & Mitigation

Technical Risks

  • Provider API Changes: Adapter pattern isolates breaking changes
  • Rate Limiting: Built-in retry logic and provider rotation
  • JSON Format Drift: Automated schema validation and updates
  • Performance Overhead: Lazy loading, caching, and optimization

Business Risks

  • Provider Pricing Changes: Multi-provider strategy spreads risk
  • Tool Deprecation: Open source ensures project continuity
  • Competition: Focus on unique value proposition (orchestration)
  • Adoption: Clear migration path and compelling cost benefits

First Experiment Candidates

  1. Provider Adapter POC: Simple wrapper for Claude Code with JSON output
  2. Cost Tracking MVP: Basic usage monitoring for existing tools
  3. Task Router Prototype: Rule-based provider selection logic
  4. Workflow Preset Demo: YAML-driven multi-step task execution

MVP Definition (2-week spike)

Minimal Viable Product:

  • Single command that routes to either Claude Code OR Aider
  • Standardized JSON output from both providers
  • Basic cost tracking with simple budget alerts
  • Configuration file for provider preferences
  • Integration with existing development workflow

Success Criteria for MVP:

# Should work seamlessly
unified-cli refactor --file src/main.go --provider auto
unified-cli test-gen --budget 0.50 --prefer claude-code
unified-cli status --costs --json

References

This represents the evolution from problem identification to structured implementation plan. The scope is ambitious but broken into manageable phases with clear success criteria.

Clone this wiki locally