MiniCode

A lightweight, highly efficient coding tool. Designed for speed, built for simplicity.

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, now including per-project sessions, provider-usage context accounting, auto-compact, and large tool-result storage.
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

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
per-project session persistence with resume, rename, fork, and compact commands
model-aware context stats with provider usage, estimated tail tokens, and auto-compact
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
oversized tool results are stored on disk with a short in-context preview, keeping long command output from crowding out useful conversation context

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
context accounting is now provider-usage-driven: provider-reported usage anchors the context stats, auto-compact trigger, blocking/warning levels, and TUI context badge; the local estimator is used only when provider usage is unavailable or for messages added after the latest usage boundary
the TUI context badge distinguishes exact provider usage from estimated tail text, for example ctx 82% ... usage+est; compacted conversations mark retained pre-compact usage stale so it is not reused as current context truth
large tool results are persisted under MiniCode's local data directory and replaced in the model context by a preview plus file path; repeated passes reuse the same replacement so accounting stays stable

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

You can override the config directory with MINI_CODE_HOME:

export MINI_CODE_HOME=/path/to/custom/dir
npm run install-local

The launcher is installed to:

~/.local/bin/minicode

You can override the launcher directory with MINI_CODE_BIN_DIR:

export MINI_CODE_BIN_DIR=/path/to/custom/bin
npm run install-local

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)

Session management

MiniCode automatically saves your conversation after each turn. Each launch creates a new session with a unique ID.

/resume — open interactive session picker
/resume <id> — resume a specific session by ID
/rename <name> — rename the current session
/new — start a fresh session (previous session is preserved)
/fork — fork the current session into a new independent copy
/compact — compress context to free up context window space

CLI flags:

minicode --resume — launch with session picker
minicode --resume <id> — resume a specific session
minicode --fork <id> — fork a session and resume the fork

Sessions are scoped per working directory and stored in ~/.mini-code/projects/ using append-only JSONL. On exit, MiniCode prints the session ID so you can resume later. Sessions older than 30 days are automatically cleaned up.

Long Sessions and Context Management

MiniCode now treats long-running conversations as a first-class workflow:

Provider usage, when returned by the model endpoint, is recorded on assistant response boundaries and used as the primary token source.
If messages are added after the latest provider usage boundary, MiniCode adds a local tail estimate and labels the badge accordingly, for example usage+est.
If no provider usage is available, MiniCode falls back to local estimation so offline mode and compatible gateways still work.
Context stats feed the TUI badge, warning/blocking levels, and auto-compact trigger.
/compact performs manual context compression and records a compact boundary in the session log.
Automatic compaction can summarize older turns once utilization gets high.
After compaction, retained pre-compact usage is marked stale so an old provider total is not mistaken for the current context size.
Oversized tool results are written to ~/.mini-code/tool-results/ and replaced in the visible context with a preview and the full-output path. A single result over 50_000 characters is persisted, and batches are reduced toward a 200_000 character visible budget.

Session storage and context compression work together: loadSession resumes from the latest compact boundary, while loadTranscript can still rebuild the visible transcript from the JSONL event log.

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 page instead of stopping at a plan.

If you want to be even more explicit:

Load the fullstack-dev skill first, then follow its workflow to implement this task.

A common pattern is to clone an official or Claude Code-compatible skills repo locally and install from there:

git clone https://github.com/MiniMax-AI/skills.git ~/minimax-skills
minicode skills add ~/minimax-skills/skills/frontend-dev --name frontend-dev

MCP: install, inspect, trigger

Install a user-scoped MCP server:

minicode mcp add MiniMax --env MINIMAX_API_KEY=your-key --env MINIMAX_API_HOST=https://api.minimaxi.com -- uvx minimax-coding-plan-mcp -y

List configured MCP servers:

minicode mcp list

To configure an MCP server only for the current project, add --project:

minicode mcp add filesystem --project -- npx -y @modelcontextprotocol/server-filesystem .
minicode mcp list --project

Inside the interactive UI, run:

/mcp

to see which servers are connected, which protocol they negotiated, and how many tools / resources / prompts they expose.

MCP tools are automatically registered as:

mcp__<server_name>__<tool_name>

