MiniBot has been rewritten in TypeScript: Jiminyang1/minibot-ts. This repository holds the original Python version.
A local command-line AI agent runtime built on OpenAI-compatible chat.completions. A single-owner synchronous turn loop with tool calling, unifying local tools, MCP, Skills, and cross-session long-term memory; every runtime fact flows through one event stream to the CLI, the Web/SSE UI, and the run log.
- Token-level streaming: CLI typewriter and Web streaming bubbles (
message.deltaevents;message.completedstays authoritative) - Local + MCP tools behind one
Toolinterface (declarative concurrency/approval properties) - Append-only session persistence with automatic compaction (safe-cut-point summaries, read-only tool-block fallback)
- Structured
RuntimeEventas the sole output channel: CLI rendering, SSE Web UI, and runs.jsonl are all subscribers - Progressive skill disclosure (L1 metadata resident in the system prompt, L2 body on demand via
read_skill) - Cross-session user memory (
remember/forget) plus episodic memory (search_historysearches raw messages and compaction summaries across all past sessions) - Scheduled tasks and reminders: created in natural language (cron routines / one-shots), fired unattended by
minibot-daemon, delivered via macOS notifications and stored as searchable sessions - Sensitive-tool approval (
ask/always; CLI prompt or Web approval endpoint). Once web pages, search results or MCP output are in a session,rememberandfetch_urlto a URL that no user message or untrusted tool result showed also ask, so injected text cannot quietly persist or send data out - Quality loop: golden evals scored per stage (pytest, Langfuse dataset replay, LLM-as-judge) and an experimental lessons loop that mines failures, drafts fixes for human review and retrieves approved ones
- Reliability: exponential-backoff retries for transient LLM errors (never after the first delta), summariser failures degrade to truncation, tool args pre-validated against their JSON Schema
- MCP over
stdio/streamable_http; bundled SQLite demo and macOS system servers, draw.io MCP in the default config
Uses uv (Python 3.12):
cp .env.example .env # set OPENAI_API_KEY
uv sync
uv run minibotuv sync --extra data also installs pandas, matplotlib, openpyxl and tabulate, for scripts that the exec tool runs on artifacts. MiniBot itself does not import them, and a plain uv sync removes them again.
Web UI:
uv run minibot-server --host 127.0.0.1 --port 8765
# open http://127.0.0.1:8765/The server has no authentication. It accepts only loopback Host headers (localhost, 127.0.0.1, [::1]), which blocks DNS rebinding, and rejects writes that carry a foreign Origin. Binding a non-loopback --host prints a warning; add the names remote clients use with --allowed-host.
minibot opens a full-screen TUI (Textual) by default: scrollable conversation, Markdown-rendered replies, streaming, reasoning and tool calls collapsed into clickable one-liners, a bottom-pinned input, and an approval modal (y/n); Esc cancels the run, Ctrl+N starts a session. Slash commands work as usual.
The line REPL remains as minibot --plain (auto-fallback when piped): --verbose, --no-color, spinner status bar, typewriter streaming, and the collapsing reasoning preview all behave as before.
flowchart TB
subgraph entry [Entry]
CLI[CLI]
Web[Web / SSE]
end
subgraph core [Core]
AS[AgentSession]
AL[AgentLoop]
end
subgraph services [Services]
CB[ContextBuilder]
TB[TokenBudget]
CP[Compactor]
GATE[ToolApprovalGate]
end
subgraph infra [Infrastructure]
SM[SessionManager]
TRG[ToolRegistry]
MCP[MCPHost]
LLM[LLMClient]
end
subgraph subscribers [Event subscribers]
EV[(Event stream)]
FOLD[RunLogFold → runs.jsonl]
end
CLI --> AS
Web --> AS
AS --> AL
AL --> CB & TB & CP & GATE
AL --> LLM
AL --> TRG
AL --> SM
AL -. emit .-> EV
EV --> FOLD
EV --> CLI
EV --> Web
TRG --> Local[Local Tools]
TRG --> Proxy[MCPToolProxy]
Proxy --> MCP
Per-turn flow — AgentLoop.run_turn is the single owner; each iteration runs in order:
- Budget check (
TokenBudget); if over budget,Compactor.reduce(compact + persist + emit) ContextBuilder.buildassembles the request as a pure function (system prompt / memory / time / skills catalog + projected history)- Streamed LLM call (deltas publish as
message.deltaevents; the terminalLLMResponsedrives everything downstream) - Tool execution (approval via the injected
ToolApprovalGate; consecutive read-only tools run as a parallel batch) - Message append (session persistence + event); large outputs become artifact references via
ToolOutputMaterializer
Design constraints
| Principle | Detail |
|---|---|
| Single owner | run_turn reads top-to-bottom as one turn's full lifecycle; turn state lives only in loop locals |
| Orchestration vs mechanics | The loop only decides and delegates; mechanics live in named, independently testable components |
| One output channel | RuntimeEvent is the sole exit; runs
8000
.jsonl is RunLogFold's fold over the stream |
| Append-only session | messages.jsonl is the source of truth; compaction appends an entry and persists immediately |
| Projected view | SessionContextProjector derives model-visible messages (incl. interrupted results for cut-off tool calls) |
| Sync turn loop | Main loop is synchronous; MCP asyncio lives in background threads |
Deep dives: docs/architecture.md — layering rules, per-turn sequence diagram, the full event catalog, the compaction decision tree, error/cancellation/concurrency semantics; docs/core-philosophy.md — the judgment criteria behind this shape (both in Chinese).
| Path | Role |
|---|---|
bootstrap.py |
Composition root; wires the runtime |
runtime/agent_session.py |
Run lifecycle: session lock, cancellation, run.* events, event fan-out |
runtime/agent_loop.py |
The core loop (single owner) |
runtime/context_builder.py |
Pure request assembly |
runtime/budget.py |
Token budget and incremental estimation |
runtime/compactor.py |
Compaction mechanics + immediate persistence (cut-point rules in compaction.py) |
runtime/approval.py |
Approval policy and the injected approval gate |
runtime/run_log_fold.py |
runs.jsonl as a fold over the event stream |
session/ |
Append-only persistence + projection |
tools/ |
Local Tool implementations and ToolRegistry |
mcp_host/ |
MCP client, transports, MCPToolProxy |
mcp_servers/ |
Bundled SQLite / macOS MCP servers |
skills/ |
Skill metadata and Markdown bodies |
user_memory.py |
Global long-term memory |
evals/ |
Golden evals: sandbox, per-stage scoring, Langfuse dataset, pytest suite, trace promotion |
lessons/ |
Lessons loop: mining, clustering, drafting, review, retrieval |
cli.py / server.py |
CLI and Web entry points |
| Variable | Default | Description |
|---|---|---|
OPENAI_API_KEY |
— | required |
OPENAI_BASE_URL |
official | OpenAI-compatible endpoint |
MINIBOT_MODEL |
gpt-5.4-mini |
model name |
MINIBOT_CONTEXT_WINDOW_TOKENS |
model catalog | hard context-window override for unknown/compatible models |
MINIBOT_MODEL_MAX_INPUT_TOKENS |
model catalog | hard input-limit override when the provider has a separate cap |
MINIBOT_MODEL_MAX_OUTPUT_TOKENS |
model catalog | hard output-limit override for unknown/compatible models |
MINIBOT_MAX_OUTPUT_TOKENS |
4096 |
output ceiling actually sent to the provider on every request |
MINIBOT_APPROVAL_MODE |
ask |
ask / always |
MINIBOT_MAX_ITERATIONS |
20 |
max LLM↔tool rounds per turn |
MINIBOT_MAX_PARALLEL_TOOLS |
4 |
parallel tool cap per response |
MINIBOT_COMPACT_TOKEN_THRESHOLD |
model hard input limit | compaction policy threshold, not the model window |
MINIBOT_COMPACT_KEEP_RECENT_TOKENS |
16000 |
recent context kept after compaction |
MINIBOT_RESERVED_COMPLETION_TOKENS |
— | legacy alias for MINIBOT_MAX_OUTPUT_TOKENS |
MINIBOT_INCLUDE_REASONING_CONTENT |
auto |
reasoning-field passthrough (DeepSeek etc.) |
MINIBOT_STREAMING |
auto |
set 0/off to disable streaming (for endpoints with broken SSE) |
MINIBOT_LLM_MAX_RETRIES |
3 |
max retries for transient LLM errors (429/5xx/connection) |
MINIBOT_LESSONS |
auto |
auto (on when fastembed is installed and a lesson is approved) / on / off |
MINIBOT_LESSONS_TOP_K / MINIBOT_LESSONS_MIN_SCORE |
3 / 0.55 |
most lessons per request / cosine floor |
MINIBOT_EVAL_JUDGE_MODEL |
the tested model | model that grades the eval answer stage; pin it when comparing models |
MINIBOT_FETCH_VIA_JINA |
0 |
1 lets fetch_url try the Jina reader (r.jina.ai) first; better text extraction, but every fetched URL goes to that third party |
LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY |
— | setting both enables Langfuse tracing (one trace per turn: full requests, tools, approvals, compaction) |
LANGFUSE_BASE_URL |
EU cloud | Langfuse endpoint: your signup region, or a self-hosted URL |
MINIBOT_LANGFUSE |
1 |
0 keeps keys configured but disables tracing |
MINIBOT_LANGFUSE_MAX_INPUT_MESSAGES |
50 |
history messages uploaded per model call, after the system prompt (0 = all) |
MINIBOT_HOME |
~/.minibot |
global state home (sessions / run log / memory / mcp.json) |
Persistence — state is centralized globally (default ~/.minibot, override with MINIBOT_HOME). Conversations belong to the user, not to the launch directory; the workspace only roots the fs/exec tools and is recorded as session metadata:
~/.minibot/sessions/<id>/messages.jsonl— all sessions (append-only; meta records workspace provenance)~/.minibot/runs.jsonl— run summaries (fold of the event stream)~/.minibot/sessions/<id>/artifacts/— large tool outputs~/.minibot/user_memory.json— long-term memory
Legacy per-workspace .minibot directories migrate with one command (id collisions renamed, run logs merged):
uv run minibot --migrate <dir1> <dir2> ...Lookup order: MINIBOT_MCP_CONFIG_PATH → ~/.minibot/mcp.json → bundled mcp.json.
- Servers with
enabled: trueconnect and discover tools at startup; one failing server never blocks startup trusted: trueskips approval; MCP output still counts as untrusted content for the approval rules above- Transports support
${ENV_VAR},${MINIBOT_PYTHON},${MINIBOT_PACKAGE_DIR} - The bundled config includes
sqlite,macos_system, and an external draw.io MCP server launched vianpx -y @drawio/mcp
Say "generate my daily brief at 8 every morning" or "remind me to submit the report tomorrow at 9" in conversation — MiniBot calls schedule_task (approval-gated) and writes ~/.minibot/schedule.json. Firing needs the resident daemon:
uv run minibot-daemon # resident process; single-instance lock- Routines use five-field cron (local time); one-shot reminders use ISO timestamps
- Each firing creates a fresh
[定时]session (searchable viasearch_history) and posts a macOS notification - Missed firings catch up within a one-hour grace window (laptop lid, daemon downtime); older misses are recorded and skipped
- Unattended runs deny sensitive tools by default; set
MINIBOT_APPROVAL_MODE=alwaysfor the daemon at your own risk - Manage with
/tasks,/tasks cancel <id>, or plain natural language
Heartbeat: cron executes a fixed instruction on time; heartbeat wakes up and decides for itself. Say "patrol every 30 minutes" to create one (schedule_task with heartbeat mode): on each beat it reviews the ~/.minibot/HEARTBEAT.md checklist (inlined into the prompt) inside one persistent session, does what needs doing, and replies HEARTBEAT_OK to stay silent when nothing needs you — notifications fire only when something does. The checklist is plain Markdown (# lines are comments); the ever-growing session is kept in check by automatic compaction.
Evals measure the agent. The lessons loop (experimental) turns past failures into rules that a human approves. run --lessons compare is how to check whether approved lessons help. With ten cases run once each, one flip is ten points of noise, so add --repeat N: each case then has a pass count per mode, and the report separates cases that always pass, always fail, or pass only sometimes.
Golden evals (evals/). Cases live in evals/cases.json, mirrored to the Langfuse dataset minibot-golden. Each case runs one sandboxed turn and is scored per stage: skill selection → tool selection → tool arguments → answer (LLM-as-judge) → outcome.
uv run python -m minibot.evals run # every case; prints the first failing stage per case + trace URL
uv run python -m minibot.evals pytest -k tool_args # pytest, one test per (case, stage); replays the Langfuse dataset
uv run python -m minibot.evals traces --failed # recent real runs that went wrong
uv run python -m minibot.evals promote <trace_id> # turn a real run into a case: recorded tool outputs replay in the sandbox
uv run python -m minibot.evals run --lessons compare # same cases with lessons off and on: pass rates, flips, calls/tokens/latency
uv run python -m minibot.evals run --repeat 3 # the same cases three times: pass / flaky / fail per case, pass-rate range
uv run python -m minibot.evals run --repeat 3 --baseline <run> # also compare with a saved run: stage rates, cost, cases that got worse + trace
uv run python -m minibot.evals compare <base> <new> # the same comparison between two saved runsEvery run saves its scored rows (repeats pooled) as $MINIBOT_HOME/evals/<run>.json; that run name is what --baseline and compare take. Only cases present in both runs, with the same definition, are compared; a case whose input or expectations changed in between is listed instead, and a change in the scoring code is flagged. Each run also records a hash of every prompt, skill and tool definition the model is shown, so the report lists the parts whose text changed and, for each case that got worse, the changed parts it used (the place to look first). A change of judge is flagged too: the answer stage is graded by MINIBOT_EVAL_JUDGE_MODEL (default: the tested model), so pin it before comparing two models. Each row of runs.jsonl also records the lessons its requests carried and, with Langfuse on, its trace id.
The pytest suite calls the real model, so it only runs with -m golden (the pytest subcommand adds it); plain pytest collects unit tests only.
Lessons (lessons/, needs uv sync --extra lessons) — experimental. A lesson is a human-approved rule: when , do . It has not run on real failures yet, and its thresholds come from a small hand-written set; uv run python -m minibot.lessons.benchmark re-measures them.
uv run python -m minibot.lessons mine --dry-run # failures found in sessions and runs.jsonl, clustered
uv run python -m minibot.lessons mine # the LLM drafts one lesson per cluster
uv run python -m minibot.lessons review # approve / edit / reject each draft
uv run python -m minibot.lessons list --status approvedMining reads failed tool calls, failed or exhausted turns, denied approvals and user corrections ("不对", "wrong"). Incidents are clustered with a local embedding model (BAAI/bge-small-zh-v1.5, about 90 MB, cached under ~/.minibot/models); no data leaves the machine and there is no vector database. At request time, each user message gets the approved lessons whose trigger or evidence requests match it, appended to that message. Never the system prompt, and never only the latest message: a message must read the same in every request, or the prompt cache loses the turn that follows it. model.request.started names the lessons in the request. Only approved lessons are ever injected: drafts are mined from tool output and web text, so the review step is also the prompt-injection gate.
/sessions · /new · /resume <id> · /delete <id|current> · /compact · /mcp · /mcp tools [server] · /memory [clear|forget <id>] · /skills · /tasks [cancel <id>] · /permission [ask|always] · /config · /help
| Method | Path | Description |
|---|---|---|
POST |
/runs |
create a run, returns run_id |
GET |
/runs/{run_id}/events |
SSE with Last-Event-ID replay |
POST |
/runs/{run_id}/cancel |
cancel a run |
POST |
/runs/{run_id}/approvals/{approval_id} |
resolve a tool approval |
GET |
/sessions |
list sessions |
GET |
/sessions/current |
current session |
POST |
/sessions |
create and switch the current session |
GET/PATCH/DELETE |
/sessions/{id} |
read, retitle, delete a session |
GET |
/sessions/{id}/messages |
conversation history |
Disconnecting from SSE only cancels the subscription, not the background run.
uv run python -m unittest discover -s tests
uv run ruff check .Event names and payloads are the stable contract shared by the CLI, SSE, and the run log; consult the event catalog in docs/architecture.md before changing them.