Mini-Kode
A ~14K-line educational AI coding agent CLI for learning and hacking coding-agent internals.
- Source repo
- minmaxflow/mini-kode
- Stars
- ★ 305
- Last updated
- 18d ago
- License
- MIT
- Primary language
- TypeScript
- FA score
- 43/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- Developers who want to learn how a coding agent is built and need a TypeScript codebase small enough to read end to end
- Not a fit if
- Teams wanting a production-grade coding assistant; this is an educational project
- Those needing image input or sub-agents, which are still planned
- Maintenance
- Commits in the last 30 dayslast commit 2026-11-03
- Source review
- 43/100 · Major gaps 1 safety controls not found
What does this agent do, and when should you use it?
Mini-Kode is an MIT-licensed, educational AI coding assistant that runs as a command-line tool, written in TypeScript and deliberately kept to roughly 14,000 lines so the whole system stays readable. It implements a complete agent loop on top of the OpenAI SDK, with streaming responses and human-in-the-loop permission approval, and renders a React/Ink terminal UI. A unified tool layer covers file operations, search and command execution, and can be extended by connecting to external MCP servers. The model layer is OpenAI-compatible, with DeepSeek, GLM and MiniMax documented as tested providers. It also reads an AGENTS.md file from the project root as persistent project context. It is aimed at developers who want to understand and modify how a coding agent works, not at teams that need a production-hardened assistant.
Invoking mini-kode parses arguments through Commander, then either launches an Ink/React interactive terminal UI or runs a single instruction directly in non-interactive mode. The core agent module drives the LLM loop: it sends the system prompt, the AGENTS.md project context and conversation history to an OpenAI-compatible endpoint and consumes streamed responses. When the model requests a tool call, the tools in src/tools (file read/write, search, command execution) are invoked, and the two-layer permission system in src/permissions asks the user to approve before anything takes effect. The LLM client lives in src/llm, configuration in src/config and session handling in src/sessions. External MCP servers can be connected to expose additional tools, and all activity is surfaced in the terminal interface.
- Developers who want to learn how a coding agent is built and need a TypeScript codebase small enough to read end to end
- Instructors running courses or workshops who need a well-structured, commented agent reference implementation
- Individual developers using DeepSeek, GLM or MiniMax API keys to fix bugs and search code from the terminal
- Teams that want to point the agent at their own OpenAI-compatible gateway with a custom base URL and model name
- Engineers who want to extend a coding assistant's capabilities through MCP servers
Key setup facts
Pulled from the install and usage notes below. The project README has the current values.
- Install / run
npm install -g mini-kode
- Environment variables
DEEPSEEK_API_KEYGLM_API_KEYMINIMAX_API_KEYMINIMAX_REGIONMINIMAX_MODELMINIKODE_API_KEY
How do you install or deploy this agent?
Install globally with npm:
npm install -g mini-kodeThen set at least one model provider key, for example DeepSeek or GLM:
export DEEPSEEK_API_KEY="your-deepseek-api-key"export GLM_API_KEY="your-glm-api-key"MiniMax is also supported:
export MINIMAX_API_KEY="your-minimax-api-key"
export MINIMAX_REGION="cn"
export MINIMAX_MODEL="MiniMax-M3"Or any OpenAI-compatible service:
export MINIKODE_API_KEY="your-api-key"
export MINIKODE_BASE_URL="https://your-api-provider.com/v1"
export MINIKODE_MODEL="your-model-name"How do you use this agent?
Start the interactive UI from your project root:
mini-kodeOr issue a single instruction in non-interactive mode:
mini-kode "help me fix the bug in auth.ts"Keep an AGENTS.md in the project root so the assistant has project context. To develop from source, install Bun and pnpm first:
pnpm install
pnpm run devWhat are this agent's strengths and limitations?
- At roughly 14K lines the codebase is small enough to read fully and fork, and the project publishes a DeepWiki code walkthrough
- A unified tool layer covers file operations, search and command execution, and MCP servers can add more
- The OpenAI SDK-based model layer has verified DeepSeek, GLM and MiniMax support plus custom base URL and model overrides, avoiding single-vendor lock-in
- A two-layer permission system gives human-in-the-loop approval before tool calls execute
- React/Ink delivers a modern terminal UI with theme support, and both interactive and non-interactive modes are available
- Self-described as an educational project with no claim of production stability or security auditing
- The roadmap lists session persistence, image input, sub-agents, reasoning models and context caching as not yet implemented
- Development workflow depends on Bun and pnpm rather than a plain Node toolchain
- You must bring your own third-party model API key and pay per use; nothing works out of the box without a provider
- The README does not state supported operating systems, and MCP and non-interactive configuration details are not documented in depth
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Mini-Kode This agent | 43 · Major gaps | CLIFree + model costs | ★ 305 | 18d ago | TypeScript | OpenAI API |
| smelt | 50 · Major gaps | CLIFree + model costs | ★ 73 | 2d ago | Rust | ChatGPT · Claude Code · OpenAI API · Claude API |
| rpi: Rust Coding-Agent Runtime | 71 · Some gaps | CLIFree + model costs | ★ 287 | today | Rust | OpenAI API · Claude API |
| Aster | 70 · Some gaps | CLIFree + model costs | ★ 139 | 20d ago | Rust | OpenAI API |
How does FollowAgents rate this agent?
Why each dimension lost points
docs/permission.md documents a multi-layer approval model (default/autoEdit/yolo), absolute-path requirement with path.resolve normalization, a bash blacklist (curl/wget/nc etc.) and backtick prohibition, which is substantive least-privilege and confirmation design, so least_privilege and user_confirmation score 2. However yolo mode auto-approves all FS and bash operations with no prominent risk warning, which is deducted. data_flow_transparency only states API keys are not stored in config and use env vars; it never discloses that conversation/file content is sent to third-party LLM endpoints, so 1. sensitive_data_handling has env-var and ${ENV_VAR} resolution, but MCP examples run npx -y with @latest packages and no integrity pinning, so 2. dependency_security: all deps use caret ranges, no lockfile evidence, no audit script, so 1. external_effects: bash execution and external MCP servers exist but no sandbox or egress restriction is described, so 1. rollback is entirely absent: no undo, no diff rollback, session persistence listed only as a future plan, so 0. source_attribution: README References explicitly credits inspiration sources, so 2.
self_consistency has clear contradictions: docs/permission.md says project policy lives in .mini-kode/config.json while docs/config.md says .mini-kode/permissions.json, and grant fields differ (path/command vs pattern); README says two-layer permissions while permission.md says three-layer, so 1. dependency_availability: caret ranges with no lockfile evidence, and a Bun build vs Node>=20 runtime toolchain mix raises availability risk, so 1. failure_messages: docs mention clear errors for banned commands, but MCP init failure only console.errors then marks initialized and silently continues, so 1.
audience_and_scenarios is clearly educational, aimed at understanding modern coding-agent architecture, so 2. capability_boundaries are defined via the tool system, permission types, banned commands and a future-plans list, so 2. trigger_precision describes the approval flow but bash uses a blacklist rather than allowlist and prefix grants like npm:* are bypassable via arguments, so 1. environment_fit requires Node>=20 plus Bun+pnpm for development and supports multiple LLM endpoints/regions, but has no platform (e.g. Windows) notes, so 1.
information_architecture has README, a docs directory (permission/config), and AGENTS.md/CLAUDE.md dev guides, so 2. install_notes cover global npm install, API key env vars, dev prerequisites and commands, so 2. naming_stability: early 0.2.x with inconsistent config paths/fields across docs, so 1. examples_and_faq has install/config examples but no FAQ or troubleshooting, so 1. known_limitations only hints at gaps via Future Plans without a systematic limitations/risk list, so 1. license has a full MIT LICENSE consistent with package.json, so 3. versioning_changelog has a version number but no CHANGELOG and a manual bump process, so 1. maintenance_responsibility: publisher is unverified, only a personal email and repo link, no governance or maintenance commitment, so 1.
output_usability offers interactive and non-interactive modes, streaming and an Ink UI, but no output-format or result examples, so 1. marginal_value is an educational project whose incremental value is readable architecture rather than production productivity, so 1. cost_benefit has no token-cost controls and context caching is only a future plan, so 1.
claim_traceability: README claims 14K lines of production code and 'tested and verified' DeepSeek/GLM support, but the packet contains no supporting evidence, so 1. cross_source_corroboration: README, AGENTS.md, CLAUDE.md and docs contradict each other on permission layer count and config paths, so 1. fact_inference_separation: docs mix facts with vision (Future Plans alongside current state) without clearly separating implemented vs planned, so 1.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- yolo mode auto-approves all file writes and bash commands without prompting; confirm the risk and avoid it in sensitive directories.
- Bash permissions use a blacklist rather than an allowlist, and prefix grants like npm:* can be bypassed via arguments; command validation is not a strong isolation boundary.
- Docs contradict each other on permission layer count (two vs three) and the project permission file path (config.json vs permissions.json); trust the source over the docs.
- MCP examples use npx -y with @latest packages, creating supply-chain and version-drift risk; pin versions and review server provenance.
- No rollback/undo or session-resume capability, so destructive operations are hard to recover from.
- Publisher identity is unverified by the FollowAgents registry; maintenance responsibility and update path are unclear.
FAQ
Is Mini-Kode free to use?
Will it modify my files without asking?
Can I point it at my own model gateway?
Does it remember my project context?
Which client platforms does it support?
Is Mini-Kode open source?
Is Mini-Kode safe to use?
Is Mini-Kode still maintained?
Who makes Mini-Kode?
Thanks — we use this to improve the page.