Skip to main content

mini-code-cli

A minimal coding agent CLI

No bloat, no dependencies, no tracking, no telemetry...

CI PyPI Python Stars License: AGPL v3 Cite

mini-code in a terminal

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

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 32768, or half the model window 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)
--super off kitchen-sink behaviour preset: plan-verify2 + strict verification, all shell/sub-agent/skill/sudo/background features, auto-mode, prompt-change recovery and dynamic todos. The model, URL and API key are left untouched
--plan-strategy NAME plan-verify2 plan-verify2, plan-verify, plan-verify-step or open-plan (implies --plan)
--allow-nudge off plan mode only: ask the model to continue (or reply DONE) when it stops without a tool call, before running the plan review
--nudge-limit N 1 maximum continuation nudges per text-only stop with --allow-nudge
--strict-verify off use the evidence-based verification prompt for every plan review/verify stage; also verifies after open-plan work settles. Unproven requirements count as unfinished
--runtime-strategy NAME normal normal, prompt-change or prompt-change-plan: recover after 3 consecutive failures of the same call/tool
--scratchpad off give the agent a free-form .mini/SCRATCHPAD.md (plus further scratch files) for thoughts, plans and learnings
--dynamic-todo-tracking off give the agent a structured session-local todo list (todo_write / todo_update / todo_list), independent of plan mode and the scratchpad
--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
--no-settings off do not load, prompt for, or save session settings (useful for CI/benchmark runs)
--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 DuckDuckGo Lite HTML search (POST), with DuckDuckGo Instant Answers and Wikipedia as fallbacks. Returns titles, URLs and snippets; 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. Output over 50k characters is capped in the reply and the full text is written to .mini/tool-output/ so read_file/grep can page it
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, wait and cancel inspect 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)
/todo show the dynamic todo list; /todo clear empties it
/image <path> stage a PNG/JPEG/WEBP/GIF for the next message; /image clear removes staged images
/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
`/settings [name number] [value]`
/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.

Session settings

Settings are stored per session in the cache, never in the project’s .mini:

<cache-dir>/<session-id>/settings.json

The file has a single current layout (version, values, api_keys, api_key_envs, with keys scoped by endpoint/model); older top-level key fields are ignored rather than migrated. Startup deliberately does not load previous-session settings: the resume offer uses the CLI/environment/default configuration, so no settings notes or questions appear before you choose. Settings are loaded only after that choice. Resuming adopts the restored session’s settings; starting a new session resets ordinary settings to their defaults (the previous per-model API-key archive is the one thing kept) and asks the provider/model questions again, pre-selecting the current provider so Enter keeps it. An explicit --model skips the questions. The saved model and API key are checked after the model is known (after the restore, or after the provider/model selection).

The wizard asks for the model provider (localhost, deepseek, or a custom URL) and, when needed, the API key. For DeepSeek it then asks which model to use, offering the ids from the live /v1/models response when a key is available (otherwise the stable deepseek-chat / deepseek-reasoner aliases). The DeepSeek key prompt says where to create a key and that MINI_CODE_API_KEY is used first. When the fixed TUI applies, the wizard runs inside it (arrow keys or numbers select, and a typed key is masked). If you type a key, mini-code asks clearly whether to write it to the session file with mode 0600; otherwise it stays in memory for this session only. Keys are scoped to the endpoint/model: selecting another model loads its stored key, or asks for one when none is stored. Once the model is known, a key found for it is checked against /v1/models; an explicit 401/403 rejection reopens the key prompt.

Use /settings to inspect or change settings. The table marks values that rebuild the tool list or generated system prompt — these invalidate the LLM prompt cache. Cache-impacting edits from the plain settings> prompt are staged until you type apply, so a batch rebuilds the prompt once.

