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?

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 (multi-agent implement / verify / refine pipeline)
• Sparse loop — MailBox collective memory for cross-session task persistence (--sparse)
• Smart provider routing with tiered models (high/medium/low)
• 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 git@github.com: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

/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 configurable Step/Pipeline:

Modes:

The pipeline runs up to 5 iterations, short-circuiting on the first VERIFY: PASS. All agents return structured results via attempt_completion.

Sparse Loop (MailBox Collective Memory)

The --sparse HANDLE flag extends loop with cross-session collective memory via the MailBox system:

# Start a task with sparse mode
/loop data cleaning pipeline --sparse @agent-a --task-id clean-v1

# Resume the same task hours or days later — agents inherit full history
/loop continue cleaning --sparse @agent-a --task-id clean-v1

When --sparse is set:

• Each task gets a MailBox group (gid = task-id)
• All pipeline agents (DesignAgent, DevAgent, ReviewAgent, TestAgent) share the same group as persistent thread
• Agents are prompted to:
  1. Start → mailbox_read previous progress before acting
  2. Claim → mailbox_post what they're about to do
  3. Update → mailbox_post at key milestones ([State], decisions, blockers)
  4. Finish → mailbox_post [Result] to mark completion for the next agent
• Same --task-id across separate CLI invocations → agents automatically see the full history

This turns loop from a stateless pipeline into a collaborative engine where agents and humans coordinate asynchronously across time.

Built-in Tools

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:

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:

License

Apache License 2.0

✨ Contributors

Author

Created by moofs.