mangopi-cli 0.1.33

Mango Pi Cli

Mangopi CLI

Single-file, zero-dependency AI coding assistant for the terminal.

Mangopi CLI is a local-first autonomous coding agent built with only the Python standard library.

No frameworks. No Electron. No Docker. No dependency hell.

Just one fast, hackable Python file.

---

Design Philosophy

Seeking a perfect balance between code size, complexity, and the functionality & effectiveness of the agent.

Mangopi CLI intentionally keeps the runtime extremely small.

Why?

• easier to audit
• easier to hack
• easier to fork
• easier to understand
• easier to run locally

The project avoids unnecessary abstractions, frameworks, and dependencies whenever possible.

---

Why Mangopi CLI?

Mangopi CLI	Typical AI Agent Frameworks
Single-file runtime	Large multi-module codebases
Python standard library only	Heavy dependency trees
Instant startup	Slow boot time
Fully hackable	Framework-heavy
Local-first	Cloud-oriented
Minimal abstractions	Over-engineered
Easy to fork	Hard to customize

---

Ideal For

• developers who prefer terminal workflows
• users who dislike heavyweight AI frameworks
• hackers and tinkerers
• local-first enthusiasts
• people who want full runtime control
• building custom coding agents

---

Features

• Single-file architecture
• Python standard library only
• Instant startup speed
• Local-first workflow design
• Autonomous loop execution (3-agent implement / verify / refine pipeline)
• Smart provider routing with tiered models (high/medium/low)
• Flash-ext thinking framework server (OpenAI-compatible proxy)
• Multimodal support (image reading via view_image)
• Web search via Bocha AI Search (web_search tool)
• Context-aware conversation management
• Automatic context compacting
• OpenAI-compatible API support
• Built-in file and shell tools
• Persistent local sessions
• Skill system support (SKILL.md)
• Safe shell execution checks
• Fully hackable and easy to extend
• Large-context optimized runtime

---

Installation

From PyPI

pip install mangopi-cli

Start Mangopi CLI:

mangopi-cli

---

From Source

git clone [e-mail]:w4n9H/mangopi-cli.git
cd mangopi-cli
python mangopi_cli.py

---

Configuration

Required:

export MANGO_KEY="your_api_key"

Recommended:

export MANGO_API_URL="https://api.deepseek.com"
export MANGO_MODEL="deepseek-v4-flash"

Optional:

export MANGO_MAX_CONTEXT=1000000   # default 1,000,000 tokens
export MANGO_LANG=en               # en (default) | zh — controls UI text and CLI help language

---

Smart Provider Routing

Enable multi-model routing with the MANGO_ROUTING env var:

export MANGO_ROUTING=on

Define providers in .mangocli/providers.json (tiers: low/medium/high):

{
  "providers": [
    {"name": "low",    "url": "https://api.deepseek.com", "model": "deepseek-v4-flash",    "tier": "low",    "api_key": "sk-xxx"},
    {"name": "medium", "url": "https://api.deepseek.com", "model": "deepseek-v4",          "tier": "medium", "api_key": "sk-xxx"},
    {"name": "high",   "url": "https://api.deepseek.com", "model": "deepseek-v4-reasoning", "tier": "high",   "api_key": "sk-xxx"}
  ],
  "routing": {
    "default_tier": "medium",
    "score_thresholds": {"low_max": 3, "medium_max": 7}
  }
}

Mangopi CLI auto-selects the appropriate tier based on task complexity — keyword matching + LLM scoring. Each turn uses one model; no mid-loop switching. A sample config is at providers.json.example.

---

Supported Providers

Mangopi CLI supports:

• DeepSeek
• OpenAI-compatible APIs
• MiniMax
• Custom compatible endpoints

Example:

export MANGO_API_URL="https://api.openai.com/v1"
export MANGO_MODEL="gpt-4o-mini"

---

Usage

Start the CLI:

mangopi-cli

or:

python mangopi_cli.py

---

Built-in Commands

Command	Aliases	Description
/q	/quit	Quit
/n	/new	Start a new session (old session is auto-backed-up)
/c	/compact	Manually trigger full conversation compact
/h	/help	Show built-in command help
/l <goal>	/loop <query>	Start Loop Engineering — 3-agent pipeline (implement → verify → refine)
/g <goal>	/goal <query>	(deprecated) Use /loop instead

/loop runs up to 5 iterations; the pipeline short-circuits on the first VERIFY: PASS.

---

Loop Engineering

Loop Engineering replaces the legacy Goal Mode with a 3-agent collaborative pipeline:

Agent	Role
Implementer	Designs & writes code. Explicitly forbidden from running tests — "that's the Verifier's job."
Verifier	Inspects changed files, determines the right test command, runs tests, judges PASS/FAIL at the architecture level.
Updater	On failure, reads the Verifier's analysis and produces a refined prompt (50–200 words) for the next Implementer iteration; read/grep only, no code edits.

