This project has been archived by its maintainers, and is no longer receiving any updates.
minacode
A coding agent I use, maintain, and customize, shipped as a small, focused Python package.
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.
Resuming a saved session with its conversation and tool history.
Highlights
- Worker delegation: hand a bounded task to a second in-process session on its own provider with
/worker; theDelegatetool keeps worker context across delegations until reset. - Forced reply language:
/languageor[runtime] languagepins the reply language for the session. - Smarter retries: exponential backoff with jitter and provider
Retry-After, shown as a liveretryingphase with a countdown. - Prompt-cache aware: stable request prefixes let supported providers reuse work and can reach 90–99% cache hit rates;
/statusshows the reported result. - Code navigation: jump to definitions, callers, and implementations with a searchable code index.
- Live follow-ups: type while the agent works;
Enterqueues a message for the next model step, whileCtrl-Cdiscards a draft or interrupts the task once the input is empty. - Anchored edits: structured edits use
line:hashanchors and reject stale file content. - Resumable sessions: conversation, tool calls, diffs, and working memory survive
-cor--resume. - Built-in diff viewer:
/diffshows the latest round and the net session result. - MCP and skills: connect Model Context Protocol servers and load Markdown instruction packs on demand.
- Provider-side web search: opt in to a provider's own search tool (OpenAI, Qwen, Anthropic, Z.AI) and see each search and its sources in the transcript.
- Provider compatibility: OpenAI-compatible APIs and Anthropic.
Install
Requires macOS or Linux, Python 3.11+, and uv.
uv tool install minacode
minacode --init-config
Add your provider to ~/.minacode/config.toml:
[provider]
active = "default"
[provider.default]
url = "https://api.deepseek.com"
key = "sk-..."
model = "deepseek-v4-flash"
Then run:
minacode
Upgrade with uv tool upgrade minacode.
Links
- Documentation — full usage guide and reference.
- Blog post — why and how it was built.
- code-symbol-index — the code index library minacode uses.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file minacode-0.24.4.tar.gz.
File metadata
- Download URL: minacode-0.24.4.tar.gz
- Upload date:
- Size: 271.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
6028be3030390f5e1f2426d51f669203830a3630346dc0501298895bdbf771b9
|
|
| MD5 |
edd36c1c4b0ab6aaa35cfb9b48ab54aa
|
|
| BLAKE2b-256 |
6e161560eb120bb99006b8fc6d319d2ee0508d9a8ac0014ba8a6f4e3e0b9a9c1
|
File details
Details for the file minacode-0.24.4-py3-none-any.whl.
File metadata
- Download URL: minacode-0.24.4-py3-none-any.whl
- Upload date:
- Size: 289.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
fc4e88d5915d1d790447779ffa5dd4f89bf8b32a0cd99e5516e2165a1265c573
|
|
| MD5 |
3f0a694ad5a519f2e2ac65168c41eccc
|
|
| BLAKE2b-256 |
949d34691ad01ad5ffbde973a1cd9876072742c5783af606025612dde913ea24
|
