mini-code-cli
A minimal coding agent CLI
No bloat, no dependencies, no tracking, no telemetry...
Purpose: a no-bloat, minimal coding CLI to enjoy experimenting and researching!
Install · Quick start · Modes & safety · Options · Tools · Sub-agents · In-session commands · Development · Docs · Citation
Install
pip3 install mini-code-cli
- PyPI: https://pypi.org/project/mini-code-cli/
- Python:
>= 3.10· runtime dependency:requestsonly - From source / contributing: see docs/README_DEV.md
Quick start
1 — Local model (e.g. vLLM or SGLang on port 30000; see serving a model locally):
mini-code # talks to http://0.0.0.0:30000/v1
2 — Hosted / custom API:
export MINI_CODE_API_KEY="sk-YOUR_API_KEY"
mini-code --url "https://api.deepseek.com" --model "deepseek-v4-flash"
3 — The shortcuts (plan mode, sub-agents, shell, auto-mode, no permission prompts):
mini-code --all # = --plan --enable-subagents --enable-shell --skills --auto-mode --sudo --background
mini-code --all-last # ...and continue your last session
4 — A first prompt:
Write an agent.md file for me that helps an LLM write efficient triton kernels,
given a reference implementation.
Command-line options
| Option | Default | What it does |
|---|---|---|
--url URL |
http://0.0.0.0:30000 |
API host |
--model MODEL |
— | model name |
--api-key KEY |
$MINI_CODE_API_KEY |
API key for authentication |
--max-tokens N |
— | reply budget; also the output headroom used when deriving the compaction limit |
--temperature T |
1.0 |
sampling temperature |
--system-prompt TEXT |
built-in | replace the system prompt (an --agent-md file is appended after it) |
--prompt TEXT |
— | initial user prompt |
-a, --auto-mode |
off | keep querying the model and running tools until no tool calls remain |
--agent-md FILE |
— | append an agent.md file after the system prompt (e.g. ./skill.md) |
--ask-permission |
off | ask before every tool call, including an ALLOW-tier shell command (--sudo disables all prompts) |
--sudo |
off | dangerous: never ask. DENY-tier commands are still refused |
--allowed-dir DIR |
./ |
sandbox for file tools (does not restrict the shell) |
-s, --enable-shell |
off | allow shell execution (classifier always applies) |
-g, --enable-subagents |
off | expose sub-agents as tools |
--background |
off | enable background shell/sub-agent tasks and the background tool; needs --enable-shell or --enable-subagents |
--tui [auto|on|off] |
auto |
fixed full-screen dashboard. auto enables it only on a known interactive TTY; on forces it; off uses the scrolling console |
--skills |
off | enable the .mini skills directory (skill.mds, SKILLS.md, runnable scripts). run_skill executes those Python scripts — arbitrary code execution, even without --enable-shell; only enable it for a directory you trust |
-p, --plan |
off | plan mode (CURRENT_GOAL.md / CURRENT_PLAN.md, printed plan, /plan, /skip-plan) |
--plan-strategy NAME |
plan-verify-step |
plan-verify-step, plan-verify or open-plan (implies --plan) |
--scratchpad |
off | give the agent a free-form .mini/SCRATCHPAD.md (plus further scratch files) for thoughts, plans and learnings |
--compaction-strategy NAME |
summarise |
summarise, predict-files or predict-messages |
--llm-timeout S |
500 |
HTTP timeout for LLM requests |
--tool-timeout S |
120 |
timeout for a single tool call |
--max-context-tokens N |
derived | input-token budget before the history is compacted |
--cache-dir DIR |
~/.cache/mini/sessions/ |
where session histories are stored |
--restore-session PATH |
— | continue a specific previous session |
-l, --load-last-session |
off | continue the session recorded in the .mini pointer |
--all |
off | --plan --enable-subagents --enable-shell --skills --auto-mode --sudo --background |
--all-last |
off | --all + --load-last-session |
--verbose |
off | print full detail (default: user/assistant turns, token usage, tool calls only) |
-h, --help |
— | show the built-in help |
Available tools
The agent can call a small set of tools, all defined in mini_code_cli/tools.py. Every
parameter a model does not need is defaulted, so omitting it keeps the previous behaviour.
| Tool | What it does |
|---|---|
read_file |
read a file; offset (1-based line) and limit page through large files. Output is capped at 100k characters, so page or narrow instead of relying on a whole-file read |
write_file |
write/overwrite; append adds to the end, create_dirs creates parents |
edit |
replace an exact string (old_string → new_string); refuses a missing or ambiguous match unless replace_all |
grep |
regex search a file or directory; recursive, include, ignore_case, line_numbers, max_results (noise dirs skipped). Output is capped at 100k characters |
glob |
list files matching a glob (one per line, ** supported), optionally against a root; capped at 2000 matches / 100k characters |
web_search |
best-effort lookup: related queries + a short Wikipedia extract. Never raises |
read_website |
fetch raw text/HTML of a public http/https URL (other schemes and private/link-local hosts are rejected; MINI_CODE_ALLOW_PRIVATE_URLS=1 overrides); max_chars caps size |
run_shell_command |
run a shell command (needs --enable-shell); cwd, timeout, and stdout/stderr/exit code are all reported |
background |
start/list/output/wait/cancel background shell tasks (needs --background --enable-shell) or sub-agent tasks (needs --background --enable-subagents); output is captured in a per-task log |
Sub-agents
--enable-subagents lets the main agent delegate a focused task to a sub-agent, exposed to
the model as an extra tool. A sub-agent is a self-contained, narrowed agent: it runs unattended
in auto-mode, in its own isolated session folder, and hands back a short text result (plus an
optional report.md). It reuses all the existing machinery — tools, the shell-safety
classifier, the --allowed-dir sandbox, compaction and --plan — and cannot spawn further
sub-agents.
mini-code --enable-subagents # the available sub-agents then show up in /help
| Sub-agent | What it is for |
|---|---|
research |
read-only web research: searches, reads a few sources, returns a sourced summary. Can only use web_search / read_website — never the filesystem or shell. Optional sources hint (e.g. "wikipedia.org only") |
planner |
drafts or refines a step-by-step plan for a goal; always runs in plan mode |
software_engineer |
writes, edits, refactors, fixes and tests code; can run shell commands (tests, builds) to verify |
generic |
general-purpose helper for anything that fits no narrower agent |
Adding your own sub-agent
A sub-agent is just a small class — subclass SubAgent and register it:
# my_subagents.py
from mini_code_cli.subagents import SubAgent, register
class SummarizeSubAgent(SubAgent):
name = "summarize"
description = "Summarize a piece of text the main agent provides."
tools = ["read_file", "write_file"] # restrict the nested agent's tools
enable_shell = False
max_steps = 5
register(SummarizeSubAgent())
Make sure the module is imported (e.g. import my_subagents) and it is discovered and exposed
to the model automatically when --enable-subagents is set. See
mini_code_cli/subagents/builtin.py for every knob and
docs/ARCHITECTURE.md (sections 2–3) for the design.
Background tasks
When --background is enabled together with shell execution or sub-agents, the agent also gets a background tool:
background(action="start", command="pytest -q")starts a long command in its own process group;background(action="start", kind="subagent", subagent="software_engineer", task="...")starts a nested agent task;list,output,waitandcancelinspect or control the tasks.
Each task has an id (bg-1), a status, a log under the session folder
(background/bg-1.log), an output tail, and a cancellation path. Shell tasks are killed as a
process group; sub-agent tasks receive a cancellation event between steps. Background tasks are
session-local and do not survive a restart (the logs do).
Use /background to see the foreground activity and all tasks, or /background bg-1 for one
task's output. Note that the main loop is synchronous, so /background can be typed between
steps; it shows the last/current blocking activity rather than live-during the call.
In-session commands
| Command | What it does |
|---|---|
/history |
list the conversation (turn number, what happened, where) |
/history <n> |
show the full messages recorded for turn n |
/history last |
...for the most recent turn |
/reset [<n>] |
rewind to the end of turn n (last works too); drops everything after it |
/clear |
clear the screen (keeps the conversation history) |
/plan |
show the current goal + plan (plan mode only) |
/context |
show how the context window is used: tokens and percentages by category (system prompt, user/assistant messages, tool calls/outputs, reasoning, overhead) |
/background [id] |
show foreground activity + background tasks, or one task's output tail |
/expand [n] |
show the full detail of the nth most recent tool call (default: the last one) |
/skip-plan <prompt> |
send <prompt> once without generating or reviewing a plan |
/help |
show this help |
/quit, /exit |
save the session and exit |
Multi-line input: press Shift+Enter (or Ctrl-J) to insert a newline; plain
Enter sends the turn. This works in the session prompt and the startup tip
reminds you. Terminals that report Shift+Enter as a CSI-u/modifyOtherKeys
sequence are recognised; elsewhere Ctrl-J inserts the newline.
With --tui, mini-code switches to a fixed alternate-screen dashboard: a
Mini-Code summary box (version/session/model/context) at the top, a core
conversation view of user/assistant turns in the middle, and an input box with
a one-line help hint at the bottom. The whole screen is redrawn on changes, so the view never
scrolls; tool/thinking status is a transient line that disappears when the
operation finishes. Shift+↑/Shift+↓ scroll the middle pane one line at a
time and show (lines scrolled / total); Esc returns to the bottom or closes
command output (/help, /history, ...). Info/warnings sit below a small
separator at the bottom of the body. The dashboard is coloured when the
terminal supports it; info/warnings/errors are shown as coloured
ℹ/⚠/✖/✔ lines. Each assistant block also carries a dim line with
that turn's tool calls, background tasks and assistant-message count.
Questions (resume/permission) use a yellow "Question to User" box just above
the input. Restored sessions load their history into
the core view and mark the summary as [restored]; generated plans append to
the core view. Tool details can be expanded with /expand [n].
The prompt has a small line editor: ↑/↓ recall previous turns, ←/→ move
the cursor, Home/End jump within the line, and Ctrl-A/E/K/U/L provide the
usual editing/clear shortcuts. --tui defaults to auto (known TTY only); use --tui=off for the old
scrolling console or --tui=on to force it. It is not part of --all.
Development
Linting, the test suite, CI and the release process are documented in docs/README_DEV.md.
python3 scripts/lint.py # lint (standard library only)
python3 -m unittest discover -s tests -p "test_*.py" # run the test suite
Releases are cut by tagging main: pushing a v* tag triggers
.github/workflows/release.yml, which builds the sdist + wheel,
verifies them with twine check, and attaches them to a new GitHub release.
Documentation
Everything beyond this README lives in docs/:
| Document | What it covers |
|---|---|
| docs/README_DEV.md | developer guide — local setup, repository layout, linting, the test suite, CI and the release / PyPI upload process |
| docs/ARCHITECTURE.md | design — module layout, on-disk conversation state (history_{n}.json, summary_history.json, usage files), the sub-agent framework and how to extend it |
This README stays the user-facing entry point (install, CLI flags, tools, sub-agents, in-session commands, modes & safety); the two documents above go deeper on the developer and design side.
Modes & safety
Shell execution — -s / --enable-shell
Everything the agent runs from the shell first passes a safety classifier that sorts the command into one of three tiers:
| Tier | Examples | What happens |
|---|---|---|
| DENY | rm -rf /, dd of=/dev/..., mkfs.*, fork bombs |
refused outright, never run |
| ASK | rm file, sudo ..., chmod, curl ... | sh |
requires your confirmation |
| ALLOW | ls, cat, git status |
runs without prompting |
--sudo removes the confirmation prompts (ASK tier and --ask-permission); DENY commands are
still refused. With no flags, an ASK-tier command prompts and an ALLOW-tier one runs unaided.
Plan mode — -p / --plan
The loop keeps two human-readable tracking files in the session directory: CURRENT_GOAL.md
(your latest instruction) and CURRENT_PLAN.md (a step-by-step plan for that goal, marked
finished when it is done). They are authored by the loop, not the agent, live outside
--allowed-dir, and can be inspected any time with /plan. The generated plan is
also printed as a box right after planning, so you can see it without asking.
Use /skip-plan <prompt> to send one prompt without planning it (plan mode stays
on for later turns).
--plan-strategy selects how planning is wired:
| Strategy | What happens |
|---|---|
plan-verify-step (default) |
Current behaviour: author a plan, review it once the work settles, then run one extra step and keep whatever that step says. |
plan-verify |
Same plan + review, but the post-review step is kept only when it calls a tool. A no-tool answer is shown to you and ends the turn without being appended to the transcript. |
open-plan |
The agent owns a plan document at .mini/PLAN.md inside --allowed-dir, reads and updates it with the normal file tools, and the loop neither authors nor reviews a plan. |
Scratchpad — --scratchpad
With --scratchpad, the loop creates .mini/SCRATCHPAD.md inside --allowed-dir and tells the
agent that it may read and write that file freely, and may create additional scratch files in the
same directory (for example SCRATCH-NOTES.md, SCRATCH-IDEAS.md). The scratchpad is ordinary
state inside the sandbox, so the normal read_file / write_file / edit tools work; no special
tool is registered. It is meant for the agent's own thoughts, plans, learnings and open questions,
and survives a history compaction because it lives on disk.
Sessions — resume, or start fresh
Every session is saved under --cache-dir (default ~/.cache/mini/sessions/).
| Flag | Behaviour |
|---|---|
--restore-session PATH |
continue that exact session (a session directory or a bare session id under --cache-dir) |
-l, --load-last-session |
continue the session recorded in the .mini/last_session.json pointer, without asking |
--load-last-session continues that session in place (same id, same folder, same
messages), so the conversation you were in is the one you get back; an explicit
--restore-session wins if both are given. The "most recent" session comes from a single
source — the tiny .mini/last_session.json pointer written when a session starts or is
restored inside --allowed-dir (deliberately no timestamp fallback: with no pointer, a fresh
session starts). That pointer lives in the same .mini directory as --skills, but as its
own dedicated file, so the two never clash.
A session folder is restorable only if it has what this version writes: a valid
summary_history.json recorder, plus the history_{n}.json segment its last record names
(usage files are optional). Anything else — a folder from an older release, a hand-assembled
transcript, a recorder that does not validate, a missing segment — is refused with a note
saying why, and a fresh session is started instead. Nothing is repaired, guessed at, or
written into the refused folder.
Context compaction — --max-context-tokens
Compaction is decided by tokens only, never by message count: a few large tool outputs can
fill a window that hundreds of short turns would not. The next request is projected from the
server-reported prompt_tokens, plus an estimate of what was appended since, plus the output
reserve (--max-tokens). Unset (default) it is derived from the model's context window minus the
output reserve and a safety margin. Lower it to compact sooner, raise it to compact later — there
is no message-count cap to configure.
Compaction replaces the older turns with a summary, but it always carries the turn in flight
across the rollover: the message you just typed (or, mid-turn, the tool call the model is
waiting on) is kept verbatim after the summary. So a compaction that fires just as you send an
instruction cannot swallow it — the model still answers what you asked, and the turn stays in
the session file, in /history and in a later restore.
--compaction-strategy chooses what else survives besides the summary:
| Strategy | Messages after compaction |
|---|---|
summarise (default) |
system, summary, plan, current turn |
predict-files |
system, summary, predicted read-only tool calls + results, plan, current turn |
predict-messages |
system, summary, original messages the model names by index, plan, current turn |
predict-files asks the model which files it needs to re-read and executes only the read-only
tools (read_file, grep, glob) it predicts; predict-messages asks for a JSON array of
0-based message indexes to keep verbatim. Both predictions are one extra tool-free (or
read-only-tool) LLM call, are billed normally, and are capped so they cannot refill the context
they just freed. A failed prediction degrades to the plain summary.
Because a rollover leaves no trace in the transcript (the old turns really are gone), the
console says in plain terms what happened — all of it without --verbose:
[!] Compacting the conversation: 42 messages -> a summary (51000 tokens in, 8192 reserved for the reply > 52000 budget). The current turn (1 message) is kept verbatim.
[!] Summary preview: The user asked for a token-based compaction trigger, then fixed ...
[!] Compacted history_0.json (42 messages) into a summary; history_1.json now starts with 3 messages (summary + 1 kept message).
So you can see what was folded away (a preview of the summary itself), how much (the
message count of the segment that was closed), where it went (history_0.json closed,
history_1.json started) and that nothing you just typed was lost. If the summariser answers
with an empty summary twice, or the call fails, compaction is abandoned and the note says so
explicitly — "nothing was lost, but the next request may still be too large" — with the
transcript and the segment left untouched.
Exiting — the good-bye box
Quitting (/quit, exit, or EOF on stdin) saves the session and then prints a short yellow
box: the version, a sign-off, and what the session left behind — session id, model, folder,
the history segments on disk, how many turns were recorded, run duration, token / call totals,
background tasks cancelled on exit, and a --load-last-session resume hint.
╔══════════ MiniCodeCLI v0.1.1.2 - goodbye ═════════════════════╗
║ Goodbye, and thanks for using MiniCodeCLI! ║
║ ║
║ session id : 1792666273983619-36ca3c2e ║
║ model : ornith-ai/Ornith-1.5-35B-A3B ║
║ saved under : ~/.cache/mini/sessions/1792…-36ca3c2e/ ║
║ history : history_0.json (segment 0), 5 messages ║
║ conversation : 2 recorded turns ║
║ duration : 12m 34s ║
║ tokens : 20 in / 10 out (30 total) ║
║ calls : 2 LLM, 0 tool ║
║ background : none running ║
║ resume : mini-code --load-last-session ║
╚═══════════════════════════════════════════════════════════════╝
It is printed exactly once, and only on a normal exit: a Ctrl-C or an internal error already
says what went wrong in red, so it does not get a cheerful summary box on top. With --verbose
the old per-field Token usage (this session) block is printed above it as well.
Serving a model locally
Tested with vLLM v0.30 (tool calling enabled):
vllm serve ornith-ai/Ornith-1.5-397B-FP8 \
--tensor-parallel-size 4 \
--host 0.0.0.0 \
--port 30000 \
--enable-auto-tool-choice \
--tool-call-parser qwen3_xml \
--reasoning-parser qwen3 \
--trust-remote-code
Citation
If you use mini-code-cli in your research or writing, please cite it:
@misc{mini-code-cli,
author = {Rozanov, Nikolai},
title = {mini-code-cli: A minimal, dependency-light coding agent},
year = {2026},
version = {0.2.0.0},
howpublished = {\url{https://github.com/ai-nikolai/mini-code-cli}},
note = {A no-bloat, dependency-light agent CLI for experimenting.}
}
License
AGPL-3.0 — (C) Nikolai Rozanov, 2026 – present.
Metadata
Release files for mini-code-cli 0.2.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mini_code_cli-0.2.0.0.tar.gz | 227.1 kB | Without provenance | Details for mini_code_cli-0.2.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mini_code_cli-0.2.0.0-py3-none-any.whl | Python 3 | none | any | Details for mini_code_cli-0.2.0.0-py3-none-any.whl |
Total release size: 396.2 kB
Release files / mini_code_cli-0.2.0.0.tar.gz
| Download URL | mini_code_cli-0.2.0.0.tar.gz |
|---|---|
| Size | 227.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
77968e1caefc00106fde51b94fa89886d89493f7d9e6bf324c60b50aca1d982f
|
|
BLAKE2b-256 checksum How to use checksums |
35d6c05e286909feeb099f4211a920ace38bafb8b65bcd73e6e38454c250acce
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.13
|
Release files / mini_code_cli-0.2.0.0-py3-none-any.whl
| Download URL | mini_code_cli-0.2.0.0-py3-none-any.whl |
|---|---|
| Size | 169.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cc48dede13a2ff3a10c0d82b914b6cee26e4facf84abc39da98ce90c1dd9f533
|
|
BLAKE2b-256 checksum How to use checksums |
64613d1e5bcc9de5268beb72855e3017c7ac5ff1dcc60e715094713f4332f6be
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.13
|
Security for mini-code-cli 0.2.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.