For example, after connecting the MiniMax MCP server you may see:

mcp__minimax__web_search
mcp__minimax__understand_image

These tool names are not hand-written in MiniCode. They appear automatically after a successful MCP connection.

How to use them in chat

The simplest approach is to just describe the task naturally and let the model decide when to use a skill or MCP tool:

Search for recent Chinese-language resources about MCP and give me 5 representative links.

If MiniMax MCP is connected, the model will typically choose mcp__minimax__web_search.

If you want a more controlled workflow, name the skill or target capability explicitly:

Use the frontend-dev skill and directly modify the current project files to turn this page into a more complete product landing page.

Or:

Use the connected MCP tools to search for the MiniMax MCP guide and summarize what capabilities it provides.

When to use skills vs MCP

skills are better for workflow, conventions, domain-specific instructions, and reusable execution patterns
MCP is better for search, image understanding, browsers, filesystems, databases, and other remote capabilities

A common combination is:

use a skill such as frontend-dev to shape how the work should be done
use MCP to provide external search, image understanding, or system integrations

Compatibility notes

MiniCode currently focuses on:

local SKILL.md discovery with load_skill
stdio MCP servers
MCP tools
generic helper tools for MCP resources and prompts

For vendor compatibility, MiniCode automatically tries:

standard Content-Length framing
then falls back to newline-json if needed

That means servers such as MiniMax MCP, which use newline-delimited JSON over stdio, can still be connected directly.

Star History

Learn Claude Code Design Through MiniCode

If you want to study the project as a learning resource, continue with:

What Claude Code Design Ideas You Can Learn Through MiniCode

Project Structure

src/index.ts: CLI entry
src/agent-loop.ts: multi-step model/tool loop
src/tool.ts: tool registry and execution
src/skills.ts: local skill discovery and loading
src/mcp.ts: stdio MCP client and dynamic tool wrapping
src/manage-cli.ts: top-level minicode mcp / minicode skills management commands
src/session.ts: append-only session JSONL, resume/fork/rename, compact boundaries, and expiry cleanup
src/compact/*: manual compact, auto-compact, and conversation summarization helpers
src/utils/token-estimator.ts: provider-usage-first context accounting with estimate fallback
src/utils/tool-result-storage.ts: large tool-output persistence and preview replacement
src/tools/*: built-in tools
src/tui/*: terminal UI modules
src/config.ts: runtime configuration loading
src/install.ts: interactive installer

Code Size

Current core implementation size is about 7,874 lines.

Counting scope:

included: core TypeScript source, built-in tools, config, MCP, sessions, compaction, adapters, permissions, and bin/minicode
excluded: docs, tests, external/, node_modules/, and TUI files (src/tui/, src/tty-app.ts, src/ui.ts)

If src/tty-app.ts and src/ui.ts are included while still excluding src/tui/, the total is about 9,767 lines.

Architecture Docs

Contributing

Roadmap

Development

npm run check

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

Name		Name	Last commit message	Last commit date
Latest commit History 84 Commits
bin		bin
docs		docs
external		external
src		src
test		test
.gitignore		.gitignore
.gitmodules		.gitmodules
ARCHITECTURE.md		ARCHITECTURE.md
ARCHITECTURE_ZH.md		ARCHITECTURE_ZH.md
CLAUDE_CODE_PATTERNS.md		CLAUDE_CODE_PATTERNS.md
CLAUDE_CODE_PATTERNS_ZH.md		CLAUDE_CODE_PATTERNS_ZH.md
CONTRIBUTING.md		CONTRIBUTING.md
CONTRIBUTING_ZH.md		CONTRIBUTING_ZH.md
LICENSE		LICENSE
README.md		README.md
README.zh-CN.md		README.zh-CN.md
ROADMAP.md		ROADMAP.md
ROADMAP_ZH.md		ROADMAP_ZH.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

MiniCode

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

Session management

Long Sessions and Context Management

Configuration

Skills and MCP Usage

Skills: install, inspect, trigger

MCP: install, inspect, trigger

How to use them in chat

When to use skills vs MCP

Compatibility notes

Star History

Learn Claude Code Design Through MiniCode

Project Structure

Code Size

Architecture Docs

Contributing

Roadmap

Development

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages