MiniCode

中文 | English

A lightweight CLI Agent implementation, perfect for learning Agent development as an educational project.

Features

• 🤖 Intelligent Conversation - LLM-based dialogue capabilities (supports multiple models)
• 🔧 Tool Calling - Supports bash command execution and file reading
• 📺 Streaming Output - Real-time display of thinking process
• 🎨 Colorful Terminal - User-friendly interface design
• 📚 Education-Friendly - Clean code, clear structure, ~300 lines

Installation

One-Command Install

Linux / macOS:

curl -fsSL https://raw.githubusercontent.com/fak111/minicode/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/fak111/minicode/main/install.ps1 | iex

After installation:

Linux / macOS:

1. Set your API Key:

   export OPENAI_API_KEY="your-api-key-here"

2. Add ~/.local/bin to your PATH (if not already added):

   export PATH="$HOME/.local/bin:$PATH"
   # Add this line to ~/.bashrc or ~/.zshrc for persistence

3. Run MiniCode:

   minicode

Windows:

1. Add %USERPROFILE%\AppData\Local\bin to your system PATH environment variable
2. Set your API Key:

   $env:OPENAI_API_KEY="your-api-key-here"

3. Restart your terminal and run:

   minicode

The installation script will:

• Check and install Bun if needed
• Clone the repository to ~/.minicode (Linux/macOS) or %USERPROFILE%\.minicode (Windows)
• Install dependencies
• Create a global minicode command

Quick Start

1. Install Dependencies

cd minicode
bun install

2. Configure API Key

cp .env.example .env
# Edit .env file and add your API Key

Or set environment variables directly:

export OPENAI_API_KEY="your_api_key_here"

3. Run

One-shot Mode (Single Execution):

bun run dev "read package.json"
bun run dev "List files and tell me about the project"

REPL Mode (Interactive Conversation):

bun run dev

Then enter your questions:

➜ What does this project do?

Project Structure

minicode/
├── package.json         # Project configuration
├── tsconfig.json        # TypeScript configuration
├── .env.example         # Environment variables example
├── README.md            # This file
└── src/
    ├── config.ts        # Configuration management
    ├── tools.ts         # Tool definitions
    ├── session.ts       # Session management + ReAct loop
    └── cli.ts           # CLI entry point

Code Architecture

cli.ts → NanoSession.chat() → OpenAI API (streaming)
         ↓
       Tool calls → runTool() → bash / read_file
         ↓
       Results → Return to LLM for continued thinking

Core Files

File	Lines	Responsibility
config.ts	~60	Config loading, type definitions, System Prompt
tools.ts	~70	Tool definitions, tool execution, output truncation
session.ts	~80	ReAct loop, streaming output processing
cli.ts	~55	REPL loop, user interaction

How It Works

MiniCode uses the ReAct Pattern (Reasoning + Acting):

1. Think: User input → LLM analysis
2. Act: LLM decides to call tools → Execute tools
3. Observe: Tool results → Return to LLM
4. Repeat: LLM continues thinking or responds based on results

Educational Highlights

This project demonstrates:

1. Environment Variable Configuration - Reading from process.env in config.ts
2. Tool Definitions - JSON Schema definitions in tools.ts
3. ReAct Loop - while loop in session.ts
4. Streaming Output - for await...of iteration in session.ts
5. REPL Implementation - readline/promises in cli.ts

Extension Suggestions

Steps to add new tools:

1. Add definition to the TOOLS array in tools.ts
2. Add execution logic to the runTool() function
3. Document the new tool in SYSTEM_PROMPT in config.ts

Environment Variables

Variable	Required	Default	Description
OPENAI_API_KEY	Yes	-	API Key
OPENAI_BASE_URL	No	https://api.deepseek.com	API Base URL
OPENAI_MODEL	No	deepseek-chat	Model name
WORKDIR	No	Current directory	Working directory

Supported Models

MiniCode supports any OpenAI API-compatible models, such as:

• deepseek-chat - DeepSeek chat model (default)
• deepseek-coder - DeepSeek code model
• gpt-4-turbo - OpenAI GPT-4 Turbo
• gpt-3.5-turbo - OpenAI GPT-3.5 Turbo
• qwen-turbo - Qwen model
• Other OpenAI API-compatible models

Usage Examples:

# Use GPT-4 Turbo
export OPENAI_MODEL="gpt-4-turbo"
export OPENAI_BASE_URL="https://api.openai.com/v1"

# Use DeepSeek Coder
export OPENAI_MODEL="deepseek-coder"
export OPENAI_BASE_URL="https://api.deepseek.com"

# Use Qwen
export OPENAI_MODEL="qwen-turbo"
export OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"

Dependencies

• Bun - Runtime
• OpenAI SDK - LLM interface
• picocolors - Colored output

Acknowledgments

This project is partially inspired by the open-source AI Coding Agent project OpenCode.

License

MIT