Mini-Code-Agent

A terminal-based coding agent inspired by Claude Code — built from scratch in Python, fully open-source, and designed to be readable.

中文文档 (Chinese)

Why Mini-Code-Agent?

Features

🔧 12 Built-in Tools — read/write/edit/delete files, bash, glob, grep, spawn agents, send/wait message, tool_search, mcp_call

🤖 Multi-Agent — /spawn parallel agents, /spawn --pane visible terminal-pane workers (tmux / Windows Terminal, separate processes), /team auto-planned orchestration, strong/weak model mixing, cross-agent mailbox messaging (send_message / wait_message)

💰 Cost Dashboard — per-model input/output pricing, session + all-time ledger, budget warnings at 80%/100%

⏪ Undo & Fork — /undo rolls back conversation AND file changes; /fork branches into a new session

🎬 Record & Replay — /record captures tool sequences, /replay re-runs them with zero LLM calls + {{template}} variables

🧠 Memory — LLM auto-extracts preferences at session end, injects them next session; manual /memory add too

📋 Persistent Tasks — /todo with dependency tracking (--after), survives restarts

🔌 MCP Protocol — stdio + HTTP + SSE transport, connect any MCP-compatible tool server via config; loading = "dispatch" for lazy discovery

🔒 OS Sandbox — Linux bubblewrap + macOS seatbelt kernel-level isolation (optional [security] sandbox = true)

🎨 Themes — dark/light/default, markdown heading colors follow theme

🔍 Transparency — /trace shows every agent decision in real time (phases, permissions, tool timing, LLM metadata)

📚 Teaching & Audit — /explain shows why each tool is called; /audit logs all actions with hash-chain tamper detection

💾 Session Management — auto-save with crash recovery, /session tag/list --tag classification, /fork branching

🌳 Worktree Isolation — /spawn --isolated runs agents in separate git worktrees (parallel file changes don't conflict)

📄 Context-Aware — auto-reads CLAUDE.md / AGENT.md project instructions at startup; @file inline references with Tab completion

Quick Start

Install

pip install mini-code-agent

Or from source:

git clone https://github.com/ccxxxyy/mini-code-agent.git
cd mini-code-agent
uv sync
uv run mini

Configure

Set your LLM API key (any OpenAI-compatible provider):

# Environment variable
export OPENAI_API_KEY="sk-..."
export OPENAI_BASE_URL="https://api.deepseek.com/v1"  # optional: non-OpenAI provider

# Or .env file (auto-loaded)
echo 'OPENAI_API_KEY=sk-...' > .env

# Or CLI
mini --api-key "sk-..." --base-url "https://api.deepseek.com/v1" --model "deepseek-chat"

Run

mini          # start the agent
mini --help   # see all options

See docs/terminal-guide.md for how to open each terminal per OS and their compatibility levels.

Remote / Browser Mode

Use the agent from a browser instead of the terminal — works on remote servers, iPads, or any device with a browser.

# 1. Install with remote support
pip install mini-code-agent[remote]
# Or from source:
uv sync --extra remote

# 2. Start in remote mode (from any working directory)
cd /path/to/your/project
mini --remote

# 3. Open browser
#    Terminal shows: Browser: http://localhost:8765
#    Open that URL in your browser

The agent works on whatever directory you run the command from — just like terminal mode.

Running from any directory (if installed globally):

# Global install (once)
cd /path/to/mini-code-agent
uv tool install . --extra remote

# Then use anywhere
cd ~/my-project
mini-agent --remote
# Browser: http://localhost:8765

Custom host/port:

mini --remote --host 0.0.0.0 --port 9000
# Browser: http://0.0.0.0:9000

# With token authentication:
mini --remote --remote-token "my-secret"
# Browser: http://localhost:8765?token=my-secret

Commands

Full syntax, flags and examples for every command: docs/commands-guide.md

Configuration

All settings via ~/.mini-agent/config.toml (user) or .mini-agent/config.toml (project):

[llm]
model = "deepseek-chat"
provider = "openai"       # "openai" | "openai-responses" (o1/o3/o4-mini) | "anthropic"
temperature = 0.0

[cost]
budget = 5.0
[cost.pricing.deepseek-chat]
input = 2.0
output = 8.0

[mcp.servers.github]
url = "http://localhost:8080/mcp"
transport = "http"
headers = { Authorization = "Bearer ghp_..." }

See config.toml.example for all options. Full guide: docs/config-guide.md.

Architecture

mini-code-agent/
├── src/mini_agent/
│   ├── core/        # Agent loop, state, sub-agents, teams, planner, mailbox, pane worker, cost tracker, task store, tool recorder, agent types, spawn backends
│   ├── tools/       # 12 built-in tools + MCP protocol (stdio/HTTP/SSE, eager/dispatch) + hook system
│   ├── memory/      # Context compression (4-stage cascade), persistent memory, session store, extraction, recall, consolidation, file snapshots, spill cache, project context
│   ├── security/    # Permissions, path guard, audit, OS sandbox (bwrap/seatbelt), worktree isolation, remote confirm (cross-process)
│   ├── ui/          # Rich terminal, streaming renderer, input handler, components, themes, trace, teach, progress board, double-Esc watcher
│   ├── remote/      # WebSocket server + browser UI (--remote mode, disconnect queuing)
│   ├── extensions/  # Slash commands (26), skills (4 built-in), hooks (11 stages), event listener + tool/command/skill plugins
│   ├── llm/         # Provider abstraction: OpenAI Chat Completions + Responses API + Anthropic, token counter
│   ├── events/      # EventBus — async pub/sub decoupling all layers (5 subscribers, 17 subscriptions)
│   ├── config/      # Layered config loading (TOML + env + CLI), shell/platform detection
│   └── models/      # Dataclasses (messages, events, config, sessions, permissions)
├── tests/           # 969 tests, 80%+ coverage
├── skills/          # 4 built-in skill packs
├── experiments/     # 10 mechanism experiments (compression A/B, model mixing, deadlock induction, circuit breaker)
├── examples/        # Example plugins (drop into ./.mini-agent/plugins or declare a mini_agent.plugins entry point)
└── docs/            # 15 documentation files (incl. agent-architecture.md, comparison-mewcode.md)

Design philosophy: Five layers (UI → Engine → Tools → Memory → Security) + remote/extensions/llm/config/models, decoupled via EventBus. All I/O is async. Zero vendor SDK — just httpx.

S01–S20 Coverage

This project implements 19 of 20 mechanisms from the learn-claude-code harness checklist. See docs/agent-architecture.md for a deep dive into what each layer solves and why.

✅ S01 Agent Loop · S02 Tool Use · S03 Permission · S04 Hooks · S05 Planning · S06 Subagent · S07 Skill Loading · S08 Context Compression · S09 Memory · S10 System Prompt · S11 Error Recovery · S12 Task System · S13 Background Tasks · S15 Agent Teams · S16 Team Protocols · S17 Autonomous Agents · S18 Worktree Isolation · S19 MCP Plugin · S20 Comprehensive Agent

⬚ S14 Cron Scheduler — intentionally skipped (OS-level cron/Task Scheduler is more appropriate for a terminal tool)

Development

uv sync --extra dev
uv run pytest tests/           # 969 tests
uv run ruff check src/ tests/  # lint
uv run ruff format src/ tests/ # format

See docs/tasks.md for the full development history (P1–P83, 83 phases).

Publishing to PyPI

git tag v1.1.0
git push origin v1.1.0
# GitHub Actions auto-publishes via Trusted Publisher

First-time setup: register at pypi.org, add Trusted Publisher for ccxxxyy/mini-code-agent → publish.yml.

License

MIT