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: requests only
• 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 --auto-mode --sudo
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

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.

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

# 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())

In-session commands

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/:

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:

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.

Sessions — resume, or start fresh

Every session is saved under --cache-dir (default ~/.cache/mini/sessions/).

--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.

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.

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.1.1.0},
  howpublished = {\url{https://github.com/ai-nikolai/mini-code-cli}},
  note         = {A no-bloat, dependency-free agent CLI for experimenting.}
}

License

AGPL-3.0 — (C) Nikolai Rozanov, 2026 – present.