In the fixed TUI the centered, unboxed ASCII mark and tagline (the same mark used by --tui off) sit above the session view and stay visible in the settings views. The settings table is a navigable overlay grouped into Model & connection, Generation, Planning, Compaction, Tools & permissions, Runtime limits, Display, Agent behaviour and Immutable/session sections (so e.g. verbose lives under Display). It starts at the first setting and scrolls with the selection. Up/down or numbers select; left/right toggle an on/off setting or rotate through a fixed-choice setting (such as plan-strategy) in place. Values equal to their built-in default are marked (default). Enter opens a focused sub-window that shows only that setting's input box (or its option list), where exit or Esc returns to the settings table. The full table (including immutable rows) is always shown. a stages the same feature flags as the CLI --all preset (plan, shell, sub-agents, skills, auto-mode, sudo, background); p stages the CLI --super preset; d stages all defaults while keeping the model, URL and API key. The same presets are available as /settings all, /settings super and /settings default. Changes are staged in the table until you press s to save; q quits, and if there are unsaved changes it asks whether to save them or cancel the changes. The table header shows a green saved or yellow unsaved badge. Plan mode is its own on/off setting; the plan strategy keeps a concrete value even while plan mode is off, and changing the strategy does not turn plan mode on. Changing the TUI, paths, the custom system prompt or the initial prompt is not allowed mid-session.

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-verify2 (default) Author a plan, then verify completion with one machine-readable verdict (STATUS: DONE / STATUS: INCOMPLETE / STATUS: IN PROGRESS). DONE ends the turn immediately, without the post-review step; an unfinished verdict re-queues the outstanding work and the agent continues, with another verify after it settles.
plan-verify Author a plan, review it once the work settles, then keep the post-review step only when it calls a tool. A no-tool answer is shown to you and ends the turn without being appended to the transcript.
plan-verify-step The original behaviour: same plan + review, then always run one extra step and keep whatever that step says.
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.

--strict-verify makes the completion check evidence-based instead of trust-based. The verifier must restate the goal as concrete requirements, cite the tool call/output that proves each one, and mark missing or ambiguous evidence as unfinished. It applies to plan-verify, plan-verify2 and plan-verify-step, and with open-plan it adds a verification pass after the work settles without taking ownership of the agent's plan document.

--allow-nudge adds a completion checkpoint to any plan strategy. When the model replies without a tool call and the text does not explicitly say DONE / complete / finished, the loop appends a short “continue with the next tool call, or reply DONE” message instead of immediately paying for a plan review. --nudge-limit N controls how many nudges are allowed per text-only stop (default 1). After the limit, the normal plan strategy takes over. This is useful for thinking models that tend to emit an intermediate “let me do X” message and stop.

Runtime recovery — --runtime-strategy

The runtime strategy decides what happens when tool use keeps failing. It is independent of plan mode and applies to every turn:

Strategy What happens
normal (default) No automatic prompts; the model sees tool errors and decides.
prompt-change After three consecutive failures of the same call (same command/path/query) or of the same tool with different inputs, the loop injects: “You have tried TOOL N times and it failed. Rethink your approach and try something else.” It also shows the last failure. A success resets the streak; at most three prompts are issued per turn.
prompt-change-plan The same prompt, then a fresh planning request for the current goal. In open-plan the loop injects the recovery plan but does not overwrite the agent's .mini/PLAN.md.

Both recovery strategies are heuristics: they are meant to break repetitive command/tool loops without changing the model's overall instruction. When web_search/read_website are available, the prompt also tells the model to search the documentation or the web before retrying. runtime-strategy and strict-verify are also available in /settings.

Dynamic todo tracking — --dynamic-todo-tracking

This is separate from the scratchpad. It registers three structured tools and tells the agent to keep a short checklist:

  • todo_write replaces the list with a JSON array of {"content", "status"} objects;
  • todo_update changes one item by id (pending, in_progress, completed);
  • todo_list shows the current list.

The store is session-local (<cache-dir>/<session-id>/todos.json), not a project file, so it does not pollute the worktree or a benchmark's filesystem checks. /todo shows it and /todo clear empties it. A scratchpad remains useful for free-form notes; the todo list is for tracked, verifiable steps.

Images — /image and image-aware read_file

/image PATH stages a PNG/JPEG/WEBP/GIF for the next user message. The file is copied into the session cache and the conversation stores a small reference, not base64; the bytes are resolved into a data URI only when the request is built. /image clear drops staged images.

The agent's read_file is also image-aware: reading a supported image attaches it as an image content block after the tool result. read_file still handles text as before. Images count toward the context estimate and are flattened to [image: name] in plan/review/compaction prompts.

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, 32768 reserved for the reply > 60000 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. The summary request is itself size-bounded, so a single enormous tool output cannot make compaction overflow the model's context window. If the summariser answers with an empty summary twice, or the call fails, compaction falls back to a deterministic mechanical summary (the goal plus the newest turns) and still rolls the segment over — keeping the over-long transcript would make every later request fail.

Exiting — the good-bye box

