CLI Agent

A powerful, modular command-line interface for interacting with AI models enhanced with Model Context Protocol (MCP) tool integration. Features a centralized architecture that makes it easy to add new LLM providers while providing robust tool integration and subagent management capabilities.

🚀 Features

• Multiple AI Backends: Support for Anthropic Claude, OpenAI GPT, DeepSeek, Google Gemini, OpenRouter, and ollama with easy extensibility
• Deep Research System: Coordinated multi-subagent research workflow with autonomous report generation
• Hooks System: Powerful workflow automation with security controls - audit commands, block dangerous operations, auto-format code, and integrate with external tools
• MCP Model Server: Expose all AI models as standardized MCP tools with persistent conversations
• Modular Architecture: Provider-model separation with centralized base agent for maximum flexibility
• MCP Server Integration: Connect to multiple MCP servers for extended functionality
• Persistent Conversations: Maintain conversation context across multiple tool calls for each AI model
• Interactive Chat: Real-time conversation with AI models and comprehensive tool access
• Subagent System: Spawn focused subagents for complex tasks with automatic coordination
• Command-Line Tools: Manage MCP servers and query models directly
• Built-in Tools: File operations, bash execution, web fetching, todo management, and task delegation
• Enhanced Tool Display: Full parameter visibility and complete response output (no truncation)

📦 Installation

Option 1: Install from PyPI (Recommended)

pip install mcp-cli-agent

Option 2: Install from Source

1. Clone the repository:

   git clone https://github.com/amranu/cli-agent.git
   cd cli-agent
   

2. Install the package:

   pip install -e .
   

⚙️ Configuration

Configure API keys (environment variables):

    # Set environment variables for the providers you want to use
    export OPENAI_API_KEY=your_openai_api_key_here
    export DEEPSEEK_API_KEY=your_deepseek_api_key_here
    export ANTHROPIC_API_KEY=your_anthropic_api_key_here
    export GEMINI_API_KEY=your_gemini_api_key_here
    export OPENROUTER_API_KEY=your_openrouter_api_key_here

    # Start with automatic provider selection
    agent chat
    
    # Or specify a particular provider-model combination
    agent chat --model openai:gpt-4-turbo-preview

Smart Provider Selection: The agent automatically selects a configured provider based on available API keys.

Configuration is automatically saved to ~/.config/cli-agent/config.json and persists across sessions.

Migration from MCP Agent: If you previously used MCP Agent, your configuration will be automatically migrated from ~/.config/mcp-agent/ to ~/.config/cli-agent/ on first run.

🛠️ Usage

Interactive Chat

Start an interactive chat session with your configured AI model and MCP tools:

agent chat --model deepseek:deepseek-chat

MCP Model Server

Start the MCP model server to expose all AI models as standardized MCP tools with persistent conversations:

# Start via stdio transport (recommended for MCP clients)
python mcp_server.py --stdio

# Or start via agent CLI (defaults to stdio)
agent mcp serve
agent mcp serve --stdio  # explicit stdio

# Start with TCP transport (useful for debugging)
python mcp_server.py --tcp --port 3000 --host localhost
agent mcp serve --tcp --port 3000 --host localhost

The model server exposes AI models from 6 providers:

• Anthropic: Claude models
• OpenAI: GPT models
• DeepSeek: Chat and reasoning models
• Gemini: Google's Gemini models
• OpenRouter: Multi-provider access
• Ollama: Local models via Ollama server

MCP Server Management

Add a new MCP server

# Format: name:command:arg1:arg2:...
agent mcp add myserver:node:/path/to/server.js
agent mcp add filesystem:python:-m:mcp.server.stdio:filesystem:--root:.

# Add the AI models server to your MCP configuration
agent mcp add ai-models:python:mcp_server.py:--stdio

List configured servers

agent mcp list

Remove a server

agent mcp remove myserver

Single Query

Ask a one-time question without entering interactive mode:

agent ask "What's the weather like today?"

Model Switching

Switch between different AI models using the provider-model format (configuration persists automatically):

