MiniCode is a lightweight, terminal-first coding assistant designed for local development workflows. It provides a reference implementation of the model-tool-model agent loop, delivering a Claude Code-like experience within a compact and readable codebase README.md26-28 The system is built to be fast, simple, and highly extensible, making it an ideal platform for learning agentic architectures or building custom terminal-based developer tools README.md81-89
MiniCode operates through a practical agent loop that manages the entire lifecycle of a coding task:
read_file, edit_file, patch_file), shell commands (run_command), and web searching README.md104-116SKILL.md files README.md100-102~/.mini-code/projects/ using append-only JSONL, allowing for resume, rename, and fork operations README.md98 ROADMAP.md40-42For a guide on setting up your environment and running your first session, see Getting Started.
The architecture of MiniCode is divided into several distinct subsystems that coordinate through a central agent loop. The following diagram illustrates how natural language requests are transformed into concrete code actions.
From Intent to Action: Code Entity Mapping
Sources: README.md32-42 README.zh-CN.md92-103 ROADMAP.md11-32
The heart of MiniCode is the multi-turn tool-calling loop. It manages conversation state, sends context to the LLM via the AnthropicModelAdapter, and dispatches tool calls requested by the model README.md92-95 It continues to iterate until the model provides a final response or requires user intervention via ask_user README.md146
MiniCode features a robust set of built-in tools for filesystem operations (e.g., edit_file, grep_files) and system interaction (run_command) README.md104-113 Beyond built-ins, it integrates with Model Context Protocol (MCP) servers over stdio, allowing users to plug in external tools, resources, and prompts dynamically README.md101-102
Security is handled by the PermissionManager in src/permissions.ts, which gates access to sensitive paths and commands README.md126 Any file modification triggers a TUI-based diff review in src/file-review.ts, where users must explicitly approve changes before they are committed to disk README.md125
The interface is a full-screen terminal application orchestrated by runTtyApp in src/tty-app.ts. It provides a scrollable transcript, a command menu (slash commands), and interactive approval dialogs README.md96-98 Recent upgrades include standardized unified diff output and serialized input handling to prevent event deadlocks README.md137-142
Subsystem Relationship Diagram
Sources: README.md92-102 README.zh-CN.md164-185 ROADMAP.md11-42
MiniCode is intentionally kept small to remain "hackable." It prioritizes the most valuable execution patterns—such as directory awareness and secure write flows—over a "platform" approach with heavy dependencies README.md81-89
The project maintains a lightweight Claude Code-style distinction between foreground tool execution and background shell tasks README.md141 Future development focuses on richer project memory, stronger provider abstraction (OpenAI, OpenRouter), and expanded multi-language implementations (Rust and Python) ROADMAP.md44-63 ROADMAP.md78-88
For a deeper dive into these constraints and the project's future, see Design Principles and Roadmap.
Sources:
Refresh this wiki
This wiki was recently refreshed. Please wait 7 days to refresh again.