mini-code-cli 0.1.0.4__tar.gz → 0.1.1.1__tar.gz

{mini_code_cli-0.1.0.4 → mini_code_cli-0.1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mini-code-cli
-Version: 0.1.0.4
+Version: 0.1.1.1
 Summary: Mini Coding Agent. Allows you to easily experiment with a small coding agent.
 Author-email: Nikolai Rozanov <nikolai.rozanov@gmail.com>
 License:                     GNU AFFERO GENERAL PUBLIC LICENSE
@@ -666,95 +666,159 @@ License:                     GNU AFFERO GENERAL PUBLIC LICENSE
         <https://www.gnu.org/licenses/>.
         
 Project-URL: Homepage, https://github.com/ai-nikolai/mini-code-cli
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: requests<3,>=2.31
 Dynamic: license-file
 
-# A minimal coding agent cli
+# 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...
+[![CI](https://img.shields.io/github/actions/workflow/status/ai-nikolai/mini-code-cli/ci.yml?branch=main&label=CI&logo=github&style=flat-square)](https://github.com/ai-nikolai/mini-code-cli/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/mini-code-cli?style=flat-square&logo=pypi&logoColor=white)](https://pypi.org/project/mini-code-cli/)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue?style=flat-square&logo=python&logoColor=white)](https://pypi.org/project/mini-code-cli/)
+[![Stars](https://img.shields.io/github/stars/ai-nikolai/mini-code-cli?style=flat-square&logo=github)](https://github.com/ai-nikolai/mini-code-cli/stargazers)
+[![License: AGPL v3](https://img.shields.io/badge/license-AGPL--3.0-blue?style=flat-square)](LICENSE)
+[![Cite](https://img.shields.io/badge/cite-BibTeX-blueviolet?style=flat-square&logo=latex&logoColor=white)](#citation)
+
+**Purpose:** a no-bloat, minimal coding CLI to enjoy experimenting and researching.
+
+**Install** · [Quick start](#quick-start) · [Modes &amp; safety](#modes--safety) · [Options](#command-line-options) · [Tools](#available-tools) · [Sub-agents](#sub-agents) · [In-session commands](#in-session-commands) · [Development](#development) · [Docs](#documentation) · [Citation](#citation)
 
-## Getting started:
+> [!TIP]
+> **New here?** `pip install mini-code-cli`, point it at a model (a local server on
+> `localhost:30000`, or `MINI_CODE_API_KEY` + `--url`), and run `mini-code`. Everything else
+> is optional.
+
+## Install
 
-### Installation (from pypi)
 ```bash
 pip3 install mini-code-cli
 ```
 
-### Run agent:
+- **PyPI:** <https://pypi.org/project/mini-code-cli/>
+- **Python:** `>= 3.10` &nbsp;·&nbsp; **runtime dependency:** `requests` only
+- **From source / contributing:** see [docs/README_DEV.md](docs/README_DEV.md)
+
+## Quick start
+
+**1 — Local model** (e.g. vLLM or SGLang on port 30000; see [serving a model locally](#serving-a-model-locally)):
 
-1. Basic usage: (get local LLM running (e.g. via SGLang or Vllm))
 ```bash
-mini-code #run the agent using `localhost:30000/v1` model
+mini-code                          # talks to http://0.0.0.0:30000/v1
 ```
-2. Custom API based model:
+
+**2 — Hosted / custom API:**
+
 ```bash
 export MINI_CODE_API_KEY="sk-YOUR_API_KEY"
 mini-code --url "https://api.deepseek.com" --model "deepseek-v4-flash"
 ```
-3. Auto-mode and shell enabled: (this will run localhost:30000)
-```bash
-mini-code --enable-shell --auto-mode
-mini-code -s -a --sudo
-mini-code -s -a -p -g -l --sudo #plan, previous session, subagents (#or short-hand the next commands)
-mini-code --all
-mini-code --all-last
-```
 
-4. Advanced usage:
-Auto-mode, Agent.md, Shell Enabled mode and a specific allowed dir:
+**3 — The shortcuts** (plan mode, sub-agents, shell, auto-mode, no permission prompts):
+
 ```bash
-mini-code --enable-shell --auto-mode --agent-md "./skill.md" --allowed-dir "./" --ask-permission --system-prompt "Your awesome new system prompt..."
+mini-code --all                    # = --plan --enable-subagents --enable-shell --auto-mode --sudo
+mini-code --all-last               # ...and continue your last session
 ```
-- auto-mode: the agent will continue querying the LLM and executing tools, until no more tool calls are possible
-- agent.md: this will read an agent.md file with the specified name (e.g. ./skill.md)
-- shell-enabled: **Be careful**: This will allow the agent to execute shell commands. **Every command is first checked by a shell-safety classifier** that sorts it into three tiers:
-    - **DENY** — obviously destructive commands (e.g. `rm -rf /`, `dd of=/dev/...`, `mkfs.*`, fork bombs) are **refused outright** and never run.
-    - **ASK** — risky commands (e.g. `rm file`, `sudo ...`, `chmod`, `curl ... | sh`) require your confirmation before running.
-    - **ALLOW** — clearly safe commands (e.g. `ls`, `cat`, `git status`) run without prompting.
-  This protection is **always enforced** for the shell tool, even in auto-mode / without `--ask-permission`, so the agent can never run dangerous commands unattended. (The classifier is a heuristic, not a sandbox — use with care.)
-- allowed-dir: this specifies which dirs the agent can read and write from, that does not stop the shell comands! (though dangerous shell commands are still blocked by the classifier above).
-- ask-permission: asks user permission before every tool call. For shell commands, commands in the ALLOW tier skip the prompt, DENY is blocked, and ASK always prompts.
-- system-prompt: you can override the default prompt by using a string. (Note: Agent.md is always appended after the system prompt.)
-- load-last-session: instead of starting a fresh conversation, automatically continue your most recently active session from the default cache dir. It resumes under a brand-new session id, so the original session is never overwritten. An explicit `--restore-session` (a specific path) takes precedence if both are given. The "most recent" session is resolved in two steps: at the end of every interactive session, its path is recorded in a tiny `.mini/last_session.json` pointer inside the `--allowed-dir`, and `--load-last-session` consults that pointer first; only if there is no pointer (e.g. a fresh allowed dir, or the `--skills` feature disabled) does it fall back to the timestamp heuristic (the session whose history was modified most recently). The `.mini` pointer is the same directory the `--skills` feature uses, but it is a single dedicated file, so the two never clash.
-- **Interactive session offer:** if a previous session exists in the cache dir but you did **not** explicitly ask to resume one (i.e. neither `--load-last-session` nor `--restore-session` was passed), the prompt asks what you'd like to do before the conversation starts: 1) **Resume** the previous session (splice its history in under a brand-new session id and continue it), 2) **Start a new** session (empty history), or 3) **Exit** (start nothing). Ctrl-C / EOF at the offer is treated as a graceful exit. This is distinct from `--load-last-session`, which silently resumes the most recent session without asking.
-- plan: `--plan` enables **plan mode**. The loop keeps two human-readable tracking files in the session directory: `CURRENT_GOAL.md` (the user's latest instruction) and `CURRENT_PLAN.md` (a step-by-step plan the loop generates for the active goal, marked finished once the goal is done). These files are authored by the *loop*, not the agent (they live outside `--allowed-dir`), and you can inspect them anytime with `/plan` (only meaningful in plan mode). After the work looks done, plan mode reviews the plan's completion and re-queues any outstanding tasks before returning to you. Plan mode also changes how history compaction works: after the history is compacted to a summary, the current `CURRENT_PLAN.md` and the user's last instruction (`CURRENT_GOAL.md`) are re-injected into the messages so the agent keeps working against the same goal. When the session ends, the active goal is marked finished in `CURRENT_PLAN.md`.
 
-### Available tools
+**4 — A first prompt:**
 
-The agent can call a small set of tools, all of which live in `mini_code_cli/tools.py`:
-
-- **`read_file` / `write_file`** — read a file or write/overwrite one.
-- **`grep`** — search a file for a pattern.
-- **`glob`** — list files matching a glob pattern.
-- **`web_search`** — best-effort web lookup: returns popular related queries (DuckDuckGo autocomplete) plus a short extract from the top Wikipedia match. Never raises; always returns a string.
-- **`read_website`** — fetch the raw text/HTML of a URL (bounded by `--tool-timeout`).
-- **`run_shell_command`** — run a shell command (only when `--enable-shell` is set). Every command is passed through the shell-safety classifier described above.
-
-### Sub-agents
-
-Passing `--enable-subagents` lets the main agent **delegate a focused task to a sub-agent**, which is exposed to the model as an extra tool. A sub-agent is a self-contained, narrowed agent: it runs on its own in auto-mode (unattended), in its own isolated session folder, and hands a short text result (plus an optional `report.md`) back to the main agent. It reuses all the existing machinery -- tools, the shell-safety classifier, the `--allowed-dir` sandbox, history compaction and `--plan` mode -- and cannot recursively spawn further sub-agents.
+```txt
+Write an agent.md file for me that helps an LLM write efficient triton kernels,
+given a reference implementation.
+```
 
-Enable it and the available sub-agents appear in the help (`/help`):
+> [!NOTE]
+> **Every flag** is listed once, in [Command-line options](#command-line-options) — or run
+> `mini-code --help`. Modes and their caveats are described in [Modes & safety](#modes--safety).
+
+## 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 (ALLOW-tier shell commands still skip the prompt) |
+| `--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 |
+| `--skills` | off | enable the `.mini` skills directory (`skill.md`s, `SKILLS.md`, runnable scripts) |
+| `-p`, `--plan` | off | plan mode (`CURRENT_GOAL.md` / `CURRENT_PLAN.md`, `/plan`) |
+| `--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 --auto-mode --sudo` |
+| `--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 |
+| `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) |
+| `glob` | list files matching a glob (one per line, `**` supported), optionally against a `root` |
+| `web_search` | best-effort lookup: related queries + a short Wikipedia extract. Never raises |
+| `read_website` | fetch raw text/HTML of a URL (bounded by `--tool-timeout`), `max_chars` caps size |
+| `run_shell_command` | run a shell command (needs `--enable-shell`); `cwd`, `timeout`, and stdout/stderr/exit code are all reported |
+
+## 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.
 
 ```bash
-mini-code --enable-subagents
+mini-code --enable-subagents       # the available sub-agents then show up in /help
 ```
 
-Two worked examples ship out of the box:
-
-- **`research`** -- read-only web research. Given a topic it searches the web, reads a few sources and returns a concise, sourced summary. It can only use `web_search` / `read_website` -- never the filesystem or shell -- so it is safe even without a sandbox. Accepts an optional `sources` hint (e.g. `"wikipedia.org only"`).
-- **`planner`** -- drafts/refines a clear step-by-step plan for a goal and returns it. Always runs in plan mode.
+| 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 |
 
-The `tools`, `enable_shell` and `max_steps` knobs are always intersected with the parent's own permissions, so a sub-agent can never do anything the main agent could not. Sub-agents also compose with `--plan` mode: each sub-agent keeps its own `CURRENT_PLAN.md` / `CURRENT_GOAL.md` in its own session folder.
+> [!NOTE]
+> A sub-agent's `tools`, `enable_shell` and `max_steps` are always **intersected with the
+> parent's** permissions, so it can never do anything the main agent could not. Sub-agents
+> compose with `--plan`: each keeps its own `CURRENT_PLAN.md` / `CURRENT_GOAL.md`.
 
-#### Adding your own sub-agent
+<details>
+<summary><b>Adding your own sub-agent</b></summary>
 
-A sub-agent is just a small class. Subclass `SubAgent` and register it:
+A sub-agent is just a small class — subclass `SubAgent` and register it:
 
 ```python
 # my_subagents.py
@@ -770,98 +834,147 @@ class SummarizeSubAgent(SubAgent):
 register(SummarizeSubAgent())
 ```
 
-Then make sure it is imported (e.g. add `import my_subagents`), and it will be discovered and exposed to the model automatically when `--enable-subagents` is set. See `mini_code_cli/subagents/builtin.py` for the full list of knobs and `ARCHITECTURE.md` (sections 2-3) for the design and every available option.
+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](docs/ARCHITECTURE.md) (sections 2–3) for the design.
+
+</details>
+
+## 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) |
+| `/help` | show this help |
+| `/quit`, `/exit` | save the session and exit |
+
+> [!NOTE]
+> `/history` and `/reset` are driven by `summary_history.json`, a flat recorder that maps every
+> turn to the `history_{n}.json` segment and message index it lives in — so no full history is
+> read just to list the conversation.
+>
+> * **`<n>` is validated**: `last`, or a positive 1-based turn number. `0`, negatives and
+>   non-numbers are rejected with `No such turn` instead of silently showing a different turn.
+> * **A bare `/reset` never destroys anything**: it reports `Already at turn N` when the
+>   transcript already ends at the last recorded turn, and *warns instead of truncating* if
+>   there are messages that were never recorded. Only `/reset <n>` / `/reset last` rewind.
+> * **A rewind really sticks**: the target `history_{n}.json` is truncated in place (no backup)
+>   and every higher `history_{m}.json` / `usage_{m}.json` segment is deleted, so a restart
+>   cannot resurrect the dropped turns. All history files are written atomically.
+> * **Token usage is never rolled back**: a rewind does not un-spend tokens, and the session
+>   total is preserved. See
+>   [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#rewinding-reset-and-what-it-does-to-the-files)
+>   for the files involved.
+
+## Development
+
+Linting, the test suite, CI and the release process are documented in
+[**docs/README_DEV.md**](docs/README_DEV.md).
 
-3. Try a prompt:
-```txt
-Write an agent.md file for me that helps an LLM write efficient triton kernels, given a reference implementation.
-```
-
-4. Get help:
 ```bash
-mini-code --help
+python3 scripts/lint.py                                # lint (standard library only)
+python3 -m unittest discover -s tests -p "test_*.py"    # run the test suite
 ```
-```
-Agent loop for interacting with a language model
-
-options:
-  -h, --help            show this help message and exit
-  --url URL             API host, default=http://0.0.0.0:30000
-  --max-tokens MAX_TOKENS
-                        Maximum tokens for LLM response, default=None
-  --temperature TEMPERATURE
-                        Temperature for LLM, default=1.0
-  --model MODEL         Model name, default=None
-  --api-key API_KEY     API key for authentication. If not set, it tries to find it in env variable: MINI_CODE_API_KEY.
-  --cache-dir CACHE_DIR
-                        The cache dir for the session histories. default=~/.cache/mini_code/sessions/
-  --restore-session RESTORE_SESSION
-                        The location of a previous session to continue. (e.g. ~/.cache/mini_code/sessions/1792028090823027-a9d77653/)
-  --load-last-session   Load the most recent previous session from the cache dir and continue it (under a new session id), instead of starting fresh. --restore-session takes precedence if also given.
-  --system-prompt SYSTEM_PROMPT
-                        Replace system prompt, with a custom system prompt.
-  -a, --auto-mode       Whether to run the agent in `auto-mode'. Or default: `manual-mode'.
-  --agent-md AGENT_MD   If the agent should use an agent-md file... (it will added after system message.)
-  --prompt PROMPT       An initial prompt from the user...
-  --ask-permission      Ask for permission before any tool call. (Shell ALLOW-tier commands skip the prompt; DENY is blocked.)
-  --sudo                DANGEROUS: never ask for permission. Every non-destructive tool call and shell command runs automatically without confirmation. Destructive (DENY-tier) commands are still refused.
-  --allowed-dir ALLOWED_DIR
-                        Allowed directory for file operations, default='./'
-  -s, --enable-shell    Allow shell execution. default= False
-  --enable-subagents    Allow the agent to delegate work to sub-agents (exposed as extra tools). default= False
-  --llm-timeout LLM_TIMEOUT
-                        HTTP timeout in seconds for LLM requests (reasoning models can be slow). default=500
-  --tool-timeout TOOL_TIMEOUT
-                        Timeout in seconds for a single tool call. default=120
-  --plan                Enable plan mode: the agent keeps a CURRENT_PLAN.md
-                        (its step-by-step plan, marked finished when the goal
-                        is done) and CURRENT_GOAL.md (the user's latest
-                        instruction) in the session directory. Also changes
-                        how history compaction works.
-  --verbose             Print the full, detailed output. Without it (default),
-                        only user/assistant turns, token usage and tool calls
-                        are shown.
-  ```
-
-### In-session commands
 
-```
-/history            list the conversation (turn number, what happened, where)
-/history <n>        show the full messages recorded for turn n
-/reset [<n>]        rewind to the end of turn n (drops everything after it)
-/clear              clear the screen (keeps the conversation history)
-/plan               show the current goal + plan (plan mode only)
-/help               show this help
-/quit, /exit        save the session and exit
-```
+Releases are cut by tagging `main`: pushing a `v*` tag triggers
+[`.github/workflows/release.yml`](.github/workflows/release.yml), which builds the sdist + wheel,
+verifies them with `twine check`, and attaches them to a new GitHub release.
 
-## Testing
+## Documentation
 
-The project ships with a small standard-library test suite (no extra dependencies to install):
+Everything beyond this README lives in [`docs/`](docs/):
 
-```bash
-# Run the whole suite from the repo root:
-python3 -m unittest discover -s tests -p "test_*.py"
-
-# ...or run a single test file:
-python3 tests/test_tools.py
-python3 tests/test_sandboxing.py
-python3 tests/test_agent_loop.py
-python3 tests/test_shell_safety.py
-```
+| Document | What it covers |
+| --- | --- |
+| [**docs/README_DEV.md**](docs/README_DEV.md) | developer guide — local setup, repository layout, linting, the test suite, CI and the release / PyPI upload process |
+| [**docs/ARCHITECTURE.md**](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 &amp; 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 |
+
+> [!WARNING]
+> The classifier is **always enforced** — even in auto-mode and with `--sudo` — so the agent
+> cannot run destructive commands unattended. It is a heuristic, not a sandbox: use it with care.
+> `--allowed-dir` sandboxes **file tools**, not the shell.
+
+### 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 tests focus on the parts of the agent that are easy to get wrong and worth guarding:
+> [!NOTE]
+> Plan mode also changes **history compaction**: after the transcript is compacted to a summary,
+> `CURRENT_PLAN.md` and `CURRENT_GOAL.md` are re-injected, so the agent keeps working against the
+> same goal. When the work looks done the plan is reviewed and any outstanding task is re-queued
+> before the agent returns to you.
 
-- **`test_sandboxing.py`** — the `--allowed-dir` sandbox. Verifies that child paths are allowed, while `..` traversal and sibling paths outside the allowed directory are rejected.
-- **`test_tools.py`** — the tool functions. Confirms they *return* their results/errors (instead of printing), that `run_shell_command` captures stderr and honors a timeout, and that the generated tool schema exposes the expected parameters.
-- **`test_agent_loop.py`** — agent-loop behaviour. Confirms that enabling the shell forces per-command permission prompts, that memory compaction is correctly wired (accepts token accounting), and that token-usage formatting handles servers that report no usage.
-- **`test_shell_safety.py`** — the shell command classifier. Confirms commands are sorted into the three tiers correctly: destructive commands (`rm -rf /`, `dd of=/dev/...`, `mkfs.*`, fork bombs) are **DENY**, risky ones (`rm file`, `sudo`, `curl | sh`, redirects to `/etc/...`) are **ASK**, and safe ones (`ls`, `cat`, `git status`) are **ALLOW**.
+### Sessions — resume, or start fresh
 
-This keeps the tool honest as it grows, and makes it safe to experiment with riskier features (like `--enable-shell`) without regressions.
+Every session is saved under `--cache-dir` (default `~/.cache/mini/sessions/`).
 
-## Other useful commands:
+> [!TIP]
+> If a previous session exists but you did **not** ask to resume one (neither
+> `--load-last-session` nor `--restore-session`), the prompt offers **Resume / Start new / Exit**
+> before the conversation begins. Ctrl-C or EOF there is a graceful exit. This is the *asking*
+> variant; `--load-last-session` is the *silent* one.
+
+
+| 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.
+
+
+## Serving a model locally
+
+Tested with vLLM v0.30 (tool calling enabled):
 
-### Serving a vllm model locally (with correct tools). vllm v0.30 (tested):
 ```bash
 vllm serve ornith-ai/Ornith-1.5-397B-FP8 \
     --tensor-parallel-size 4 \
@@ -875,17 +988,19 @@ vllm serve ornith-ai/Ornith-1.5-397B-FP8 \
 
 ## Citation
 
-If you use `mini-code-cli` in your research or writing, please cite it using the BibTeX entry below:
+If you use `mini-code-cli` in your research or writing, please cite it:
 
 ```bibtex
 @misc{mini-code-cli,
   author       = {Rozanov, Nikolai},
   title        = {mini-code-cli: A minimal, dependency-light coding agent},
   year         = {2026},
-  version      = {0.1.0.0},
+  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.}
 }
 ```
 
-## (C) Nikolai Rozanov, 2026 - Present
+## License
+
+[AGPL-3.0](LICENSE) — (C) Nikolai Rozanov, 2026 – present.