MiniCode

MiniCode

---

简体中文 | Usage Guide | DeepWiki | Architecture | Contributing | Roadmap | License

MiniCode is a lightweight terminal coding assistant for local development workflows.

It provides Claude Code-like workflow and architectural ideas in a much smaller implementation, making it especially useful for learning, experimentation, and custom tooling.

Sponsor

Sidrune AI provides unified API access to mainstream AI models such as GPT and Claude, with multiple routes and transparent usage and pricing. Register through the exclusive MiniCode link below and get a $3 API credit (promo code SDRMINICODE is applied automatically):

Overview

MiniCode is built around a practical terminal-first agent loop:

• accept a user request
• inspect the workspace
• call tools when needed
• review file changes before writing
• return a final response in the same terminal session

The project is intentionally compact, so the control flow, tool model, and TUI behavior remain easy to understand and extend.

Core Authors

Summaries are based on the main repository and multi-language branch commit history. For the broader contributor list, please refer to the repository commit history.

Multi-language Versions

• TypeScript (this repo): MiniCode
• Rust version: MiniCode-rs
• Python version: MiniCode-Python
• Go version: MiniCode-go
• Java version: MiniCode4j

Product Showcase Page

• Open docs/index.html in a browser for a visual product overview.
• GitHub Pages (recommended): https://liumengxuan04.github.io/MiniCode/

Why MiniCode

MiniCode is a good fit if you want:

• a lightweight coding assistant instead of a large platform
• a terminal UI with tool calling, transcript, and command workflow
• a small codebase that is suitable for study and modification
• a reference implementation for Claude Code-like agent architecture

Core Capabilities

• Multi-step tool execution in a single turn, forming a model -> tool -> model loop.
• Up to 3 concurrent read-only sub-agents; the root agent owns all code changes and can wait for or close workers.
• An in-memory Todo plan shared across root-agent turns, updated with update_plan and viewed with /plan.
• A user-created in-memory Goal that continues across turns, with /goal pause, /goal resume, and explicit completion checks.
• One process-local Loop repeats a prompt with a fixed delay after each run, shares the Plan, and stays mutually exclusive with active Goals.
• Full-screen terminal UI with input history, transcript scrolling, slash command menu, and approval flows.
• Per-project session persistence with resume, rename, fork, and compact commands.
• Provider-usage-first context stats with tail estimates, auto-compact, context collapse, and snip compact.
• Built-in tools for files, search, editing, command execution, web fetch/search, and clarification prompts.
• Local skills discovered through SKILL.md, plus MCP tools/resources/prompts over stdio or remote HTTP.
• Review-before-write file edits with path and command permission checks.
• Oversized tool results are stored on disk and replaced in context with a short preview and file path.

Full command references, configuration examples, session details, and Skills/MCP usage have moved to the Usage Guide.

Installation

git clone https://github.com/LiuMengxuan04/MiniCode.git
cd MiniCode
npm install
npm run install-local

The installer asks for the model name, ANTHROPIC_BASE_URL, and ANTHROPIC_AUTH_TOKEN. Configuration is stored in:

• ~/.mini-code/settings.json
• ~/.mini-code/mcp.json

You can override the config directory with MINI_CODE_HOME and the launcher directory with MINI_CODE_BIN_DIR. See Installation Details for more.

Quick Start

Run the installed launcher:

minicode

Run in development mode:

npm run dev

Run in offline demo mode:

MINI_CODE_MODEL_MODE=mock npm run dev

Common Entry Points

• /help: show interactive help.
• /tools: list available tools.
• /plan: view the current in-memory Todo list.
• /goal <description>, /goal [status], /goal pause [reason], /goal resume, /goal clear: create, inspect and control a Goal.
• /loop [Nm|Nh] <prompt>, /loop, /loop stop: create, inspect and stop a recurring prompt (default 10m; minimum 1m).
• /skills: list discovered skills.
• /mcp: show MCP connection status.
• /status: show session and context status.
• /init: scaffold .mini-code/ and MINI.md for the current project.
• /memory: inspect the layered memory files loaded for the current turn.
• /model / /model <name>: inspect or switch the model.
• /resume: open the session picker.
• /compact: manually compact the context.

Management commands include minicode mcp ... and minicode skills .... See Commands for the full reference.

Documentation

• Usage Guide
• Architecture Overview
• 中文架构说明
• Contribution Guidelines
• 中文贡献规范
• Roadmap
• 路线图
• Learn Claude Code Design Through MiniCode

Star History

Development

npm run check
npm test

MiniCode is intentionally small and pragmatic. The goal is to keep the architecture understandable, hackable, and easy to extend.