{"id":49197361,"url":"https://github.com/minmaxflow/mini-kode","last_synced_at":"2026-05-09T19:01:42.429Z","repository":{"id":321701659,"uuid":"1086547543","full_name":"minmaxflow/mini-kode","owner":"minmaxflow","description":"An educational AI coding assistant CLI tool for learning modern AI coding assistant systems","archived":false,"fork":false,"pushed_at":"2025-10-31T03:55:11.000Z","size":201,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-10-31T04:09:59.881Z","etag":null,"topics":["ai","cli","coding-agent","educational","llm","tool-system"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/minmaxflow.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-10-30T15:09:56.000Z","updated_at":"2025-10-31T03:55:14.000Z","dependencies_parsed_at":"2025-10-31T04:20:31.062Z","dependency_job_id":null,"html_url":"https://github.com/minmaxflow/mini-kode","commit_stats":null,"previous_names":["minmaxflow/mini-kode"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/minmaxflow/mini-kode","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/minmaxflow%2Fmini-kode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/minmaxflow%2Fmini-kode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/minmaxflow%2Fmini-kode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/minmaxflow%2Fmini-kode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/minmaxflow","download_url":"https://codeload.github.com/minmaxflow/mini-kode/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/minmaxflow%2Fmini-kode/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32831504,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-08T08:22:46.396Z","status":"online","status_checked_at":"2026-05-09T02:00:06.633Z","response_time":123,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","cli","coding-agent","educational","llm","tool-system"],"created_at":"2026-04-23T12:00:27.535Z","updated_at":"2026-05-09T19:01:42.416Z","avatar_url":"https://github.com/minmaxflow.png","language":"TypeScript","funding_links":[],"categories":["Terminal-native coding agents"],"sub_categories":["Open Source"],"readme":"# Mini-Kode\n\nAn educational AI coding assistant project that helps you understand and hack modern AI coding assistant systems.\n\n## 🌟 Why Mini-Kode?\n\n![Demo](./demo.png)\n\nMini-Kode is an **educational project** designed to help developers understand modern Coding Agent architecture. We strike the perfect balance between overly complex open-source projects and simplistic demo examples, offering a complete yet manageable implementation (14K lines of production code) with:\n\n- **📚 Education-First Design** - Clean architecture built on OpenAI SDK with thoughtful type design and comprehensive comments\n- **🛠️ Complete Tool System** - Unified interface with comprehensive tools for file operations, search, and command execution\n- **🔌 MCP Integration** - Connect to external MCP servers for extended functionality\n- **⚙️ Multi-LLM Support** - Compatible with OpenAI APIs, including GLM, DeepSeek, and other mainstream models\n- **🤖 Agent Loop** - Complete LLM workflow with streaming responses and human-in-the-loop permission approval\n- **🎨 Modern UI** - React/Ink-based terminal interface with theme support\n\n## 🚀 Quick Start (Install \u0026 Use)\n\n### Install Globally\n\n```bash\nnpm install -g mini-kode\n```\n\n### Set Up API Key\n\n**DeepSeek** (tested and verified):\n\n```bash\nexport DEEPSEEK_API_KEY=\"your-deepseek-api-key\"\n```\n\n**Or use GLM (智谱AI)** (tested and verified):\n\n```bash\nexport GLM_API_KEY=\"your-glm-api-key\"\n```\n\n**Or use OpenAI compatible API**:\n\n```bash\nexport OPENAI_API_KEY=\"your-openai-api-key\"\n# or\nMINIKODE_API_KEY=\"your-api-key\"\nMINIKODE_BASE_URL=\"https://your-api-provider.com/v1\"\nMINIKODE_MODEL=\"your-model-name\"\n```\n\n### Run Mini-Kode\n\n```bash\n# Interactive mode (launch UI)\nmini-kode\n\n# Non-interactive mode (direct execution)\nmini-kode \"help me fix the bug in auth.ts\"\n```\n\n## 🔧 Development Quick Start\n\n### Prerequisites\n\n- **Bun**\n- **pnpm**\n\n### Install Dependencies\n\n```bash\npnpm install\n```\n\n### Development Commands\n\n```bash\n# Development mode with file watching\npnpm run dev\n\n# Build\npnpm run build\n\n# Test\npnpm run test\n```\n\n## 📖 Learning Resources\n\nWant to dive deeper into the system architecture? Check out [docs/README.md](./docs/README.md) for complete system documentation and architecture explanations.\n\n### 📚 Project Analysis\n\nFor a comprehensive code analysis and walkthrough, visit [**Mini-Kode Deep Analysis**](https://deepwiki.com/minmaxflow/mini-kode/1-overview) - an in-depth exploration of the codebase architecture, design patterns, and implementation details.\n\n## 🧠 Project Memory\n\nMini-Kode automatically uses `AGENTS.md` file in your project root to provide context-aware assistance:\n\n- **Automatic Context**: System reads `AGENTS.md` to understand your project\n- **Customizable**: Edit `AGENTS.md` to include project-specific information\n- **Persistent Memory**: Maintains project context across sessions\n\n## 🏗️ Project Structure\n\n```\nsrc/\n├── tools/          # Tool system and individual tools\n├── ui/             # Ink-based CLI interface components\n├── llm/            # LLM client and streaming integration\n├── permissions/    # Two-layer permission system\n├── config/         # Configuration management\n├── cli/            # CLI framework and commands\n├── agent/          # Core agent logic\n├── sessions/       # Session management\n└── utils/          # Shared utilities\n```\n\n## 🛠️ Tech Stack\n\n- **TypeScript** - Static type checking\n- **pnpm** - Package management\n- **Ink** - React terminal UI\n- **OpenAI SDK** - LLM integration (supports DeepSeek/OpenAI/compatible APIs)\n- **Vitest** - Testing framework\n- **Zod** - Runtime type validation\n- **Commander** - CLI framework\n\n## 🚧 Future Plans\n\n1. **Session Persistence and Resume** - Save and restore agent sessions\n2. **LLM Built-in Tool Integration** - Support for LLM's native tool capabilities (note: DeepSeek currently doesn't support web search tools)\n3. **Image Input Support** - Process and analyze image inputs\n4. **Sub Agents Functionality** - Hierarchical agent delegation\n5. **Reasoning Model Support** - Integration with reasoning-focused models\n6. **Tool Call Message Streaming** - Real-time streaming of tool execution\n7. **Context Caching** - Smart caching of conversation context to reduce token usage\n\n## 📚 References\n\nThis project was inspired by and references the following resources:\n\n- **[Building an Agent](https://ampcode.com/how-to-build-an-agent)** - Guide on building AI agents\n- **[Building an Agentic System](https://gerred.github.io/building-an-agentic-system/index.html)** - Comprehensive guide to building agentic systems\n- **[System and Tool Prompts](https://gist.github.com/transitive-bullshit/487c9cb52c75a9701d312334ed53b20c)** - System prompts and tool prompts for coding agent\n- **[Neovate Code](https://github.com/neovateai/neovate-code)** - Todo tool prompt\n- **[Claude Code](https://claude.ai/code)** - UX reference for CLI interface design\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fminmaxflow%2Fmini-kode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fminmaxflow%2Fmini-kode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fminmaxflow%2Fmini-kode/lists"}