Thanks to visit codestin.com
Credit goes to github.com

Skip to content

amranu/cli-agent

BranchesTags

Repository files navigation

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

📞 Support

Happy coding with CLI Agent! 🤖✨

About

A lightweight Agentic AI framework which works for Mac/Linux/WSL

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

49 stars

Watchers

1 watching

Forks

8 forks
Report repository

Releases

11 tags

Packages

 
 
 

Contributors

Languages