Quitting (/quit, exit, or EOF on stdin) saves the session, prints the centered yellow Mini Code mark and tagline above the box, and then prints a short content-width 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.

                  __  __ ___ _  _ ___    ___ ___  ___  ___
                 |  \/  |_ _| \| |_ _|  / __/ _ \|   \| __|
                 | |\/| || || .` || |  | (_| (_) | |) | _|
                 |_|  |_|___|_|\_|___|  \___\___/|___/|___|
                a minimal coding agent CLI

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

Benchmarks (academic evaluation)

Everything benchmark-related lives in benchmarks/ — the harness, its tests, its dependencies and its scripts:

python -m pip install -r benchmarks/requirements.txt   # harbor (from its branch), swebench, vllm
#                one 3.12 env is enough: harbor needs >=3.12, mini-code supports 3.10+
benchmarks/scripts/setup_external_repos.sh             # the TB 2.1 task set (data: clone, not pip)
benchmarks/scripts/apply_local_fixes.sh                # re-apply the ignored-checkout fixes

python benchmarks/run_benchmarks.py --dataset swe-bench         --agent mini-code --mode short_eval
python benchmarks/run_benchmarks.py --dataset swe-bench-lite    --agent all       --mode short_eval
python benchmarks/run_benchmarks.py --dataset terminalbench-2.1 --agent all       --mode short

# On an existing Slurm GPU allocation: start vLLM, wait for /health, then run
# one agent at a time (variables at the top of the script):
benchmarks/scripts/run_benchmark_slurm.sh
# Or generate/submit an sbatch job for the full matrix on 1-4 GPUs:
benchmarks/scripts/submit_benchmark_slurm.sh
# Prepare/verify the Terminal-Bench SIFs on a CPU partition:
benchmarks/scripts/submit_prepare_tb_sifs.sh

Both SWE-bench splits work on this cluster and need no extra repository — swe-bench-lite is the same harness, the same published instance images and the same grading, only the HuggingFace dataset changes. Measured on the Docker-less H200 with --limit 5, --agent all: Verified 10/15 (mini-code 2, pi 4, claude-code 4) and Lite 12/15 (mini-code 3, pi 4, claude-code 5); Terminal-Bench 2.1 scores per task but not yet as a campaign (one task: reward 0.0, nine verifier tests, no exception).

Each run writes results/<run-id>/summary_results.csv — one row per agent, with trials, resolved, pass_rate, mean_reward, mean_seconds. --mode short is a smoke run (3 tasks, no grading), short_eval grades those 3, full runs everything, and --dry-run prints every command and starts nothing.

The harness runs coding agents against Terminal-Bench 2.x and SWE-bench Verified/Lite and compares them — mini-code with several settings, Claude Code, Pi and a deterministic mock agent — by wrapping each benchmark's own official harness (harbor, tb, swebench.harness.run_evaluation). It supports Docker and Apptainer, exports a CSV and ships an analyser. Every agent gets the same instructions from one file, benchmarks/agents/agent.md, so a comparison cannot be explained by three different prompts.

See benchmarks/README.md for prerequisites, the two harness forks and their branches (installed from GitHub, and cloned into external_repos/ for local development by benchmarks/scripts/setup_external_repos.sh), the plan / run --csv / analyze commands underneath the entry point, the Docker and Apptainer variants, the configs (benchmarks/configs/ornith_30b.json for TB 2.0 + SWE-bench, terminal_bench_21.json for the local TB 2.1 checkout), and what a run produces.

Serving a model locally

For a one-GPU quick start, scripts/run_model.sh starts the small ornith-ai/Ornith-1.5-35B-A3B checkpoint on port 30000 and waits for /health. Edit its model/tensor-parallel line for a larger checkpoint. 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.3.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.3.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mini-code-cli 0.3.0.0
File Size Uploaded Provenance Actions
mini_code_cli-0.3.0.0.tar.gz 316.6 kB Without provenance Details for mini_code_cli-0.3.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mini-code-cli 0.3.0.0
File Interpreter ABI Platform Actions
mini_code_cli-0.3.0.0-py3-none-any.whl Python 3 none any Details for mini_code_cli-0.3.0.0-py3-none-any.whl

Total release size: 538.3 kB

Release files / mini_code_cli-0.3.0.0.tar.gz

Download URL mini_code_cli-0.3.0.0.tar.gz
Size 316.6 kB
Tags Source
SHA-256 checksum
How to use checksums
14bb2a2b9c1464ffa1cdb46abfc8652447cf8381e37741f0590c7aeb0eced57e
BLAKE2b-256 checksum
How to use checksums
6a3347655df33dd5cdc6794ca18d72397507247376b19f08dbada58a4951c5df
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.3.0.0-py3-none-any.whl

Download URL mini_code_cli-0.3.0.0-py3-none-any.whl
Size 221.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1260dfe8ef0742b3f91e338a5f28aa6a066bdd5590172778ff3a192260fa9fa9
BLAKE2b-256 checksum
How to use checksums
6dff16bf5a6557924e2079af8f2dbc46473dc6f33866dceb488044680fc9df3a
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.3.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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page