@@ -0,0 +1,78 @@
1+<p align="center">
2+ <img src="demo.gif" alt="mini-coder demo" />
3+</p>
4+
5+# mini-coder
6+
7+A fast, transparent, config-first terminal coding agent. One provider request at a time, no
8+hidden machinery: `edit`, `read`, and `bash`, an append-only JSONL session log, and a config
9+file that decides everything.
10+
11+## Install
12+
13+```sh
14+npm i -g mini-coder
15+```
16+
17+## Configuration
18+
19+Global config lives at `~/.config/mini-coder/config.json` (`$XDG_CONFIG_HOME/mini-coder/config.json`
20+if set). There is no project-local config and no override flags.
21+
22+```json
23+{
24+ "provider": "anthropic",
25+ "model": "claude-sonnet-4-5"
26+}
27+```
28+
29+Only `provider` and `model` are required. Defaults for the rest:
30+
31+```json
32+{
33+ "sessionsDir": "./sessions",
34+ "systemPrompt": "",
35+ "discoverAgentFiles": true,
36+ "skillsDirs": [],
37+ "tools": ["edit", "read", "bash"],
38+ "thinkingEffort": "medium",
39+ "customProviders": []
40+}
41+```
42+
43+- `provider` / `model` — any model from the `pi-ai` catalog. Invalid pairs fail with a
44+ list of available models for that provider.
45+- `sessionsDir` — where append-only session JSONL files are written. (no relative paths for now, absolute paths only).
46+- `systemPrompt` — the base of the system prompt. Skills and agent files, if
47+ enabled, are appended after it.
48+- `discoverAgentFiles` — when true, appends `AGENTS.md` / `CLAUDE.md` found in `~/.agents`
49+ and the working directory to the system prompt.
50+- `skillsDirs` — directories of skills to advertise (`<dir>/<skill>/SKILL.md` with
51+ `name:` and `description:` frontmatter). Paths, not contents, go to the model.
52+- `tools` — which of `edit`, `read`, `bash` the agent gets. Tool arguments are untrusted
53+ and validated at this boundary regardless.
54+- `thinkingEffort` — `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` for models
55+ that support reasoning.
56+
57+### Local and custom models
58+
59+Hosted and local models are equals. Add unlisted or self-hosted models through
60+`customProviders` — the four wire APIs come from `pi-ai`, and auth resolves from your
61+environment via `envKeys` (no local model needs it):
62+
63+```json
64+{
65+ "customProviders": [
66+ {
67+ "id": "ollama",
68+ "name": "Ollama",
69+ "baseUrl": "http://localhost:11434/v1",
70+ "api": "openai-completions",
71+ "models": ["qwen3-coder:30b", "gpt-oss:20b"]
72+ }
73+ ]
74+}
75+```
76+
77+`api` is `openai-completions`, `openai-responses`, `anthropic-messages`, or
78+`google-generative-ai`. Then point `provider` and `model` at it.