An educational AI coding assistant project that helps you understand and hack modern AI coding assistant systems.
Mini-Kode is an educational project designed to help developers understand modern Coding Agent architecture. We strike the perfect balance between overly complex open-source projects and simplistic demo examples, offering a complete yet manageable implementation (14K lines of production code) with:
- 📚 Education-First Design - Clean architecture built on OpenAI SDK with thoughtful type design and comprehensive comments
- 🛠️ Complete Tool System - Unified interface with comprehensive tools for file operations, search, and command execution
- 🔌 MCP Integration - Connect to external MCP servers for extended functionality
- ⚙️ Multi-LLM Support - Compatible with OpenAI APIs, including GLM, DeepSeek, and other mainstream models
- 🤖 Agent Loop - Complete LLM workflow with streaming responses and human-in-the-loop permission approval
- 🎨 Modern UI - React/Ink-based terminal interface with theme support
npm install -g mini-kodeDeepSeek (tested and verified):
export DEEPSEEK_API_KEY="your-deepseek-api-key"Or use GLM (智谱AI) (tested and verified):
export GLM_API_KEY="your-glm-api-key"Or use OpenAI compatible API:
export OPENAI_API_KEY="your-openai-api-key"
# or
MINIKODE_API_KEY="your-api-key"
MINIKODE_BASE_URL="https://your-api-provider.com/v1"
MINIKODE_MODEL="your-model-name"# Interactive mode (launch UI)
mini-kode
# Non-interactive mode (direct execution)
mini-kode "help me fix the bug in auth.ts"- Bun
- pnpm
pnpm install# Development mode with file watching
pnpm run dev
# Build
pnpm run build
# Test
pnpm run testWant to dive deeper into the system architecture? Check out docs/README.md for complete system documentation and architecture explanations.
For a comprehensive code analysis and walkthrough, visit Mini-Kode Deep Analysis - an in-depth exploration of the codebase architecture, design patterns, and implementation details.
Mini-Kode automatically uses AGENTS.md file in your project root to provide context-aware assistance:
- Automatic Context: System reads
AGENTS.mdto understand your project - Customizable: Edit
AGENTS.mdto include project-specific information - Persistent Memory: Maintains project context across sessions
src/
├── tools/ # Tool system and individual tools
├── ui/ # Ink-based CLI interface components
├── llm/ # LLM client and streaming integration
├── permissions/ # Two-layer permission system
├── config/ # Configuration management
├── cli/ # CLI framework and commands
├── agent/ # Core agent logic
├── sessions/ # Session management
└── utils/ # Shared utilities
- TypeScript - Static type checking
- pnpm - Package management
- Ink - React terminal UI
- OpenAI SDK - LLM integration (supports DeepSeek/OpenAI/compatible APIs)
- Vitest - Testing framework
- Zod - Runtime type validation
- Commander - CLI framework
- Session Persistence and Resume - Save and restore agent sessions
- LLM Built-in Tool Integration - Support for LLM's native tool capabilities (note: DeepSeek currently doesn't support web search tools)
- Image Input Support - Process and analyze image inputs
- Sub Agents Functionality - Hierarchical agent delegation
- Reasoning Model Support - Integration with reasoning-focused models
- Tool Call Message Streaming - Real-time streaming of tool execution
- Context Caching - Smart caching of conversation context to reduce token usage
This project was inspired by and references the following resources:
- Building an Agent - Guide on building AI agents
- Building an Agentic System - Comprehensive guide to building agentic systems
- System and Tool Prompts - System prompts and tool prompts for coding agent
- Neovate Code - Todo tool prompt
- Claude Code - UX reference for CLI interface design