# Mangopi CLI

CI PyPI Python License
Stars Release Downloads Last commit

![Mangopi CLI demo](./mangopi-demo.gif) > 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 * ACP agent server (`--acp`) — Agent Client Protocol v1 over stdio, connectable from Zed / JetBrains etc. * Multimodal support (image reading via `view_image` extension) * Web search via Bocha AI Search (`web_search` extension) * 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`) * Extension system — per-preset dirs: `~/.mangocli/presets//` (`conf.py` + `extensions/`), activated via `MANGO_PRESET` * Safe shell execution checks * Fully hackable and easy to extend * Large-context optimized runtime --- # Installation ## From PyPI ```bash pip install mangopi-cli ``` Start Mangopi CLI: ```bash mangopi-cli ``` --- ## From Source ```bash git clone git@github.com:w4n9H/mangopi-cli.git cd mangopi-cli python mangopi_cli.py ``` --- # Configuration Required: ```bash export MANGO_KEY="your_api_key" ``` Recommended: ```bash export MANGO_API_URL="https://api.deepseek.com" export MANGO_MODEL="deepseek-v4-flash" ``` Optional: ```bash export MANGO_MAX_CONTEXT=1000000 # default 1,000,000 tokens export MANGO_LANG=en # en (default) | zh — controls UI text and CLI help language ``` --- --- # Supported Providers Mangopi CLI supports: * DeepSeek * OpenAI-compatible APIs * MiniMax * Custom compatible endpoints Example: ```bash export MANGO_API_URL="https://api.openai.com/v1" export MANGO_MODEL="gpt-4o-mini" ``` --- # Usage Start the CLI: ```bash mangopi-cli ``` or: ```bash 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 | | Flag | Description | |------|-------------| | `--acp` | Run as ACP (Agent Client Protocol) v1 agent server over stdio (JSON-RPC) | --- ## ACP Agent Server (`--acp`) Run mangopi as an **Agent Client Protocol v1** agent over stdio — a resident JSON-RPC server that ACP-capable editors (Zed, JetBrains, codecompanion.nvim, etc.) can launch as a subprocess: ```bash mangopi-cli --acp ``` The client drives the conversation via `session/new` + `session/prompt` messages; mangopi executes tools locally, streams progress via `session/update` notifications, and asks for permission through `session/request_permission` (rendered as a client-side prompt). One `session/prompt` = one turn; `session/cancel` ends the current turn. # Built-in Tools | Tool | Description | |----------------------|-------------------------------------------------------------------| | `read` | Read a text file (use `view_image` extension for images) | | `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) | | `attempt_completion` | Final step — present the result to the user | `web_search` / `view_image` are shipped as optional extensions (`examples/extensions/`) since v0.1.49; `use_skill` (skill system: `SkillManager` + `skills_guidance` prompt section) ships as the `skill` extension since v0.1.53; MCP servers join the tool registry as `mcp__` proxy tools via the `mcp` extension since v0.1.54 (see `examples/extensions/mcp.py` for config). Mangopi CLI can autonomously inspect files, modify code, search projects, and execute shell commands. --- # Skill System Mangopi CLI supports reusable workflow skills (shipped as the `skill` extension, `examples/extensions/skill.py` — enable by copying/symlinking into `~/.mangocli/extensions/` or a preset's `extensions/` dir). Example structure: ```text ~/.mangocli/skills/python_backend/ ├── SKILL.md ├── scripts/ └── references/ ``` Example `SKILL.md`: ```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. --- # Extension System Mangopi CLI is extensible via per-preset directories: each preset `` lives at `~/.mangocli/presets//` with a `conf.py` (total config: `keep_tools` whitelist, `unload_sources`) and an `extensions/` folder holding extension files — set `MANGO_PRESET=` to activate it. Without `MANGO_PRESET` the CLI runs pure built-in tools (no extensions). Extensions shipped with the repo live in `examples/extensions/`; enable them by copying/symlinking into `~/.mangocli/presets//extensions/`. Each file may export any combination of three channels (all optional): | Channel | Export | Effect | |---|---|---| | Tools | `tools` | `ToolBase` instances join the built-in registry — visible in the LLM tool schema, dispatched through `run_tool`, available in ACP mode; same-name tools override built-ins (extension wins) | | Prompt sections | `prompt_sections` | `(name, content)` pairs injected into the system prompt: a name matching a default section (`base_intro` / `safety` / `builtin_rules` / `tool_guidance` / `skills_guidance` / `memory` / `environment`) overrides it (enhancement); a new name appends after `environment` | | Entry points | `entry_points` | `name -> Callable[[], int]` registry (same-name: first file in scan order wins); the built-in `--acp` flag dispatches to `entry_points["acp"]` when present | Contract: extension top-level code may `import` but must not access `mangopi_cli` attributes — the scan runs during module import, when the module is only half-initialized (importing `ToolBase` at top level is fine; everything else goes inside function bodies). Extensions run arbitrary Python code, so only install from trusted sources. A broken extension logs a diagnostic and is skipped without affecting others. ### Tools channel ```python # ~/.mangocli/presets//extensions/hello.py from mangopi_cli import ToolBase class HelloTool(ToolBase): name = "hello" description = "Say hello" params = {"name": {"type": "string", "description": "Who to greet"}} def run(self, args): return self.ok("Hello, %s!" % args.get("name", "world")) tools = [HelloTool()] ``` ### Prompt sections channel ```python # ~/.mangocli/presets//extensions/prompt_sections.py prompt_sections = [ # Same name as a default section ("safety") → overrides it (enhancement) ("safety", "## Safety\n\n" "Destructive commands and any access outside the project root require explicit user confirmation.\n" "Never delete data without asking first.\n"), # New name → appended after all default sections ("project_note", "## Project Note\n\n" "This project is managed with mangopi-cli. Keep commits small and focused.\n"), ] ``` ### Entry points channel ```python # ~/.mangocli/presets//extensions/entry_points.py import mangopi_cli # top-level: import only, no attribute access (import-time scan) def hello_serve() -> int: # Lazy import: the module is fully initialized by the time this runs from mangopi_cli import __version__ print(f"hello_serve: mangopi-cli v{__version__} entry point invoked") return 0 entry_points = {"hello": hello_serve} ``` ### Presets (total config) Each preset `` is a directory `~/.mangocli/presets//` with an optional `conf.py` (total config applied at startup) and the `extensions/` folder above. Set `MANGO_PRESET=` to activate; **without it the CLI runs pure built-in tools (no extensions)**. The banner shows the active preset and tool count, e.g. `... | minimal[2 tool]`. ```python # ~/.mangocli/presets/minimal/conf.py preset = { "name": "minimal", "description": "Benchmark mode: bash + edit only, one-line system prompt", "keep_tools": ["bash", "edit"], # optional: "unload_sources": ["clipboard.py", "git_status.py"], # optional: prompt overrides (v0.1.50 mode system) "prompt_overrides": { "base": "You are a helpful software engineer assistant.", # replaces the base_intro section "clear_sections": ["safety", "builtin_rules", "tool_guidance", # removes sections "skills_guidance", "memory", "environment"], # "append_sections": [{"name": "custom", "content": "..."}], # appends sections }, } ``` * `keep_tools` — whitelist: `TOOLS` keeps only the listed tools (built-in + extensions unified); the inverse is registered under the `__preset__` slot, `unload_source("__preset__")` restores * `unload_sources` — optional: reversibly unload extension registrations (three channels), combinable with `keep_tools` * `prompt_overrides` — optional: `base` replaces the `base_intro` section, `clear_sections` removes sections, `append_sections` appends new ones (see Run Modes below) * Applying a preset emits the `preset:applied` event (extensions such as `trace.py` can listen) ## Run Modes Mangopi CLI ships three run-mode presets in `examples/presets/` (copy a directory into `~/.mangocli/presets/` to enable). Modes are a preset-level combination of tool whitelist and system-prompt overrides, modeled after DeepSeek Harness: | Mode | Tools | System Prompt | Use case | |---|---|---|---| | `standard` | 8 core tools | Full layered assembly | Daily development (same as no preset) | | `minimal` | `bash` + `edit` only | One line | Model benchmark / capability baseline | | `codemode` | `run_code` + `attempt_completion` | Full + SDK declarations | Batch operations with fewer round-trips | ```bash export MANGO_PRESET=minimal # or: standard / codemode mangopi-cli ``` * `standard` — the default behavior made explicit: 8 core tools and the complete layered system prompt. * `minimal` — strips every peripheral enhancement (safety rules, tool guidance, skills, memory, environment) to purely measure the model's autonomous planning, code editing and terminal capability. Mirrors DeepSeek Harness minimal mode (`bash` + editor only, one-line persona). * `codemode` — Programmatic Tool Calling (PTC): `run_code` is the only directly callable file/shell tool; the six tools (`read`/`write`/`edit`/`search`/`grep`/`bash`) are reached from inside the program — the model writes one Python script orchestrating multiple tool calls in a single execution. Intermediate tool results stay out of the conversation — only `print` output flows back, cutting token usage and model round-trips. The code-only instruction and SDK declarations are declared in `examples/presets/codemode/conf.py` via `prompt_overrides.append_sections`. **Security note**: `run_code` executes in a restricted scope — whitelist builtins (no `__import__`/`open`/`eval`/`exec`/`globals`), only six tool APIs bound (`read`/`write`/`edit`/`search`/`grep`/`bash`), a SIGALRM timeout (30s, main thread only), and output truncation. Tool calls inside the script inherit the core safety checks (path sandbox, dangerous-command detection). This is a reasonable guardrail for model-generated scripts, not a hard sandbox. ### Shipped extensions The repo ships 17 optional extensions in `examples/extensions/` (copy/symlink into `~/.mangocli/presets//extensions/` to enable; without `MANGO_PRESET`, `~/.mangocli/extensions/`): | File | Function | |---|---| | `acp.py` | ACP v1 agent server over stdio (`mangopi-cli --acp` dispatches to `entry_points["acp"]`) | | `ask_user.py` | Structured multi-choice questions to clarify requirements | | `clipboard.py` | System clipboard read/write (macOS / Linux) | | `debug.py` | Per-call args/results debug prints (event bus) | | `git_status.py` | Read-only git status/log/diff summaries | | `mcp.py` | MCP client: community MCP servers as proxy tools (`mcp__`, native inputSchema passthrough; stdio + Streamable HTTP; manifest cache with config fingerprint; self-healing reconnect; config `~/.mangocli/mcp_servers.json`) | | `memory.py` | Long-term memory: AGENT.md / MANGO.md + per-day journals, auto-injected into the prompt | | `multi_edit.py` | Apply N Edit operations in one call with best-effort rollback | | `plan_mode.py` | Plan-then-execute state machine (read-only tool subset while active) | | `ratelimit.py` | Sliding-window rate warning (event bus, warn only) | | `run_code.py` | Code Mode / PTC tool: batch tool orchestration in one execution (used by the `codemode` preset) | | `skill.py` | Skill system: `use_skill` loads `SKILL.md` + scripts/references; dynamic `skills_guidance` prompt section (moved out of core in v0.1.53) | | `task_tracker.py` | In-session task tracking (create/list/update/get/delete), auto-injected into the prompt | | `trace.py` | Session event stream to `~/.mangocli/traces/run_*.json` (replaces core MANGO_TRACE; includes tool errors) | | `view_image.py` | Local image into vision context | | `web_fetch.py` | Fetch a URL's content into context (http/https only) | | `web_search.py` | Live web search via Bocha AI Search (`MANGO_SEARCH_API_KEY`) | --- # Session Persistence Sessions are stored locally: ```text .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) | | `AcpServer` | ACP (Agent Client Protocol) v1 server: stdio JSON-RPC dispatch, sessions, permissions | | `agent_loop` | Drives the read → think → tool-call → verify loop until the model stops or calls `attempt_completion` | --- # License Apache License 2.0 --- --- # Author Created by moofs.