The pipeline runs up to 5 iterations, short-circuiting on the first VERIFY: PASS. Session files under .mangocli/loops/ are automatically cleaned up on exit.

Example:

/loop build a fastapi todo app with tests

The agent implements, a dedicated Verifier runs the actual tests, and if anything fails, the Updater refines the prompt for the next attempt — all autonomously.

Flash-ext Server

Flash-ext is a standalone OpenAI-compatible HTTP proxy that injects phase-aware structured thinking frameworks before each model call. Designed for IDEs and clients that cannot run the full Mangopi agent loop.

Start the server:

python mangopi_cli.py --flash-ext --debug
# Optional flags: --web-search --port 8080 --token my-token

Flash-ext:

• Matches keywords + tool-call patterns to select thinking frameworks (debug/design/explain/optimize/implement/investigate/verify/reevaluate).
• On complex tasks, calls its own LLM to analyze session state and provide tailored guidance.
• Injects all context into the user message via XML tags — zero new system messages.
• Supports optional web search augmentation.
• Is cognitive-only: never touches file I/O or bash; only enhances reasoning before the request reaches upstream.

---

Built-in Tools

Tool	Description
read	Read a file or image (png/jpg/gif/webp auto-routed to vision)
write	Write or overwrite a file
edit	Replace an exact string in a file, with unified-diff preview
search	Search files using glob patterns, sorted by mtime
grep	Recursive regex content search
bash	Execute a shell command (60s timeout, output filtered)
view_image	Load a local image into the model's vision context
web_search	Search the live web via Bocha AI Search API
use_skill	Load an installed SKILL.md with its scripts/references
loop_engine	3-agent pipeline: implement → verify → refine (invoked via /loop)
attempt_completion	Final step — present the result to the user

Mangopi CLI can autonomously inspect files, modify code, search projects, and execute shell commands.

---

Skill System

Mangopi CLI supports reusable workflow skills.

Example structure:

~/.mangocli/skills/python_backend/

├── SKILL.md
├── scripts/
└── references/

Example SKILL.md:

---
description: Python backend workflow
tags: ["python", "backend"]
---

Use pytest for tests.
Prefer small functions.

The model can automatically discover and load relevant skills during execution.

---

Session Persistence

Sessions are stored locally:

.mangocli/session/session.json

Mangopi CLI automatically:

• restores previous sessions
• preserves important context
• compacts old conversations
• manages long-running workflows

---

Context Compacting

Mangopi CLI uses a three-tier compacting strategy that triggers automatically once context exceeds 80% of MANGO_MAX_CONTEXT:

Tier	Strategy	Scope
micro_compact	Head/tail truncation	Individual tool outputs and long assistant messages
session_memory_compact	Force-compact old turns	Drops the oldest turns, keeps last 10 turns in full
compact_conversation	Drop-while-overflow	Strips oldest turns first, then trims recent turns
full_compact	LLM-driven summary	Replaces the whole conversation with a structured recap (manual /c)

The compact pipeline is invoked by ContextManager.prepare_for_api() before every model call, so long-running autonomous workflows stay within the configured context budget without manual intervention.

---

Safety

Mangopi CLI enforces safety at two layers:

Dangerous command detection — the following patterns require explicit y/n confirmation before execution:

• File deletion — rm -rf, unlink
• Disk / partition — mkfs, fdisk, parted, dd if=... of=...
• Permission changes — chmod 777 (and similar *7*7* modes), chown ... root
• Privilege escalation — sudo rm, su -, su root
• Dangerous process control — kill -9 1, killall -9, pkill -9
• Environment tampering — export PATH=..., unset PATH, writes to /etc/
• History / log clearing — history -c, > /dev/null 2>&1

Path sandbox — write and edit resolve the target path with realpath and reject any file outside the project root. Operating on a directory path (rather than a file) is also rejected. This prevents the model from escaping the working directory.

---

Architecture

Core components:

Component	Responsibility
Printer	Terminal UI rendering (spinner, diff, tool call/result)
ContextManager	Conversation memory, three-tier compact, session save/restore
ToolBase	Tool framework (schema, confirm, before/after hooks, preview)
Provider	API abstraction (OpenAIProvider, DeepSeekProvider, MiniMaxProvider)
SystemPrompt	Layered runtime prompt assembly (base, safety, rules, tools, env)
SkillManager	Discovers and loads SKILL.md + scripts/references
loop_engine	3-agent pipeline (Implementer / Verifier / Updater) with persistent task sessions
agent_loop	Drives the read → think → tool-call → verify loop until the model stops or calls attempt_completion

---

License

Apache License 2.0

---

✨ Contributors

Contributor	Role
@BeWater799	💡 Inspiration for the Loop Engineering user prompt constraints

---

Author

Created by moofs.