minacode 0.12.0__tar.gz

minacode-0.12.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, hit9
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT INCLUDING NEGLIGENCE OR OTHERWISE ARISING IN ANY WAY OUT OF THE USE OF
+THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

minacode-0.12.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE
+include README.zh-CN.md
+prune demo*
+prune tests

minacode-0.12.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: minacode
+Version: 0.12.0
+Summary: A small terminal coding agent written in Python
+Author-email: hit9 <hit9@icloud.com>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/hit9/minacode
+Project-URL: Repository, https://github.com/hit9/minacode
+Project-URL: Issues, https://github.com/hit9/minacode/issues
+Project-URL: Documentation, https://minacode.readthedocs.io
+Keywords: ai,coding-assistant,cli,terminal
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Software Development
+Classifier: Topic :: Terminals
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anthropic>=0.64.0
+Requires-Dist: code-symbol-index>=0.3.5
+Requires-Dist: json-repair
+Requires-Dist: fastmcp-slim[client]<4,>=3
+Requires-Dist: openai>=2.37.0
+Requires-Dist: prompt-toolkit>=3.0
+Requires-Dist: rich>=13.0
+Requires-Dist: socksio>=1.0.0
+Requires-Dist: websockets>=15.0.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Dynamic: license-file
+
+<h1 align="center">minacode</h1>
+
+<p align="center">
+  <img src="snapshots/minacode1.gif" alt="minacode editing code and running tools" width="600">
+</p>
+
+<p align="center">
+  A coding agent I use, maintain, and customize, shipped as a small, focused Python package.
+</p>
+
+<p align="center"><a href="README.zh-CN.md">中文</a></p>
+
+## Safety
+
+**Use at your own risk.** minacode can edit files and run shell commands in the environment where it starts. It does not provide sandbox isolation; use a container or VM when needed.
+
+## What it is
+
+minacode does not introduce a new kind of coding agent. It combines familiar features — reading and editing files, running commands, follow-ups, sessions, diffs, MCP, and skills — into a tool I use personally.
+
+It works on real repositories, including its own: I use minacode to build and maintain minacode. Everything ships in a small, focused Python package, so I can change the behavior directly whenever I want the workflow to work differently.
+
+minacode is the former nanocode. It started as a single-file agent small enough to be called *nano*, but has since grown beyond a single file, so it now goes by minacode.
+
+<p align="center">
+  <img src="snapshots/minacode2.gif" alt="minacode resuming a saved session" width="600">
+</p>
+<p align="center"><sub>Resuming a saved session with its conversation and tool history.</sub></p>
+
+## Highlights
+
+- **Prompt-cache aware:** stable request prefixes let supported providers reuse work and can reach 90–99% cache hit rates; `/status` shows the reported result.
+- **Code navigation:** jump to definitions, callers, and implementations with a searchable code index.
+- **Live follow-ups:** type while the agent works; `Enter` queues a message for the next model step, while `Ctrl-C` discards a draft or interrupts the task once the input is empty.
+- **Anchored edits:** structured edits use `line:hash` anchors and reject stale file content.
+- **Resumable sessions:** conversation, tool calls, diffs, and working memory survive `-c` or `--resume`.
+- **Built-in diff viewer:** `/diff` shows the latest round and the net session result.
+- **MCP and skills:** connect Model Context Protocol servers and load Markdown instruction packs on demand.
+- **Provider compatibility:** OpenAI-compatible APIs and Anthropic.
+
+## Install
+
+Requires macOS or Linux, Python 3.11+, and [uv](https://docs.astral.sh/uv/).
+
+```sh
+uv tool install minacode
+minacode --init-config
+```
+
+Add your provider to `~/.minacode/config.toml`:
+
+```toml
+[provider]
+active = "default"
+
+[provider.default]
+url = "https://api.deepseek.com"
+key = "sk-..."
+model = "deepseek-v4-flash"
+```
+
+Then run:
+
+```sh
+minacode
+```
+
+Upgrade with `uv tool upgrade minacode`.
+
+## Links
+
+- [Documentation](https://minacode.readthedocs.io/en/latest/) — full usage guide and reference.
+- [Blog post](https://hit9.dev/post/nanocode) — why and how it was built.
+- [code-symbol-index](https://github.com/hit9/code-symbol-index) — the code index library minacode uses.

minacode-0.12.0/README.md

@@ -0,0 +1,74 @@
+<h1 align="center">minacode</h1>
+
+<p align="center">
+  <img src="snapshots/minacode1.gif" alt="minacode editing code and running tools" width="600">
+</p>
+
+<p align="center">
+  A coding agent I use, maintain, and customize, shipped as a small, focused Python package.
+</p>
+
+<p align="center"><a href="README.zh-CN.md">中文</a></p>
+
+## Safety
+
+**Use at your own risk.** minacode can edit files and run shell commands in the environment where it starts. It does not provide sandbox isolation; use a container or VM when needed.
+
+## What it is
+
+minacode does not introduce a new kind of coding agent. It combines familiar features — reading and editing files, running commands, follow-ups, sessions, diffs, MCP, and skills — into a tool I use personally.
+
+It works on real repositories, including its own: I use minacode to build and maintain minacode. Everything ships in a small, focused Python package, so I can change the behavior directly whenever I want the workflow to work differently.
+
+minacode is the former nanocode. It started as a single-file agent small enough to be called *nano*, but has since grown beyond a single file, so it now goes by minacode.
+
+<p align="center">
+  <img src="snapshots/minacode2.gif" alt="minacode resuming a saved session" width="600">
+</p>
+<p align="center"><sub>Resuming a saved session with its conversation and tool history.</sub></p>
+
+## Highlights
+
+- **Prompt-cache aware:** stable request prefixes let supported providers reuse work and can reach 90–99% cache hit rates; `/status` shows the reported result.
+- **Code navigation:** jump to definitions, callers, and implementations with a searchable code index.
+- **Live follow-ups:** type while the agent works; `Enter` queues a message for the next model step, while `Ctrl-C` discards a draft or interrupts the task once the input is empty.
+- **Anchored edits:** structured edits use `line:hash` anchors and reject stale file content.
+- **Resumable sessions:** conversation, tool calls, diffs, and working memory survive `-c` or `--resume`.
+- **Built-in diff viewer:** `/diff` shows the latest round and the net session result.
+- **MCP and skills:** connect Model Context Protocol servers and load Markdown instruction packs on demand.
+- **Provider compatibility:** OpenAI-compatible APIs and Anthropic.
+
+## Install
+
+Requires macOS or Linux, Python 3.11+, and [uv](https://docs.astral.sh/uv/).
+
+```sh
+uv tool install minacode
+minacode --init-config
+```
+
+Add your provider to `~/.minacode/config.toml`:
+
+```toml
+[provider]
+active = "default"
+
+[provider.default]
+url = "https://api.deepseek.com"
+key = "sk-..."
+model = "deepseek-v4-flash"
+```
+
+Then run:
+
+```sh
+minacode
+```
+
+Upgrade with `uv tool upgrade minacode`.
+
+## Links
+
+- [Documentation](https://minacode.readthedocs.io/en/latest/) — full usage guide and reference.
+- [Blog post](https://hit9.dev/post/nanocode) — why and how it was built.
+- [code-symbol-index](https://github.com/hit9/code-symbol-index) — the code index library minacode uses.

minacode-0.12.0/README.zh-CN.md

@@ -0,0 +1,74 @@
+<h1 align="center">minacode</h1>
+
+<p align="center">
+  <img src="snapshots/minacode1.gif" alt="minacode 编辑代码并运行工具" width="600">
+</p>
+
+<p align="center">
+  一个我自己在用、维护并定制的 coding agent。
+</p>
+
+<p align="center"><a href="README.md">English</a></p>
+
+## 安全
+
+**使用风险自负。** minacode 会在启动环境中编辑文件并执行 shell 命令，不提供 sandbox 隔离。需要隔离时，请使用容器或虚拟机。
+
+## 它是什么
+
+minacode 并不想发明一种新的 coding agent。它只是把熟悉的能力 — 读取和编辑文件、运行命令、追加指令、session 恢复、diff、MCP 和 skill — 整合成我自己真正在用的工具。
+
+它不仅用于真实项目，也用于自身开发：我用 minacode 来构建和维护 minacode。所有功能都在一个小而聚焦的 Python 包中，所以我可以随时直接修改行为，让工作流按我想要的方式运行。
+
+minacode 即原来的 nanocode。它最初是一个小到可以称作 *nano* 的单文件 agent，但如今已不再 nano，所以改名为 minacode。
+
+<p align="center">
+  <img src="snapshots/minacode2.gif" alt="minacode 恢复保存的 session" width="600">
+</p>
+<p align="center"><sub>恢复保存的 session，包括对话和工具调用历史。</sub></p>
+
+## 亮点
+
+- **Prompt-cache 友好：** 稳定的请求前缀让支持缓存的 provider 复用计算，缓存命中率可达 90–99%；`/status` 会显示 provider 返回的实际结果。
+- **代码导航：** 通过可搜索的代码索引跳转到定义、调用者和实现。
+- **实时追加指令：** agent 工作时仍可输入；`Enter` 将消息排入下一次模型调用，`Ctrl-C` 先清除草稿，输入为空时中断当前任务。
+- **锚点编辑：** 结构化编辑使用 `line:hash` 锚点，文件内容过期时会被拒绝。
+- **可恢复 session：** 对话、工具调用、diff 和工作记忆可通过 `-c` 或 `--resume` 恢复。
+- **内置 diff viewer：** `/diff` 展示最新一轮改动以及整个 session 的累计变更。
+- **MCP 与 skills：** 按需连接 Model Context Protocol server，加载 Markdown 指令包。
+- **Provider 兼容：** 支持 OpenAI-compatible API 与 Anthropic。
+
+## 安装
+
+需要 macOS 或 Linux、Python 3.11+ 和 [uv](https://docs.astral.sh/uv/)。
+
+```sh
+uv tool install minacode
+minacode --init-config
+```
+
+在 `~/.minacode/config.toml` 中填写 provider：
+
+```toml
+[provider]
+active = "default"
+
+[provider.default]
+url = "https://api.deepseek.com"
+key = "sk-..."
+model = "deepseek-v4-flash"
+```
+
+然后运行：
+
+```sh
+minacode
+```
+
+升级：`uv tool upgrade minacode`。
+
+## 链接
+
+- [文档](https://minacode.readthedocs.io/zh-cn/latest/) — 完整的使用指南和参考。
+- [博客](https://hit9.dev/post/nanocode) — 设计动机与实现过程。
+- [code-symbol-index](https://github.com/hit9/code-symbol-index) — minacode 使用的代码索引库。

minacode-0.12.0/minacode/__init__.py

@@ -0,0 +1,21 @@
+"""minacode: A small terminal coding agent written in Python.
+
+The implementation lives in focused submodules (``base``, ``session``,
+``skill``, ``mcp``, ``tools``, ``engine``, ``tui``) plus a ``__main__`` entry
+point.  The public names are
+re-exported here so ``import minacode`` keeps exposing the same namespace the
+single-file module used to provide.
+"""
+
+from minacode.tui import *
+from minacode.base import __version__
+
+
+def __getattr__(name: str):
+    # Lazily expose the entry point so importing minacode (and running `python -m minacode`)
+    # does not eagerly import __main__, which would raise a duplicate-module RuntimeWarning.
+    if name == "main":
+        from minacode.__main__ import main
+
+        return main
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

minacode-0.12.0/minacode/__main__.py

@@ -0,0 +1,66 @@
+"""minacode entry point: command-line argument parsing and dispatch.
+
+Invoked through the ``minacode`` console script or ``python -m minacode``.
+"""
+
+from __future__ import annotations
+
+from minacode.tui import *
+from minacode.base import __version__
+import argparse
+
+
+def main(argv: list[str] | None = None) -> int:
+    if sys.platform == "win32":
+        print("Error: minacode does not support native Windows; use WSL instead.", file=sys.stderr)
+        return 1
+
+    parser = argparse.ArgumentParser(prog="minacode")
+    parser.add_argument("--config", default=None, help="Path to config TOML")
+    parser.add_argument("--init-config", action="store_true", help="Create a default config file")
+    parser.add_argument("--yolo", action="store_true", help="Skip confirmations for mutating tools")
+    parser.add_argument(
+        "--theme", choices=["auto", "light", "dark"], default="", help="Color theme (defaults to runtime.theme, then auto-detect via COLORFGBG)"
+    )
+    resume = parser.add_mutually_exclusive_group()
+    resume.add_argument("--resume", default="", nargs="?", const="latest", help='Resume a session by UID, or "latest"/"last" for this project\'s most recent')
+    resume.add_argument("-c", "--last", "--latest", dest="continue_project", action="store_true", help="Resume the latest session in the current project")
+    parser.add_argument("-v", "--version", action="store_true", help="Show version")
+    args = parser.parse_args(argv)
+    if args.version:
+        print(__version__)
+        return 0
+    try:
+        if args.init_config:
+            path, created = ConfigFile.init(args.config)
+            print(("Created" if created else "Exists") + " config: " + path)
+            return 0
+        if args.resume or args.continue_project:
+            data = ConfigFile.load(args.config)
+            config = Config.from_dict(data)
+            session = Session.load_snapshot(
+                args.resume or "latest",
+                config=config,
+                settings=RuntimeSettings.from_dict(data, yolo=args.yolo, theme=args.theme),
+                cwd=os.getcwd(),
+            )
+        else:
+            session = Session.from_config_file(path=args.config, yolo=args.yolo, theme=args.theme)
+        Theme.set_mode(Theme.resolve(session.settings.theme))
+        command_loop = CommandLoop(Agent(session))
+        try:
+            return command_loop.run()
+        finally:
+            command_loop.close_background_output()
+            if session.mcp is not None:
+                session.mcp.close()
+    except ConfigError as error:
+        print("ConfigError: " + str(error), file=sys.stderr)
+        return 2
+    except MinacodeError as error:
+        print("Error: " + str(error), file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())