MiniCode

<p align="center"> <img src="./docs/logo.svg" alt="MiniCode Logo" width="180" /> </p> <h2 align="center">MiniCode</h2> <p align="center"> <img src="https://img.shields.io/badge/Editor-Minicode-D97757?style=for-the-badge" alt="Editor: Minicode" /> <img src="https://img.shields.io/badge/%23minicode-Project-B85C3F?style=for-the-badge" alt="#minicode" /> <img src="https://img.shields.io/badge/%23lightweight-Focus-F0EBE1?style=for-the-badge&labelColor=8B8B8B" alt="#lightweight" /> </p>

<p align="center"> A lightweight, highly efficient coding tool. Designed for speed, built for simplicity. </p>

A lightweight terminal coding assistant for local development workflows.

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

You can also explore this project through DeepWiki.

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.

Multi-language Versions

TypeScript (this repo): MiniCode
Rust version: MiniCode-rs (latest)
Python version: MiniCode-Python

Branch Highlights

TypeScript version: the reference implementation for MiniCode's core workflow, documentation, and product showcase. More branch-specific features are still being shaped.
Rust version: keeps conversation history inside the working directory, making it easier to move or migrate a project without losing its local MiniCode context.
Python version: a Python-native implementation branch. More branch-specific features are still being shaped.

Product Showcase Page
Why MiniCode
Features
Installation
Quick Start
Commands
Configuration
Skills and MCP Usage
Star History
Project Structure
Architecture Docs
Contributing
Roadmap
Learn Claude Code Design Through MiniCode
Development

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

Features

Core workflow

multi-step tool execution in a single turn
model -> tool -> model loop
full-screen terminal interface
input history, transcript scrolling, and slash command menu
discoverable local skills via SKILL.md
dynamic MCP tool loading over stdio
MCP resources and prompts via generic MCP helper tools

Built-in tools

list_files
grep_files
read_file
write_file
edit_file
patch_file
modify_file
run_command
web_fetch
web_search
ask_user
load_skill
list_mcp_resources
read_mcp_resource
list_mcp_prompts
get_mcp_prompt

Safety and usability

review-before-write flow for file modifications
path and command permission checks
local installer with independent config storage
support for Anthropic-style API endpoints

Recent interaction upgrades

approval prompts now use Up/Down selection with Enter confirm
approval prompts also support direct letter/number shortcuts shown in each option
supports "reject with guidance" to send corrective instructions back to the model
edit approvals support "allow this file for this turn" and "allow all edits for this turn"
file review now uses standard unified diff output (closer to git diff)
approval view supports Ctrl+O expand/collapse plus wheel/page scrolling
Ctrl+C now exits cleanly even when an approval prompt is open
finished tool calls auto-collapse into concise summaries to reduce transcript noise
explicit background shell commands launched through run_command are now surfaced as lightweight shell tasks instead of remaining stuck as a forever-running tool call
TTY input handling is serialized, and CRLF Enter sequences are normalized so approval confirms do not accidentally fire twice
fixed an input-event deadlock where approval prompts could stop accepting Up/Down/Enter
escape-sequence parsing is hardened so malformed terminal input does not stall key handling
run_command now accepts single-string invocations like "git status" and auto-splits args
clarifying questions are now structured via ask_user, and the turn pauses until the user replies

Installation

cd mini-code
npm install
npm run install-local

The installer will ask for:

model name
ANTHROPIC_BASE_URL
ANTHROPIC_AUTH_TOKEN

Configuration is stored in:

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

The launcher is installed to:

~/.local/bin/minicode

If ~/.local/bin is not already on your PATH, add:

export PATH="$HOME/.local/bin:$PATH"

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

Commands

Management commands

minicode mcp list
minicode mcp add <name> [--project] [--protocol <mode>] [--url <endpoint>] [--header KEY=VALUE ...] [--env KEY=VALUE ...] [-- <command> [args...]]
minicode mcp login <name> --token <bearer-token>
minicode mcp logout <name>
minicode mcp remove <name> [--project]
minicode skills list
minicode skills add <path> [--name <name>] [--project]
minicode skills remove <name> [--project]

Local slash commands

/help
/tools
/skills
/mcp
/status
/model
/model <name>
/config-paths

Terminal interaction

command suggestions and slash menu
transcript scrolling
prompt editing
input history navigation
approval selection and feedback input flow (Up/Down + Enter, or key shortcuts)

Configuration

Example configuration:

{
  "model": "your-model-name",
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    },
    "remote-example": {
      "protocol": "streamable-http",
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  },
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com",
    "ANTHROPIC_AUTH_TOKEN": "your-token",
    "ANTHROPIC_MODEL": "your-model-name"
  }
}

Project-scoped MCP config is also supported through Claude Code compatible .mcp.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    }
  }
}

For vendor compatibility, MiniCode now auto-negotiates stdio framing:

standard MCP Content-Length framing is tried first
if that fails, MiniCode falls back to newline-delimited JSON
you can force a mode per server with "protocol": "content-length" or "protocol": "newline-json"
for remote MCP over HTTP, use "protocol": "streamable-http" with "url" (and optional "headers")
header values support environment interpolation, e.g. "Authorization": "Bearer $MCP_TOKEN"

Remote MCP authentication strategy (lightweight by design):

use minicode mcp login <name> --token <bearer-token> to store a bearer token locally
use minicode mcp logout <name> to clear a stored token
for now, MiniCode intentionally uses this token-based path instead of a full built-in OAuth callback + refresh state machine
this keeps the implementation small and aligned with MiniCode's lightweight architecture goals; full OAuth automation may be added later when needed

Skills are discovered from:

./.mini-code/skills/<skill-name>/SKILL.md
~/.mini-code/skills/<skill-name>/SKILL.md
./.claude/skills/<skill-name>/SKILL.md
~/.claude/skills/<skill-name>/SKILL.md

Configuration priority:

~/.mini-code/settings.json
~/.mini-code/mcp.json
project .mcp.json
compatible existing local settings
process environment variables

Skills and MCP Usage

MiniCode supports two extension layers:

skills: local workflow instructions, usually described by a SKILL.md
MCP: external tool providers that expose tools, resources, and prompts into MiniCode

Skills: install, inspect, trigger

Install a local skill:

minicode skills add ~/minimax-skills/skills/frontend-dev --name frontend-dev

List installed or discovered skills:

minicode skills list

Inside the interactive UI, you can also run:

/skills

to inspect which skills are available in the current session.

If you explicitly mention a skill name, MiniCode will prefer loading it. For example:

Use the frontend-dev skill and directly rebuild the current landing

MiniCode

Install / Use

README

MiniCode

Overview

Multi-language Versions

Branch Highlights

Table of Contents

Product Showcase Page

Why MiniCode

Features

Core workflow

Built-in tools

Safety and usability

Recent interaction upgrades

Installation

Quick Start

Commands

Management commands

Local slash commands

Terminal interaction

Configuration

Skills and MCP Usage

Skills: install, inspect, trigger