aiflow-cli/README.md

Intelligent AI Assistant with Smart Model Routing - Created by DavidFon

# 🚀 AiFlow CLI

> Intelligent AI Assistant with Smart Model Routing  
> Created by [DavidFon](https://davidfon.dev) (冯志伟)

![AiFlow CLI Screenshot](./docs/assets/aiflow-screenshot.png)

## 👋 Meet the Creator

Hi! I'm **DavidFon**, a full-stack developer who got tired of expensive AI bills.
AiFlow was born from my personal frustration with paying $300+/month for AI APIs
when most tasks could be handled by cheaper models.

This repository contains the AiFlow CLI, an intelligent AI assistant that helps developers
**save 75-85% on AI costs** through smart model routing while maintaining high-quality results.

**Why AiFlow?**

- 💰 Save 75-85% on AI costs through intelligent routing
- 🎯 Built by developers, for developers
- 🌟 Open source and community-driven
- 🚀 Production-ready with enterprise features
- 🔗 **Restored MCP support** for enhanced integrations and extensibility

With AiFlow CLI you can:

- Query and edit large codebases with smart model selection for optimal cost-performance
- Generate new apps from PDFs or sketches using multimodal capabilities
- Automate operational tasks with intelligent cost optimization
- Use tools and MCP servers to connect new capabilities
- Leverage smart routing to use the right model for each specific task
- **Track and optimize AI costs in real-time** with comprehensive cost management tools
- **Enhanced MCP (Model Context Protocol) support** for extended functionality and integrations

## Quickstart

1. **Prerequisites:** Ensure you have [Node.js version 18](https://nodejs.org/en/download) or higher installed.
2. **Run the CLI:** Execute the following command in your terminal:

   ```bash
   npx aiflow-cli
   ```

   Or install it with:

   ```bash
   npm install -g aiflow-cli
   aiflow
   ```

   **Proxy Settings (v1.2.181+):** AiFlow now runs without proxy by default. If you need proxy support:

   ```bash
   # Use built-in proxy
   prox aiflow

   # Use custom proxy
   export AIFLOW_PROXY=http://your-proxy:8080
   prox aiflow
   ```

3. **Pick a color theme**
4. **Configure your AI providers:** AiFlow supports multiple AI providers for smart routing. Configure your preferred models and API keys.

You are now ready to use AiFlow CLI with intelligent cost optimization!

### 🎯 Creator's Mission

_"Every developer deserves access to powerful AI tools without breaking the bank"_ - DavidFon

### For advanced configuration:

AiFlow supports multiple AI providers for optimal cost-performance routing:

1. Configure your preferred models in the settings
2. Set up API keys for your chosen providers
3. Let AiFlow automatically route to the most cost-effective model for each task

For detailed configuration, see the [authentication](./docs/cli/authentication.md) guide.

## Examples

Once AiFlow CLI is running, you can start leveraging intelligent AI routing from your shell.

You can start a project from a new directory:

```sh
cd new-project/
aiflow
> Write me a Discord bot that answers questions using a FAQ.md file I will provide
```

Or work with an existing project:

```sh
cd your-project
aiflow
> Give me a summary of all of the changes that went in yesterday
```

**With proxy (if needed):**

```sh
cd your-project
prox aiflow
> Help me analyze this codebase and suggest improvements
```

### Next steps

- Learn how to [contribute to or build from the source](docs/CONTRIBUTING.md).
- Explore the available **[CLI Commands](./docs/cli/commands.md)**.
- If you encounter any issues, review the **[Troubleshooting guide](./docs/troubleshooting.md)**.
- For more comprehensive documentation, see the [full documentation](./docs/index.md).
- Take a look at some [popular tasks](#popular-tasks) for more inspiration.

### Troubleshooting

Head over to the [troubleshooting](docs/troubleshooting.md) guide if you're
having issues.

## 💰 Cost Management Features

AiFlow CLI includes comprehensive cost tracking and optimization tools to help you manage AI expenses:

### Real-time Cost Tracking

- Monitor costs per request, session, and total usage
- Track token usage (input/output) for all AI models
- Visual cost indicators and budget warnings

### Cost Management Commands

```bash
# View current cost status
aiflow cost status

# Compare costs between models
aiflow cost compare gemini-1.5-flash gpt-4o-mini deepseek-chat

# Get model recommendations for your use case
aiflow cost recommend --scenario coding

# Calculate costs for specific usage
aiflow cost calc gemini-1.5-flash

# Export cost data for analysis
aiflow cost export --format csv
```

### Supported Models & Providers

- **Google**: Gemini 2.0 Pro, Gemini 1.5 Pro/Flash
- **OpenAI**: GPT-4o, GPT-4o Mini, GPT-3.5 Turbo
- **Anthropic**: Claude 3.5 Sonnet, Claude 3 Opus/Haiku
- **DeepSeek**: DeepSeek V3, DeepSeek Chat/Coder
- **Others**: Qwen, ChatGLM, and more

### Smart Cost Optimization

- Automatic model selection based on cost-performance ratio
- Budget alerts at 80% and 100% thresholds
- Historical cost analysis and trends
- Export data for expense reporting

## 🌐 Proxy Configuration

**Important Change (v1.2.181+):** AiFlow CLI has updated its proxy handling for better flexibility and performance.

### Default Behavior
- AiFlow now runs **without proxy by default**
- This improves startup speed and reduces connection issues
- Direct internet access is used for AI API calls

### When You Need Proxy
If you're behind a corporate firewall or need proxy access:

```bash
# Method 1: Use built-in proxy command
prox aiflow

# Method 2: Set custom proxy and use prox command
export AIFLOW_PROXY=http://your-proxy-server:8080
prox aiflow

# Method 3: One-time custom proxy usage
AIFLOW_PROXY=http://corporate-proxy:3128 prox aiflow
```

### Proxy Commands

| Command | Description |
|---------|-------------|
| `aiflow` | Run without proxy (default) |
| `prox aiflow` | Run with proxy support |
| `AIFLOW_PROXY=<url> prox aiflow` | Run with custom proxy |

### Migration from Previous Versions

If you were using AiFlow v1.2.180 or earlier:
- **Before:** AiFlow automatically used proxy settings
- **Now:** Use `prox aiflow` when proxy is needed
- **Benefit:** Faster startup and more reliable connections when proxy isn't required

## Session Management

AiFlow CLI automatically saves your conversation history to `.aiflow/session.json` in your project directory. This allows you to:

- **Continue conversations:** When you restart AiFlow in the same directory, your previous conversation is automatically restored
- **Clear history:** Use the `/clear` command to completely reset your session, including deleting saved conversation files
- **Privacy:** Session files are stored locally in your project directory and are not shared

**Note:** The `.aiflow` directory should be added to your `.gitignore` to avoid committing conversation history to version control.

## 🔗 MCP (Model Context Protocol) Support

AiFlow CLI features **fully restored MCP support**, enabling powerful integrations with external tools and services through the Model Context Protocol. MCP allows AiFlow to extend its capabilities by connecting to various servers and tools.

### MCP Configuration Management

AiFlow provides comprehensive MCP configuration management through built-in commands:

```bash
# Edit user-level MCP configuration (opens in external editor)
/mcp edit user

# Edit workspace-level MCP configuration
/mcp edit workspace

# Display current MCP configuration information
/mcp info

# View MCP configuration template and examples
/mcp template

# Validate MCP configuration files
/mcp validate
```

### Configuration File Locations

MCP configuration files are stored in the following locations:

- **User-level config**: `~/.aiflow/mcp-config.json` - Global settings applied to all projects
- **Workspace-level config**: `./.aiflow/mcp-config.json` - Project-specific settings that override user-level config
- **Configuration templates**: Available through `/mcp template` command

### MCP Features

- **Server Integration**: Connect to MCP-compatible servers for extended functionality
- **Tool Access**: Access external tools and APIs through MCP protocol
- **Configuration Layering**: User and workspace-level configuration with proper precedence
- **Validation**: Built-in configuration validation to ensure proper setup
- **Template Support**: Easy setup with configuration templates

### Getting Started with MCP

1. **View available templates**: `/mcp template`
2. **Create initial configuration**: `/mcp edit user` or `/mcp edit workspace`
3. **Validate your setup**: `/mcp validate`
4. **Check configuration status**: `/mcp info`

MCP integration allows AiFlow to seamlessly work with external systems, databases, APIs, and tools, significantly expanding its capabilities beyond basic AI interactions.

## 🤖 AI Agent System

AiFlow CLI features a powerful Agent system with 13 specialized AI assistants:

### Available Agents

- **🏗️ Architect** - System architecture design and technical decisions
- **📱 Product Manager** - Product requirements and user experience
- **🔐 Security Expert** - Security analysis and vulnerability detection
- **🚀 DevOps Engineer** - Deployment, CI/CD, and infrastructure
- **📚 Documentation Expert** - Technical documentation and knowledge management
- **⚡ Performance Optimizer** - Performance analysis and optimization
- **📘 TypeScript Expert** - Type safety and code quality
- **🤖 AI Model Expert** - Multi-AI provider integration and routing
- **💰 Cost Analyst** - AI cost tracking and optimization
- **🎨 React Ink Expert** - Terminal UI components and themes
- **🧪 Test Engineer** - Testing strategies and quality assurance
- **👁️ Code Reviewer** - Code quality and best practices
- **💚 Node.js Expert** - CLI tools and Monorepo architecture

### Using Agents

```bash
# List all available agents
/agents list

# Get agent details
/agents info architect-agent

# Search for agents
/agents search security

# Smart agent recommendation
/smart-agent Help me design a microservice architecture
```

Learn more in the [Agent System Documentation](./docs/agents/README.md).

## Popular tasks

### Explore a new codebase

Start by `cd`ing into an existing or newly-cloned repository and running `aiflow`.

```text
> Describe the main pieces of this system's architecture.
```

```text
> What security mechanisms are in place?
```

### Work with your existing code

```text
> Implement a first draft for GitHub issue #123.
```

```text
> Help me migrate this codebase to the latest version of Java. Start with a plan.
```

### Automate your workflows

With **restored MCP (Model Context Protocol) support**, use MCP servers to integrate your local system tools with your enterprise collaboration suite.

```text
> Make me a slide deck showing the git history from the last 7 days, grouped by feature and team member.
```

```text
> Make a full-screen web app for a wall display to show our most interacted-with GitHub issues.
```

### Interact with your system

```text
> Convert all the images in this directory to png, and rename them to use dates from the exif data.
```

```text
> Organise my PDF invoices by month of expenditure.
```

## 📞 Connect with DavidFon

- 🌐 Website: [davidfon.dev](https://davidfon.dev)
- 🐦 Twitter: [@DavidFon_AI](https://twitter.com/DavidFon_AI)
- 💼 LinkedIn: [DavidFon](https://linkedin.com/in/davidfon)
- 📧 Email: david@aiflow.dev
- 💻 CodeUp: [AiFlow](https://codeup.aliyun.com/619daf222873bc436ca52219/DavidFon/AiFlow)

## Terms of Service and Privacy Notice

For details on the terms of service and privacy notice applicable to your use of AiFlow CLI, see the [Terms of Service and Privacy Notice](./docs/tos-privacy.md).