LiuMengxuan04/MiniCode

MiniCode – a lightweight terminal‑first coding assistant

What it is – MiniCode is an open‑source, terminal‑based AI coding assistant that mimics the Claude Code agent pattern but in a very small codebase. It runs locally, talks to an LLM (Anthropic’s Claude or any model exposed through the Sidrune AI unified API), and can call a set of built‑in tools (file edit, search, shell commands, web fetch, etc.) to carry out a user’s request.

Why it matters – Most AI‑powered coding assistants are large web services or heavyweight desktop apps. MiniCode deliberately stays tiny (a few thousand lines of TypeScript) so developers can read, modify, and extend the whole agent loop. It is therefore useful for:

• learning how LLM‑tool‑calling agents are wired together,
• building custom, project‑specific assistants without a cloud platform,
• experimenting with multi‑step tool workflows, goals, and planning in a terminal UI.

Core capabilities

• Model ↔ tool ↔ model loop – a single turn can invoke multiple tools, feed their results back to the LLM, and get a final answer.
• Sub‑agents – up to three read‑only workers run in parallel; the root agent owns all file changes.
• In‑memory plan & goal – /plan shows a Todo list that the agent updates; /goal creates a persistent objective that survives turns.
• Loop feature – repeat a prompt on a timed interval, sharing the same plan.
• Full‑screen TUI – transcript scrolling, slash‑command menu, approval prompts before any file write.
• Session persistence – each project gets its own .mini-code/ folder; sessions can be resumed, renamed, or forked.
• Context management – usage‑first stats, auto‑compact, and snipping of oversized tool results.
• Extensible tool set – file manipulation, grep‑style search, shell execution, web fetch, clarification prompts, plus user‑defined skills via SKILL.md.

Installation & quick start

# clone and install
git clone https://github.com/LiuMengxuan04/MiniCode.git
cd MiniCode
npm install
npm run install-local   # prompts for model name & Anthropic credentials

# launch the assistant
minicode

A mock mode (MINI_CODE_MODEL_MODE=mock) lets you try the UI without an API key.

Typical workflow

1. Enter a request – e.g. “Add a unit test for parseJson”.
2. MiniCode inspects the workspace, decides which tools are needed, and calls them (search files, run the test runner, etc.).
3. The LLM receives tool outputs, refines a plan, and proposes file changes.
4. You review the diff in the TUI; MiniCode asks for confirmation before writing.
5. The final response (summary, next steps, etc.) is shown in the same terminal session.

Multi‑language ecosystem – The repository hosts the TypeScript reference implementation. Equivalent versions exist in Rust, Python, Go, and Java, showing that the architecture is language‑agnostic.

Who’s behind it – Founder Liu Mengxuan (TypeScript core), co‑initiator GateJustice (long‑session context system), and several contributors handling sub‑agents, memory layers, and language ports.

Where to learn more –

• Usage guide (USAGE.md) – full command reference and configuration examples.
• Architecture overview (ARCHITECTURE.md) – explains the agent loop, memory layers, and tool model.
• Demo page – open docs/index.html or the GitHub‑Pages site for a visual walkthrough.

Ideal users

• Developers who want a terminal‑only AI assistant.
• Researchers or hobbyists studying LLM‑driven tool‑calling patterns.
• Teams needing a customizable, self‑hosted coding helper without the overhead of a cloud platform.

---

MiniCode is a genuine, lightweight AI‑agent project focused on coding assistance, not a generic tutorial list or a trivial demo.