mini-cc

<div align="center"> <img src="website/images/logo.svg" width="120" alt="mini-cc logo" /> <h1>mini-cc</h1> <p>A lightweight AI programming intelligent agent with a minimalist architecture, an open-source teaching project that dissects, learns, and replicates the architecture of large factory agents.</p> <p> <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"> <img src="https://img.shields.io/badge/typescript-5.x-blue" alt="TypeScript"> <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" alt="Node"> </p> </div> Due to trademark protection and compliance reasons, this project has been renamed to **mini-cc**. It aims to replicate the core interaction, tool call mechanism (Tool Use), sandbox execution, and memory compression strategy of the original Claude Code CLI with the simplest code. It supports multiple model providers (Anthropic, OpenAI, and all models compatible with the OpenAI interface, such as Qwen, DeepSeek, etc.), providing the ability to read files, write files, and execute Bash terminal commands. Through this project, you can learn about the core event loop of Agent, tool definition and distribution, adaptation of multiple models, and how to build a cool terminal React UI. ## 🌟 Core Features This project has implemented the following core features in the TypeScript version: - **Multi-model support**: Supports Anthropic API and OpenAI compatible interfaces, allowing free switching between Claude, DeepSeek, Qwen, Kimi, and other large models. - **Pure functional Agent loop**: Clearly shows how large models autonomously call tools, think (CoT), and feedback. Supports real-time display of reasoning processes ( `reasoning_content` ) for models like Qwen. - **Tool Use**: - `BashTool`: Execute system terminal commands (supporting npm, git, file operations, etc.). - `FileReadTool`: Read local files and provide context. - `FileWriteTool`: Overwrite and write local files to achieve automatic code modification. - **Secure Bash sandbox**: Implemented command execution wrapper stripping and high-risk destructive command (such as `rm -rf /` ) interception. - **.ai_memory memory engine**: Implements two-step rule context recording and long Token truncation mechanism to prevent Token explosion. - **MCP plugin integration**: Supports model context protocol to achieve seamless expansion of tools (e.g., secure execution of network requests and system operations). - **Cool terminal UI**: Built on React (Ink), with virtual scrolling and smooth streaming typewriter output effects. - **Fun Easter eggs**: Built-in `/buddy` companion system (based on Mulberry32 and anti-cheating algorithm) and `/voice` simulated voice intercom. ## 🛠️ Architecture Diagram ### Agent Loop and Tool Use The system uses `AgentTool` (Agent splitting) and stdio-based process isolation communication to send complex command execution to different sub-tools. The main control node continuously appends results to `messages`. Once it encounters `tool_calls`, it interrupts the current generation, enters asynchronous tool calls, and wakes up the generation after the result is produced, forming an automatic loop. ### .ai_memory Memory and Context Compression To prevent Token explosion, the program maintains a local file system memory: 1. **Compression layer (`compact.ts`)**: Automatically strip images and ultra-long documents. 2. **Blast prevention cabin (`truncateHeadForPTLRetry`)**: If the API reports `Prompt Too Long`, forcibly reduce the oldest history. 3. **Two-step rule**: Generate `.ai_memory` in the workspace to record core conventions and project architecture-level long-term memory. ### MCP (Model Context Protocol) Plugin Architecture Large model calls to tools will be transparently proxied through `MCPTool.ts` to remote or local MCP plugin services to achieve cross-process and cross-application secure isolation execution. ## 📚 Documentation Guide To help developers understand the project's architecture design and core implementation, we provide detailed documentation. You can find these contents in the [`docs`](./docs) directory: - [00. Project Outline](./docs/00-outline.md) - [01. Core Architecture](./docs/01-architecture.md) - [02. Query Engine](./docs/02-query-engine.md) - [03. Tool System](./docs/03-tool-system.md) - [04. Memory & Context](./docs/04-memory-and-context.md) - [05. MCP & Plugins](./docs/05-mcp-and-plugins.md) - [06. UI & Ink](./docs/06-ui-and-ink.md) - [07. Optimization & Deployment](./docs/07-optimization-and-deployment.md) - [08. Buddy Easter Egg](./docs/08-buddy-easter-egg.md) - [09. Security & Sandbox](./docs/09-security-and-sandbox.md) - [10. Ultimate Agent Capabilities](./docs/10-ultimate-agent-capabilities.md) ## 📁 Language Implementation Versions This project adopts a multi-language architecture, planning to use multiple programming languages to implement the same functionality. Currently included: - [TypeScript Implementation](./typescript) (✅ Completed) - *Python Implementation (⏳ Planned)* - *Go Implementation (⏳ Planned)* - *Rust Implementation (⏳ Planned)* ## 🚀 Quick Start (TypeScript Version) ### Method 1: Global Installation (Recommended) ```bash npm install -g mini-cc mini-cc ``` ### Method 2: Source Code Build & Bun Binary Packaging If you want to modify the code yourself or package it into a single binary file that can run without a Node environment: ```bash git clone https://github.com/your-username/mini-cc.git cd mini-cc/typescript npm install npm run build # Run npm start # Or build a standalone binary executable file (requires Bun installation) bun build --compile src/main.ts --outfile mini-cc ``` ### Configure API Key When running `mini-cc` for the first time, if no API Key is detected, the program will automatically pop up an interactive configuration guide to help you set it up and save it in the global directory `~/.mini-cc/config.json`. ```text ⚠️ No OpenAI compatible interface API Key detected. ? Welcome! Please paste your OPENAI_API_KEY: ********** ? Please enter the model name you want to use (default: qwen3.6-plus): qwen3.6-plus ? If you are using a compatible interface, please enter BASE_URL (optional): https://dashscope.aliyuncs.com/compatible-mode/v1 ✓ Configuration saved to global directory (~/.mini-cc/config.json) ``` You can also configure manually through the command line: ```bash mini-cc config set OPENAI_API_KEY sk-xxxxx mini-cc config set MODEL_NAME qwen-max ``` ## 💻 Interaction Example After starting the program, you can directly input natural language instructions in the terminal. For example: - "Help me create a hello.js file with the content 'Hello World'." - "List the files in the current directory?" - "Read package.json and tell me what the project name is." The program will think and call the corresponding tools to automatically execute your requirements and finally feedback the results to you. ## 🎮 Fun Instructions Enter the following instructions in the chat input box to trigger Easter eggs: - `/clear`: Clear the current session context. - `/buddy`: Summon a digital companion generated based on the system seed (little yellow duck/little octopus), with hidden rarity attributes. - `/voice`: Enter simulated voice intercom mode (press and hold the space bar to speak). ## 🛡️ Advanced Architecture Demonstration (Mocks) Some capabilities that are extremely underlying in the official version (such as cross-platform screenshot, taking over Chrome browser extension to grab AppData data, based on CCR cloud cluster deduction) are demonstrated as **architecture exercises** in `src/architecture-mocks`, and do not contain entity functions (see the directory statement for details). ## 📄 Open Source License This project is open-sourced under the [MIT License](./LICENSE), welcoming free learning, modification, and distribution.