# MiniCode: a small terminal coding assistant you can read end to end > MiniCode is a TypeScript terminal coding assistant that copies the Claude Code workflow at a fraction of the size, with Rust, Python, Go and Java ports. It is a learning reference first and a daily driver second. **LiuMengxuan04/MiniCode** — A lightweight terminal coding assistant with Claude Code-like workflow, tool loop, and TUI architecture, built for learning and experimentation. Multi-language support: TypeScript , Python and Rust implementations available now. - Repository: https://github.com/LiuMengxuan04/MiniCode - Website: https://liumengxuan04.github.io/MiniCode/ - Stars: 1,118 · Forks: 126 - Language: TypeScript - License: MIT - Published: 2026-08-04 · Updated: 2026-08-18 · Language: en - Canonical page: https://hysenlabs.com/projects/liumengxuan04-minicode ## What MiniCode actually is, and who it is for MiniCode is a terminal coding assistant written in TypeScript. The README frames it as providing "Claude Code-like workflow and architectural ideas in a much smaller implementation", and it names its audience explicitly: learning, experimentation, and custom tooling. That is a narrower claim than most agent tools make, and it is the right one. The repository is deliberately compact so the control flow, the tool model and the TUI behaviour stay legible. The people who get value here are engineers who want to see how an agent loop is wired without reading tens of thousands of lines, and teams that need to bend an assistant to an internal convention. If you want a polished product that hides its internals, this is the wrong project. If you want a reference implementation you can diff against your own ideas, it is a good one. The README also links a companion document, CLAUDE_CODE_PATTERNS.md, whose title states the intent plainly: learn Claude Code design through MiniCode. ## The model to tool to model loop, and the three concurrent readers The README describes the loop in five steps: accept a user request, inspect the workspace, call tools when needed, review file changes before writing, and return a final response in the same terminal session. Multiple tool calls can run inside a single turn, which the README calls a `model -> tool -> model` loop. That phrase is the architecture in miniature: the model proposes, a tool executes, the result goes back to the model, and the cycle repeats until the turn ends. Concurrency is bounded and asymmetric. Up to 3 concurrent read-only sub-agents may run, and the README states that the root agent owns all code changes and can wait for or close workers. So the parallelism is for inspection, not for mutation. That is a deliberate safety choice: two writers editing the same file is a class of bug the design avoids rather than manages. The cost is that large refactors stay serial at the write step. Context is handled in layers. The README mentions provider-usage-first context stats with tail estimates, auto-compact, context collapse and snip compact, plus oversized tool results that are written to disk and replaced in context with a short preview and a file path. That last mechanism is the interesting one: instead of truncating a large tool output and losing it, the assistant keeps a pointer. Session state is per-project and supports resume, rename, fork and compact. ## Installing MiniCode and running a first turn The README gives an install sequence that runs from the repository directory. It assumes you have already cloned or downloaded the project, since the first command changes into it. The third command starts an installer that asks for your model name, `ANTHROPIC_BASE_URL` and `ANTHROPIC_AUTH_TOKEN`. ```bash cd mini-code npm install npm run install-local ``` The installer writes configuration to `~/.mini-code/settings.json` and `~/.mini-code/mcp.json`. Two environment variables change those locations: `MINI_CODE_HOME` overrides the config directory and `MINI_CODE_BIN_DIR` overrides the launcher directory. After installation, the launcher is on your path. ```bash minicode ``` If you would rather not install anything globally, the README offers a development mode and an offline mode. The mock mode is worth knowing about because it lets you exercise the TUI and the tool loop without spending tokens or reaching a provider. ```bash npm run dev MINI_CODE_MODEL_MODE=mock npm run dev ``` Once inside a session, the slash commands are the fastest way to see what the assistant can reach. `/tools` lists available tools, `/skills` lists discovered skills, `/mcp` shows MCP connection status, and `/status` shows session and context state. For a new project, `/init` scaffolds a `.mini-code/` directory and a `MINI.md` file. `/memory` shows which layered memory files were loaded for the current turn, which is the command to reach for when the assistant seems to have forgotten a project convention. ## Where MiniCode gets in your way The review-before-write step is the project's main safety feature and also its main friction. The README says file edits are reviewed with path and command permission checks, which means an approval flow sits between the model and your working tree. That is good for a tool you are still learning to trust. It is tedious for a tool you already trust, and the README does not document a bypass, an allowlist format, or an auto-approve mode. The USAGE.md file is where that would live, and it is not covered in the README. The bigger gap is rollback. The README describes review before write and permission checks, but it does not describe how to undo an edit that was approved and then turned out to be wrong. If you are used to an assistant that snapshots the tree or integrates with version control before every change, verify that behaviour yourself before pointing MiniCode at a repository with uncommitted work. The absence is not proof it does not exist, but the README does not document it. Versioning is the third constraint. package.json declares version 0.1.0 and marks the package private. There are no releases listed, and the last push date is not recorded in the repository metadata here. Treat the API surface, the config file format and the slash commands as moving. The MIT licence gives you the freedom to fork, not a promise of stability. ## MiniCode against Claude Code and Aider The obvious comparison is Claude Code itself. MiniCode copies the workflow, not the scale. Claude Code is a product with a support surface, a plugin ecosystem and an update cadence you do not control; MiniCode is a repository you can read in a sitting and change. The practical difference shows up when you disagree with a design decision. With Claude Code you file an issue or work around it. With MiniCode you edit the tool definitions in `src/` and run `npm run dev`. The second comparison is Aider, which also lives in the terminal and edits files from a chat loop. Aider's centre of gravity is the git commit: it is built around making clean, reviewable commits from model edits. MiniCode's centre of gravity is the loop and the TUI, with sub-agents, skills and MCP as the extension surfaces. If your goal is tidy commit history from an assistant, Aider's model is closer to that. If your goal is to understand or reshape an agent architecture, MiniCode is the more instructive codebase, and the MIT licence makes reshaping it straightforward. The multi-language ports are a third axis worth noting. The README lists Rust, Python, Go and Java implementations maintained in separate repositories. If you want the same conceptual design in a language your team already owns, that option exists. It also means the TypeScript repository is not the only place where behaviour is defined, which matters if you plan to contribute. ## Licence, maintenance and the cost of upgrading MiniCode is MIT licensed. That permits commercial use, modification and redistribution provided the copyright notice and permission notice are preserved. It does not grant trademark rights, and it comes with no warranty. Nothing here is legal advice; if you plan to ship a derivative, read the LICENSE file in the repository rather than this paragraph. The upgrade cost is tied to the private, unreleased status. With no published releases and version 0.1.0, there is no changelog to diff against and no semantic versioning contract to lean on. Upgrading means pulling the branch and reading the commits. If you have customised the tool definitions or the TUI, expect to reconcile those changes by hand each time. The configuration files at `~/.mini-code/settings.json` and `~/.mini-code/mcp.json` are the surface most likely to shift, so keep your own copy under version control and diff it after each pull. The repository metadata does not record a last push date, so the cadence of change cannot be judged from it. ## Conclusion Adopt MiniCode if you want to read, fork or teach the shape of a Claude Code style agent loop, or if you need a small terminal assistant whose tool model you can modify in an afternoon. Do not adopt it as a production coding platform: it is version 0.1.0, private, and the README documents no rollback behaviour for its review-before-write edits. Before committing, verify two things yourself: that your provider endpoint and token work through the installer prompt, and that the review step actually intercepts writes in your workflow rather than auto-approving them. The repository is the specification here, so read USAGE.md and ARCHITECTURE.md before you trust the loop with a real working tree. ## FAQ ### How do I install MiniCode? From the repository directory, run npm install followed by npm run install-local. The installer prompts for the model name, ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN, then writes configuration to ~/.mini-code/settings.json and ~/.mini-code/mcp.json. ### What is MiniCode? It is a lightweight terminal coding assistant written in TypeScript that follows a Claude Code-like workflow, with a model to tool to model loop, a full-screen TUI and review-before-write file edits. The README describes it as intended for learning, experimentation and custom tooling. ### Is MiniCode the same as Municode? No. MiniCode is a terminal coding assistant from the LiuMengxuan04 repository. Municode is an unrelated municipal code service, and searches for things like Municode Lee County or Municode Login refer to that other service, not to this project. ### Which languages does MiniCode support? The main repository is TypeScript. The README also links separate Rust, Python, Go and Java implementations, each maintained in its own repository, so the same design is available in several languages. ### Can I run MiniCode without an API key? The README documents an offline demo mode started with MINI_CODE_MODEL_MODE=mock npm run dev, which runs the assistant without reaching a provider. Normal use still requires a model name and an auth token supplied during installation. ## Sources - [Official documentation](https://liumengxuan04.github.io/MiniCode/) - [Official README](https://github.com/LiuMengxuan04/MiniCode#readme) - [Project repository](https://github.com/LiuMengxuan04/MiniCode) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/liumengxuan04-minicode