# Provider-model format switching
agent switch anthropic:claude-3.5-sonnet
agent switch openai:gpt-4-turbo-preview
agent switch deepseek:deepseek-chat
agent switch gemini:gemini-2.5-flash

Or use slash commands within interactive chat:

/switch anthropic:claude-3.5-sonnet
/switch openai:gpt-4-turbo-preview
/switch deepseek:deepseek-reasoner
/switch gemini:gemini-2.5-pro

🔧 Configuration

Persistent Configuration System

The agent uses an automatic persistent configuration system that saves settings to ~/.config/cli-agent/config.json:

• API Keys: Set via environment variables
• Model Preferences: Automatically saved when using switch commands
• MCP Servers: Managed through the CLI and persisted across sessions
• Tool Permissions: Configurable with session-based approval system

Environment Variables

Configure the agent through environment variables:

# Anthropic Configuration (required for Claude models)
ANTHROPIC_API_KEY=your_key_here
ANTHROPIC_MODEL=claude-3-5-sonnet-20241022     # optional, defaults to claude-3-5-sonnet-20241022
ANTHROPIC_TEMPERATURE=0.7                      # optional, defaults to 0.7

# OpenAI Configuration (required for GPT models)  
OPENAI_API_KEY=your_key_here
OPENAI_MODEL=gpt-4-turbo-preview               # optional, defaults to gpt-4-turbo-preview
OPENAI_TEMPERATURE=0.7                         # optional, defaults to 0.7

# DeepSeek Configuration (required for DeepSeek models)
DEEPSEEK_API_KEY=your_key_here
DEEPSEEK_MODEL=deepseek-chat                   # optional, defaults to deepseek-chat
DEEPSEEK_TEMPERATURE=0.6                       # optional, defaults to 0.6

# Gemini Configuration (required for Gemini models)
GEMINI_API_KEY=your_key_here
GEMINI_MODEL=gemini-2.5-flash                  # optional, defaults to gemini-2.5-flash
GEMINI_TEMPERATURE=0.7                         # optional, defaults to 0.7

# OpenRouter Configuration (optional for multi-provider access)
OPENROUTER_API_KEY=your_key_here
OPENROUTER_MODEL=anthropic/claude-3.5-sonnet   # optional
OPENROUTER_TEMPERATURE=0.7                     # optional, defaults to 0.7

# Provider-Model Selection (new format)
DEFAULT_PROVIDER_MODEL=anthropic:claude-3.5-sonnet  # defaults to deepseek:deepseek-chat

# Subagent Configuration
SUBAGENT_PERMISSIONS_BYPASS=false             # bypass permission checks for subagents, defaults to false

# Host Configuration (optional)
HOST_NAME=cli-agent                            # defaults to 'cli-agent'
LOG_LEVEL=INFO                                 # defaults to INFO

Configuration changes made via commands (like model switching) are automatically persisted and don't require manual .env file editing.

🎯 Available Tools

Built-in Tools

The agent comes with comprehensive built-in tools:

• File Operations: Read, write, edit, and search files with surgical precision
• Directory Operations: List directories, get current path, navigate filesystem
• Shell Execution: Run bash commands with full output capture
• Web Fetching: Download and process web content
• Todo Management: Organize and track tasks across sessions
• Task Delegation: Spawn focused subagents for complex or context-heavy tasks
• Text Processing: Search, replace, and manipulate text content

AI Model Tools (via MCP Server)

All model tools support:

• Persistent Conversations: Maintain context across calls
• Conversation Management: Create, continue, or clear conversations
• Full Parameter Control: Temperature, max_tokens, system prompts

🔍 Interactive Chat Commands

Within the interactive chat, use these slash commands:

• /help - Show available commands
• /tools - List all available tools
• /clear - Clear conversation history
• /model - Show current model
• /tokens - Show token usage
• /compact - Compact conversation history
• /switch <provider>:<model> - Switch to any provider-model combination
• /deep-research <topic> - Launch coordinated multi-subagent research workflow

📚 Examples

Example: Basic File Operations

agent chat --model deepseek:deepseek-chat

In chat:

You: List all files in this directory
You: Read the contents of agent.py
You: Create a new file called hello.py with a simple function

Example: System Operations

In chat:

You: Show me the current directory
You: Run "git status" to check repository status
You: What's the disk usage of this folder?

Example: Subagent Task Delegation

For complex or context-heavy tasks, delegate to focused subagents:

You: Can you analyze all Python files in the src/ directory and create a summary of the class structure and dependencies?
     [Agent automatically spawns subagent using the task tool]

You: Can you analyze this large log file and find any error patterns?
     [Agent automatically spawns subagent for file analysis]

Subagents work independently and automatically return results to the main conversation.

Example: Deep Research Workflow

For comprehensive research on complex topics, use the coordinated multi-subagent research system:

You: /deep-research Enterprise AI Adoption in Healthcare 2024

[System switches to Research Director role and launches automated workflow]

Research Director: 
1. Creates comprehensive todo list for tracking research phases
2. Breaks down topic into focused sub-topics (e.g., "Current AI Tools", "Implementation Challenges", "ROI Analysis", "Future Trends")
3. Spawns multiple researcher role subagents in parallel
4. Each researcher conducts web searches and creates 3+ source summaries
5. Creates detailed outline based on all research findings
6. Spawns single summarizer role subagent to write sections
7. Assembles final 10-12 page executive report automatically
8. Displays completed research report to user

Final Output: `/tmp/deep_research_master_report_[topic]_[timestamp].md`

Key Features:

• Autonomous Operation: Runs start-to-finish without user intervention
• Parallel Research: Multiple subagents work simultaneously on different aspects
• Role-Based Coordination: Research Director → Researchers → Summarizer workflow
• Comprehensive Coverage: Targets 10-100 sources across academic, industry, news, and expert sources
• Executive Quality: Professional 10-12 page reports with structured analysis

🔬 Deep Research System

The CLI Agent features a sophisticated deep research system that coordinates multiple specialized subagents to conduct comprehensive research on complex topics.

Research Workflow

The /deep-research command launches a fully autonomous research process:

1. Topic Analysis: Research Director analyzes the topic and creates comprehensive todo tracking
2. Parallel Research: Spawns 3-5 researcher role subagents to work simultaneously on different sub-topics
3. Source Collection: Each researcher conducts web searches and creates detailed source summaries (minimum 3 sources each)
4. Outline Creation: Research Director reviews all findings and creates detailed 8-10 section outline
5. Report Writing: Single summarizer role subagent writes all sections with 3-round iterative refinement
6. Final Assembly: Automatically concatenates sections into executive-quality master report

Research Roles

• Research Director: Coordinates the entire workflow, manages todo tracking, and assembles final reports
• Researcher: Conducts web searches, reads sources, and creates comprehensive summaries
• Summarizer: Writes structured report sections based on research findings with iterative refinement

Output Quality

• Target Length: 10-12 pages (5,000-6,000 words)
• Source Coverage: 10-100 sources across academic, industry, news, and expert categories
• Structure: Executive summary, detailed analysis, key findings, recommendations
• Format: Professional markdown reports with proper citations and structure

Usage Examples

# Technology research
/deep-research Enterprise AI Adoption in Healthcare 2024

# Market analysis
/deep-research Competitive Analysis of Electric Vehicle Market 2024

# Technical investigation
/deep-research Cybersecurity Threats in Cloud Infrastructure

# Industry trends
/deep-research Future of Remote Work Technologies Post-2024

All research is conducted autonomously without user intervention, producing publication-ready reports.

🏗️ Architecture

Provider-Model Architecture

┌─────────────────┐
│   CLI Interface │    
│   (agent.py)    │    
└─────────┬───────┘    
          │            
          ▼            
┌─────────────────────┐    ┌─────────────────────────────────────────┐
│      MCPHost        │◄───│              Provider + Model           │
│ (BaseLLMProvider)   │    │                Composition              │
└─────────┬───────────┘    │ ┌─────────────────┐ ┌─────────────────┐ │
          │                │ │   BaseProvider  │ │   ModelConfig   │ │
          ▼                │ │   Subclasses:   │ │   Subclasses:   │ │
┌─────────────────────┐    │ │ • Anthropic     │ │ • ClaudeModel   │ │
│   BaseLLMProvider   │    │ │ • OpenAI        │ │ • GPTModel      │ │
│  (Centralized LLM   │    │ │ • DeepSeek      │ │ • GeminiModel   │ │
│   functionality)    │    │ │ • Google        │ │ • DeepSeekModel │ │
└─────────┬───────────┘    │ │ • OpenRouter    │ │                 │ │
          │                │ └─────────────────┘ └─────────────────┘ │
          ▼                └─────────────────────────────────────────┘
┌─────────────────────┐                         │
│   BaseMCPAgent      │                         ▼
│  (Abstract base)    │               ┌─────────────────┐
└─────────┬───────────┘               │ Tool Converters │
          │                           │ • OpenAI Format │
┌─────────▼───────────┐               │ • Anthropic     │
│ Core Components:    │               │ • Gemini        │
│ • SubagentCoordinator│              └─────────────────┘
│ • BuiltinToolExecutor│                
│ • ChatInterface     │                ┌─────────────────┐
│ • SlashCommands     │◄───────────────│ Built-in Tools  │
│ • ToolExecutionEngine│               │ • File Ops      │
│ • TokenManager      │               │ • Bash Execute  │
│ • SystemPromptBuilder│               │ • Web Fetch     │
│ • MessageProcessor  │               │ • Todo Mgmt     │
└─────────┬───────────┘               │ • Task Spawn    │
          │                           │ • Glob/Grep     │
          ▼                           │ • MultiEdit     │
┌─────────────────────┐               └─────────────────┘
│ External MCP Servers │                      
│ • AI Model Server   │               ┌─────────────────┐
│ • File System       │               │ Subagent System │
│ • APIs & Databases  │               │ • Focused Tasks │
│ • Custom Tools      │               │ • Auto Cleanup  │
└─────────────────────┘               │ • Event-Driven  │
                                      └─────────────────┘

Key Architectural Benefits

• Provider-Model Separation: API providers decoupled from model characteristics
• MCP Model Server: Standardized access to all AI models via MCP protocol
• Persistent Conversations: Conversation context maintained across tool calls
• Easy Extensibility: Adding new providers or models requires minimal code
• Robust Tool Integration: Unified tool execution with provider-specific optimizations
• Intelligent Subagent System: Automatic task delegation and coordination
• Multi-Provider Access: Same model accessible through different providers
• Enhanced Visibility: Full parameter display and complete response output

🤝 Contributing

Please read our CONTRIBUTING.md file for more details on our code of conduct and the process for submitting pull requests.

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes
4. Add tests if applicable
5. Commit your changes: git commit -m 'Add feature'
6. Push to the branch: git push origin feature-name
7. Submit a pull request

📋 Requirements

• Python 3.10+
• API keys for desired providers:
  • Anthropic API key (for Claude models)
  • OpenAI API key (for GPT models)
  • DeepSeek API key (for DeepSeek models)
  • Google AI Studio API key (for Gemini models)
  • OpenRouter API key (for multi-provider access)
• FastMCP for MCP server functionality
• Node.js (for MCP servers that require it)

🔒 Security

• API Keys: Stored as environment variables
• Configuration: Automatically managed in user home directory (~/.config/cli-agent/)
• MCP Servers: Local configurations with session-based tool permissions
• Tool Execution: Built-in permission system for sensitive operations
• Subagent Isolation: Subagents run in controlled environments with specific tool access
• Subagent Permissions: Can be configured to bypass permission checks for automated workflows via SUBAGENT_PERMISSIONS_BYPASS=true

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Model Context Protocol (MCP) for the extensible tool integration framework
• DeepSeek for the powerful reasoning models
• Google AI for Gemini model access
• FastMCP for the Python MCP client implementation

📞 Support

• 🐛 Report Issues
• 💬 Discussions
• 📖 Wiki

---

Happy coding with CLI Agent! 🤖✨