# MiniCode

**Repository Path**: naka507/MiniCode

## Basic Information

- **Project Name**: MiniCode
- **Description**: 基于事件驱动支持多个提供商 的AI 编程助手
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 1
- **Created**: 2025-10-24
- **Last Updated**: 2026-01-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MiniCode

<div align="center">

**An Event-Driven Multi-Provider AI Programming Assistant**

[![Node Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
[![License](https://img.shields.io/badge/license-ISC-blue.svg)](LICENSE)

English | [中文文档](./README.md)

</div>

---

## Introduction

MiniCode is an advanced AI programming assistant built with **event-driven architecture** and **pluggable capability system**. It supports multiple mainstream AI providers (Anthropic Claude, Google Gemini) and provides powerful code assistance through a unified interface.

## Core Features

### 🎯 Multi-Provider Support
- **Anthropic Claude**: Claude 4.5 Sonnet, Claude 4 Opus, etc.
- **Google Gemini**: Gemini 2.5 Flash, Gemini 2.5 Pro, etc.
- **Easy Switching**: Switch between providers via configuration

### 🏗️ Advanced Architecture
- **Event-Driven**: Complete decoupling of UI and Provider layers via EventBus
- **Pluggable Capabilities**: Modular capability management (Caching, Warmup, Thinking, Streaming)
- **Adapter Pattern**: Unified API differences across providers
- **Tool Registry**: Centralized tool management and execution

### 🛠️ Rich Tool Set

#### File Operations
- **Read**: Read file contents with line numbers and pagination
- **Write**: Create or overwrite files
- **Edit**: Precise file content editing
- **Glob**: Pattern matching file search
- **Grep**: Content search with regex support

#### System Tools
- **Bash**: Execute shell commands (with safety checks)
- **TodoWrite**: Task management and tracking

#### Advanced Tools
- **Task**: Launch specialized sub-agents for complex tasks
  - **General**: General-purpose agent with all tools available
  - **Explore**: Codebase exploration expert (Glob, Grep, Read, Bash)
  - **Plan**: Planning and analysis expert (Glob, Grep, Read, Bash)

#### Tool Categories
Tools are organized into four main categories:
- **readonly**: Read-only operations (Read, Glob, Grep)
- **writeops**: Write operations (Write, Edit)
- **bash**: Command execution (Bash)
- **task**: Task management (TodoWrite, Task)

### 🔒 Tool Execution Approval

For safety, MiniCode implements an intelligent tool execution approval system:

**Approval Strategy**:
- **Read-only tools** (Read, Glob, Grep): No approval required
- **Write tools** (Write, Edit): Approval required on first use
- **Command tools** (Bash): Approval required on first use
- **Task tools** (TodoWrite, Task): No approval required

**Approval Options**:
- **y (yes)**: Approve this execution
- **n (no)**: Reject this execution
- **a (always)**: Approve and auto-approve all future operations in this category

**Configuration**:
```bash
# Completely disable approval in .env file
REQUIRE_TOOL_APPROVAL=false
```

**Smart Caching**:
- After selecting "always approve", tools in that category no longer require approval
- Persistent during session, improving workflow efficiency

### 🧠 Intelligent Task Scheduling
- **Task Classifier**: Auto-detect task types (SEARCH, READ, CODE, REVIEW, DEBUG, TEST, GENERAL)
- **Complexity Assessment**: Evaluate complexity (SIMPLE, MODERATE, COMPLEX)
- **Model Scheduler**: Smart model selection based on task characteristics
- **Cost Optimization**: Use lightweight models for simple tasks, powerful models for complex ones

## Project Highlights ⭐

### 1. Zero-Intrusion Event-Driven Architecture
- UI and Provider layers are **completely decoupled** via EventBus
- No UI dependencies in business code
- Support multiple UI layers listening simultaneously

### 2. Intelligent Cost Optimization
```javascript
// Simple queries automatically use fast, low-cost models
"View README.md file" → Gemini 2.5 Flash

// Complex tasks automatically upgrade to powerful models
"Refactor entire cache system and optimize performance" → Gemini 2.5 Pro
```
- Auto-analyze task complexity and select optimal model
- **80%+ cost reduction** for simple tasks
- Support custom scheduling strategies

### 3. High-Performance Caching
- **Prompt Caching**: Auto-cache system prompts
- **Warmup**: Enjoy cache benefits from first request
- **Cost Savings**: 90% input token savings on cache hits

### 4. Pluggable Capability System
Each provider can independently configure four core capabilities:
- **Caching** - Smart cache management
- **Warmup** - Preload optimization
- **Thinking** - Deep thinking mode (Gemini exclusive)
- **Streaming** - Real-time output

### 5. Task Tool: Sub-Agent System
The Task tool allows the main AI to launch specialized sub-agents for complex tasks, achieving **divide and conquer**:

**How It Works**:
```
User Request → Main AI → Call Task Tool → Launch Sub-Agent → Execute → Return Report → Main AI Integrates
```

**Use Cases**:
- Complex codebase exploration
- Multi-step file searches
- Tasks requiring multiple iterations

**Example**:
```javascript
// AI automatically uses Task tool
User: "Find all API endpoint definitions in the project"

AI thinks: This requires multiple searches, Explore agent is more efficient

AI calls: Task({
  subagent_type: "Explore",
  prompt: "Search all API route definitions, including Express, Koa frameworks..."
})

Explore agent executes:
  → Use Glob to search route files
  → Use Grep to find route definitions
  → Use Read to verify content
  → Return complete API list

AI integrates: Present all API endpoints to user based on Explore's report
```

**Advantages**:
- **Focus**: Sub-agents focus on specific tasks
- **Tool Isolation**: Different agents have different tool access
- **Parallel Execution**: Support launching multiple sub-agents simultaneously
- **Cost Control**: Sub-agents can use cheaper models

### 6. Unified Tool Interface
```javascript
// Same tool code, seamlessly supports multiple AI providers
const tools = [Read, Write, Edit, Glob, Grep, Bash, TodoWrite, Task];
// Auto-adapts to Anthropic, Gemini, OpenAI API formats
```

### 7. Complete Observability
- Real-time task classification and scheduling decisions
- Tool execution visualization
- Tool approval interaction prompts
- Token usage statistics and cost tracking
- View detailed stats via `/stats` command

## Architecture 🏗️

### Architecture Diagram

```
┌─────────────────────────────────────────────────────────────────┐
│                          MiniCode                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────────┐        EventBus         ┌──────────────┐      │
│  │              │◄────────────────────────┤              │      │
│  │  UI Layer    │   Events (async)        │   Provider   │      │
│  │  (UIManager) │                         │    Layer     │      │
│  │              ├────────────────────────►│              │      │
│  └──────┬───────┘                         └──────┬───────┘      │
│         │                                        │              │
│         │ Display                         ┌──────▼───────┐      │
│         │                                 │   Adapter    │      │
│         │                                 │ (API Format) │      │
│         │                                 └──────┬───────┘      │
│         │                                        │              │
│  ┌──────▼────────┐                       ┌──────▼───────┐       │
│  │ Approval      │                       │  Capability  │       │
│  │ System        │                       │   System     │       │
│  │               │                       │ ┌──────────┐ │       │
│  └───────────────┘                       │ │ Caching  │ │       │
│                                          │ │ Warmup   │ │       │
│  ┌──────────────┐                       │ │ Thinking │ │       │
│  │ Task         │                       │ │Streaming │ │       │
│  │ Classifier   │                       │ └──────────┘ │       │
│  │ + Model      │                       └──────────────┘       │
│  │ Scheduler    │                                              │
│  └──────────────┘                       ┌──────────────┐       │
│                                         │   Agent      │       │
│  ┌──────────────┐                       │ (Sub-agent)  │       │
│  │ Tool         │                       └──────┬───────┘       │
│  │ Registry     │                              │               │
│  │              │                       ┌──────▼───────┐        │
│  │ - Read       │◄──────────────────────┤  API Client  │        │
│  │ - Write      │   Tool Execution      │ (HTTP Layer) │        │
│  │ - Edit       │                       └──────────────┘        │
│  │ - Glob       │                                               │
│  │ - Grep       │                                               │
│  │ - Bash       │                                               │
│  │ - TodoWrite  │                                               │
│  │ - Task       │                                               │
│  └──────────────┘                                               │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### Core Modules

**1. EventBus (Event Bus)**
```javascript
// Publish events
EventBus.toolStart('Read', { file: 'test.js' });
EventBus.streamDelta('Hello', 'text');
EventBus.generateComplete('Gemini', message, usage);

// Subscribe to events
EventBus.on('tool:start', (data) => { /* handle */ });
```
- Singleton pattern
- Support 20+ event types
- Promise-style `waitFor()` method
- Async request/response mechanism for tool approval

**2. Provider Layer**
```
BaseProvider (abstract base class)
    ├── AnthropicProvider
    │   ├── AnthropicClient (HTTP)
    │   ├── AnthropicAdapter (format conversion)
    │   ├── Capabilities: Caching, Warmup, Streaming
    │   └── Tools: custom cache_control
    │
    └── GeminiProvider
        ├── GeminiClient (HTTP)
        ├── GeminiAdapter (format conversion)
        ├── Capabilities: Caching, Thinking, Streaming
        └── Tools: maxToolsPerRequest limit
```

**3. Agent (Sub-Agent Manager)**
```javascript
// Manage Task tool's sub-agent execution
agent.initialize(provider, toolRegistry);

// Filter tools by agent type
agent.getToolsForAgentType('Explore'); // ['Glob', 'Grep', 'Read', 'Bash']

// Execute sub-agent task
await agent.execute(description, prompt, agentType, model);
```

**4. Tool Registry**
```javascript
// Auto-register all tools
toolRegistry.initialize();

// Get by category
toolRegistry.getToolsByCategory('readonly'); // [Read, Glob, Grep]
toolRegistry.getToolsByCategory('writeops'); // [Write, Edit]

// Execute tool (with approval)
const result = await toolRegistry.execute('Read', { file_path: '/path/to/file' });
```

**5. Approval System**
```javascript
// Check if approval is required
if (toolRegistry._requiresApproval(tool)) {
  // Request user approval
  const result = await EventBus.requestApproval(name, category, input);

  // Handle user response
  if (result.approved) {
    if (result.autoApproveCategory) {
      // Cache auto-approved category
      autoApprovedCategories.add(category);
    }
  }
}
```

**6. Task Classifier + Model Scheduler**
```javascript
// Task classification
const task = classifier.classify("optimize cache system");
// → { type: 'CODE', complexity: 'COMPLEX', confidence: 0.85 }

// Model scheduling
const schedule = scheduler.analyze(task);
// → { model: 'gemini-2.5-pro', tools: null, reason: 'complex code task' }
```

## Quick Start

### 1. Requirements

- Node.js >= 18.0.0
- npm or yarn

### 2. Installation

**Option 1: Global installation via npm (Recommended)**

```bash
npm install -g minicode
```

Then use the `minicode` command directly:

```bash
minicode
```

**Option 2: Run from source**

```bash
# Clone repository
git clone https://gitee.com/naka507/MiniCode.git
cd MiniCode

# Install dependencies
npm install

# Run
node src/main.js
```

### 3. Configure API Key

Create `.env` file (refer to `.env.example`):

**Using Anthropic Claude:**
```bash
PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-xxx
```

**Using Google Gemini:**
```bash
PROVIDER=gemini
GEMINI_API_KEY=your_gemini_api_key
```

### 4. Run

**If globally installed:**
```bash
minicode
```

**If running from source:**
```bash
node src/main.js
```

## Configuration Options

### Basic Configuration

| Variable | Description | Default | Example |
|----------|-------------|---------|---------|
| `PROVIDER` | AI provider | gemini | anthropic / gemini |
| `MODEL` | Model name | Auto-selected | claude-sonnet-4.5 / gemini-2.5-flash |
| `MAX_TOKENS` | Max output tokens | 4096 | 8192 |

### API Configuration

| Variable | Description | Required |
|----------|-------------|----------|
| `ANTHROPIC_API_KEY` | Anthropic API key | When using Anthropic |
| `ANTHROPIC_BASE_URL` | Anthropic API URL | No (default official) |
| `GEMINI_API_KEY` | Gemini API key | When using Gemini |
| `GEMINI_BASE_URL` | Gemini API URL | No (default official) |

### Feature Flags

| Variable | Description | Default |
|----------|-------------|---------|
| `ENABLE_CACHE` | Enable prompt caching | true |
| `ENABLE_WARMUP` | Enable warmup optimization | true |
| `ENABLE_THINKING` | Enable thinking mode | true |
| `ENABLE_STREAMING` | Enable streaming output | true |
| `ENABLE_MODEL_SCHEDULING` | Enable smart model scheduling | true |
| `REQUIRE_TOOL_APPROVAL` | Enable tool execution approval | true |

### Model Scheduling

| Variable | Description | Example |
|----------|-------------|---------|
| `FAST_MODEL` | Fast model (simple tasks) | gemini-2.5-flash |
| `POWERFUL_MODEL` | Powerful model (complex tasks) | gemini-2.5-pro |
| `THINKING_BUDGET` | Thinking budget (Gemini only) | -1 (unlimited) |

### Debug Configuration

| Variable | Description | Default |
|----------|-------------|---------|
| `VERBOSE` | Verbose logging | false |
| `DEBUG` | Debug mode | false |

## Commands

| Command | Function | Description |
|---------|----------|-------------|
| `/help` | Show help | View all available commands |
| `/stats` | Show statistics | View token usage, tool execution stats |
| `/clear` | Clear screen | Clear terminal display |
| `/exit` or `/quit` | Exit program | Save session and exit |

### Usage Examples

```bash
# Start program
$ node src/main.js

# View file content
> Read the first 50 lines of src/main.js

# Write code
> Create a utility function for date formatting

# Complex task (AI will automatically use Task tool)
> Find all places using caching in the project and analyze the caching strategy

# View statistics
> /stats

# Exit
> /exit
```

### Tool Approval Interaction Example

```bash
# When AI attempts to execute a write operation
Tool Execution Requires Approval
Tool: Write (writeops)
Input:
  file_path: /path/to/file.js
  content: ...

Approve execution? (y/n/a)
  y = yes (this time)
  n = no (cancel)
  a = always (auto-approve writeops)
> a

✓ Auto-approval enabled for category: writeops
# Future Write/Edit operations will be auto-approved
```

## License

ISC License

---

<div align="center">

**Made with ❤️ by MiniCode Team**

[GitHub](https://gitee.com/naka507/MiniCode) | [English](./README_EN.md) | [中文文档](./README.md)

</div>