Mini-Kode

A ~14K-line educational AI coding agent CLI for learning and hacking coding-agent internals.

Stars
★ 305
Last updated
18d ago
License
MIT
Primary language
TypeScript

At a glance

How it runs
CLI
Works with
Universal · cross-platformOpenAI API
Cost
Free software; you pay for model usage
Setup effort
Low · running in minutes
You'll need
Node.js/npmBunpnpmDeepSeek/GLM/MiniMax/OpenAI-compatible API keyShell / CLINetwork accessLocal filesystemMCP Server
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

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.

  1. Developers who want to learn how a coding agent is built and need a TypeScript codebase small enough to read end to end
  2. Instructors running courses or workshops who need a well-structured, commented agent reference implementation
  3. Individual developers using DeepSeek, GLM or MiniMax API keys to fix bugs and search code from the terminal
  4. Teams that want to point the agent at their own OpenAI-compatible gateway with a custom base URL and model name
  5. 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_KEY GLM_API_KEY MINIMAX_API_KEY MINIMAX_REGION MINIMAX_MODEL MINIKODE_API_KEY

How do you install or deploy this agent?

Install globally with npm:

npm install -g mini-kode

Then 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-kode

Or 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 dev

What are this agent's strengths and limitations?

Pros
  • 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
Limitations
  • 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?

FollowAgents source review · FARS-2.1
Major gaps
43/ 100 5-point scale 2.2 / 5
Trust 13/29
Reliability 5/14
Adaptability 9/18
Convention 9/18
Effectiveness 4/13
Verifiability 3/8
Why each dimension lost points
Trust13 / 29 · 2.2/5

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.

Reliability5 / 14 · 1.8/5

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.

Adaptability9 / 18 · 2.5/5

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.

Convention9 / 18 · 2.5/5

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.

Effectiveness4 / 13 · 1.5/5

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.

Verifiability3 / 8 · 1.9/5

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.

Risks and how to mitigate them
  • 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.
Evidence confidence: Low Reviewed Nov 17, 2026 Reviewed revision 147ee04f57f0
See the full review method →
Maintain this project? Add the FARS badge to your README

The badge shows the current review score and verdict and links back to this page. It refreshes about once an hour after a re-review.

FARS

[![FARS review](https://followagents.com/badge/mini-kode.svg)](https://followagents.com/en/agents/mini-kode)
<a href="https://followagents.com/en/agents/mini-kode"><img src="https://followagents.com/badge/mini-kode.svg" alt="FARS review"></a>

FAQ

Is Mini-Kode free to use?
The software is MIT-licensed and free, but you must supply a DeepSeek, GLM, MiniMax or other OpenAI-compatible API key and pay that provider for model usage.
Will it modify my files without asking?
The README describes a human-in-the-loop, two-layer permission system that tool calls pass through; check the source and docs/README.md for the exact approval granularity.
Can I point it at my own model gateway?
Yes. Set MINIKODE_API_KEY, MINIKODE_BASE_URL and MINIKODE_MODEL to target any OpenAI-compatible service.
Does it remember my project context?
It automatically reads AGENTS.md from your project root as persistent, cross-session context, and you can edit that file to add project-specific information.
Which client platforms does it support?
It is a standalone terminal CLI that talks to models over OpenAI-compatible APIs; the README documents no native integrations with ChatGPT, Claude or similar products.
Is Mini-Kode open source?
Yes. The source code is on GitHub (minmaxflow/mini-kode) under the MIT licence.
Is Mini-Kode safe to use?
FollowAgents' FARS review (Nov 17, 2026) scored Mini-Kode 13/29 on trust and safety. The review did not find these safety controls in the source: rollback or recovery path. Before giving it real accounts or data: Back up first, or work on a git branch or snapshot, so its changes can be undone.
Is Mini-Kode still maintained?
Yes. The latest commit on GitHub is from 2026-11-03, within the last 30 days.
Who makes Mini-Kode?
Mini-Kode is published on GitHub by the account minmaxflow. FollowAgents has not verified which person or company is behind that account.
Was this page helpful?
View on GitHub ↗ Install ↓

Compare agents like this one

The same FARS review applied across the shortlist this agent qualifies for.

Related concepts