mini-coder 0.1.0 → 0.1.2

package/docs/mini-coder.1.md

@@ -1,156 +1,260 @@
 # MINI-CODER(1)
 
 ## NAME
-**mini-coder** (executable: `mc`) - A small, fast CLI coding agent built for developers.
+
+**mini-coder** — a small, fast CLI coding agent (executable: `mc`)
 
 ## SYNOPSIS
-`mc [options] [prompt]`
+
+`mc` \[*options*\] \[*prompt*\]
 
 ## DESCRIPTION
-**mini-coder** is a developer-focused CLI coding agent. It prioritizes developer flow with no slow startup, no clunky GUI, and no vendor lock-in. It uses a minimalist terminal UI restricted to 16 ANSI colors to inherit the user's terminal theme, and is built entirely on Bun.js for maximum performance.
+
+Developer-focused CLI coding agent. Prioritizes dev flow — no slow startup, no GUI, no vendor lock-in. Uses 16 ANSI colors to inherit terminal theme. Built on Bun.js.
 
 ## OPTIONS
-**-m, --model <id>**
-:   Specify the model to use (e.g., `zen/claude-sonnet-4-6`).
 
-**-c, --continue**
-:   Continue the most recent session.
+`-m`, `--model` *id*
+: Model to use (e.g. `zen/claude-sonnet-4-6`).
+
+`-c`, `--continue`
+: Continue most recent session.
 
-**-r, --resume <id>**
-:   Resume a specific session by its ID.
+`-r`, `--resume` *id*
+: Resume a specific session.
 
-**-l, --list**
-:   List recent sessions.
+`-l`, `--list`
+: List recent sessions.
 
-**--cwd <path>**
-:   Set the working directory (defaults to current directory).
+`--cwd` *path*
+: Set working directory.
 
-**-h, --help**
-:   Display help information.
+`-h`, `--help`
+: Display help.
 
-**[prompt]**
-:   Optional one-shot prompt text. Runs once, then exits.
+*prompt*
+: Optional one-shot prompt. Runs once then exits.
 
 ## INTERACTIVE COMMANDS
-Inside the interactive session, the following slash commands are available:
 
-**/model**
-:   List all available models, indicating free models and context sizes.
+`/model`
+: List all available models.
+
+`/model` *id*
+: Switch model.
+
+`/model effort` *low|medium|high|xhigh|off*
+: Set reasoning effort.
+
+`/reasoning` \[*on|off*\]
+: Toggle reasoning display.
 
-**/model <id>**
-:   Switch to a specific model.
+`/context prune` *off|balanced|aggressive*
+: Pruning strategy.
 
-**/model effort <low|medium|high|xhigh|off>**
-:   Configure reasoning effort levels for models that support it.
+`/context cap` *off|bytes|kb*
+: Tool result payload cap.
 
-**/reasoning [on|off]**
-:   Toggle the display of the model's reasoning/thought process.
+`/cache` *on|off*
+: Toggle prompt caching globally.
 
-**/context prune <off|balanced|aggressive>**
-:   Configure context window pruning strategies.
+`/cache openai` *in_memory|24h*
+: OpenAI cache retention.
 
-**/context cap <off|bytes|kb>**
-:   Set a hard payload cap size for tool results to avoid blowing out context.
+`/cache gemini` *off|cachedContents/...*
+: Gemini cached content.
 
-**/cache <on|off>**
-:   Toggle prompt caching globally.
+`/undo`
+: Remove last turn (does NOT revert filesystem).
 
-**/cache openai <in_memory|24h>**
-:   Set OpenAI prompt cache retention policies.
+`/new`
+: Start a fresh session.
 
-**/cache gemini <off|cachedContents/...>**
-:   Attach Google Gemini cached content.
+`/verbose`
+: Toggle output truncation.
 
-**/undo**
-:   Remove the last conversation turn. This does not revert filesystem changes.
+`/mcp list`
+: List MCP servers.
 
-**/new**
-:   Clear context and start a fresh session.
+`/mcp add` *name* `http` *url*
+: Add HTTP MCP server.
 
-**/mcp list**
-:   List configured MCP servers.
+`/mcp add` *name* `stdio` *cmd* \[*args...*\]
+: Add stdio MCP server.
 
-**/mcp add <name> http <url>**
-:   Add an MCP server over HTTP.
+`/mcp remove` *name*
+: Remove MCP server.
 
-**/mcp add <name> stdio <cmd> [args...]**
-:   Add an MCP server over stdio.
+`/agent` \[*name*\]
+: Set or clear active agent.
 
-**/mcp remove <name>** (or **rm**)
-:   Remove an MCP server.
+`/review`
+: Review changes (custom command, auto-created globally).
 
-**/agent [name]**
-:   Set or clear an active primary custom agent.
+`/login`
+: Show OAuth login status.
 
-**/review**
-:   Custom command that reviews the current session's changes (defined via `.agents/commands/`).
+`/login` *provider*
+: Login via OAuth (opens browser for device flow). Currently supports `anthropic`.
 
+`/logout` *provider*
+: Clear saved OAuth tokens.
 
-**/help**
-:   Display command help.
+`/help`
+: Command help.
 
-**/exit, /quit, /q**
-:   Leave the session.
+`/exit`, `/quit`, `/q`
+: Leave session.
 
 ## INLINE FEATURES
-**Shell Integration**
-:   Prefix user prompts with `!` to run shell commands inline directly into the context.
 
-**File & Skill Referencing**
-:   Prefix words with `@` to reference files or skills within prompts (supports tab completion).
+`!` prefix
+: Runs shell commands inline.
+
+`@` prefix
+: References files or skills (with tab completion).
 
 ## BUILT-IN TOOLS
-The agent has access to the following tools:
-*   **shell**: Execute bash commands and capture output. Repo inspection and targeted file edits are typically done here via `mc-edit`.
-*   **subagent**: Spawn a focused mini-agent with a prompt.
-*   **listSkills**: List discovered skills without loading full skill bodies.
-*   **readSkill**: Load one `SKILL.md` on demand.
-*   **webSearch**: Search the internet (requires EXA key).
-*   **webContent**: Fetch full page content from a URL (requires EXA key).
-*   **MCP tools**: Connected external tools attached dynamically from configured MCP servers.
-
-## FILE EDIT HELPER
-**mc-edit**
-:   Helper command used from shell for one exact-text edit on an existing file. On success it prints a human-readable plain unified diff to stdout followed by a short metadata block (`ok`, `path`, `changed`). If the edit is a no-op, it prints `(no changes)` plus the same metadata. Errors are written to stderr.
 
-## ENVIRONMENT
-**OPENCODE_API_KEY**
-:   OpenCode Zen API key (Recommended provider).
+**shell**
+: Execute bash commands; repo inspection and `mc-edit` edits happen here.
+
+**listSkills**
+: List discovered skills (metadata only).
+
+**readSkill**
+: Load one SKILL.md on demand.
+
+**webSearch**
+: Search the web (requires `EXA_API_KEY`).
+
+**webContent**
+: Fetch page content (requires `EXA_API_KEY`).
+
+MCP tools are connected dynamically from configured MCP servers.
+
+## FILE EDITING — mc-edit
+
+`mc-edit` is the helper for targeted file edits, invoked from **shell**.
+
+```
+mc-edit <path> (--old <text> | --old-file <path>) [--new <text> | --new-file <path>] [--cwd <path>]
+```
+
+- Applies one exact-text edit to an existing file.
+- The old text must match exactly once.
+- Omit `--new`/`--new-file` to delete the matched text.
+- Success: prints unified diff + metadata (`ok`, `path`, `changed`).
+- No-op: prints `(no changes)` + metadata.
+- Errors go to stderr.
+
+Workflow: inspect with **shell** → edit with **mc-edit** → verify with **shell**.
+
+## CUSTOM COMMANDS
+
+Drop a `.md` file in `.agents/commands/` (local) or `~/.agents/commands/` (global) and it becomes a `/command`. Filename equals command name (`standup.md` → `/standup`).
+
+`.claude/commands/*.md` is also supported.
+
+**Frontmatter fields:**
+
+`description`
+: Shown in `/help`.
+
+`model`
+: Optional metadata field.
+
+**Argument substitution:**
+
+`$ARGUMENTS` expands to the full argument string; `$1`–`$9` expand to positional tokens.
 
-**ANTHROPIC_API_KEY**
-:   Direct Anthropic API key.
+**Shell interpolation:**
+
+`` !`cmd` `` injects shell output at expansion time (10 s timeout).
+
+**Precedence:** custom commands shadow built-ins. Local overrides global.
+
+## CUSTOM AGENTS
+
+Drop a `.md` file in `.agents/agents/` (local) or `~/.agents/agents/` (global). Filename equals agent name. Activate with `/agent <name>`.
+
+`.claude/agents/*.md` is also supported.
+
+**Frontmatter fields:**
+
+`description`
+: Shown in `/help`.
+
+`model`
+: Optional metadata field.
+
+Body is the agent system prompt.
+
+## SKILLS
+
+Skills are reusable instruction files at `.agents/skills/<name>/SKILL.md`.
+
+`.claude/skills/<name>/SKILL.md` is also supported.
+
+**Frontmatter (both required):**
+
+`name`
+: Lowercase alphanumeric + hyphens, 1–64 chars.
+
+`description`
+: Help text.
+
+Skills are never auto-loaded. Load explicitly:
+
+- `@skill-name` in prompts (injects body wrapped in `<skill>` XML).
+- **listSkills** / **readSkill** tools at runtime.
+
+Local discovery walks up from cwd to the git worktree root.
+
+## CONFIGURATION
+
+Supports `.agents` and `.claude` layouts for commands, skills, agents, and context.
+
+Config roots: `.agents/`, `.claude/` — local (repo) or global (`~/`).
+
+**Context files** (one global + one local loaded):
+
+- Global: `~/.agents/AGENTS.md` → `~/.agents/CLAUDE.md`
+- Local: `./.agents/AGENTS.md` → `./CLAUDE.md` → `./AGENTS.md`
+
+**Precedence:**
+
+1. Local overrides global.
+2. Same scope: `.agents` wins over `.claude`.
+3. Skills: nearest ancestor directory wins.
+
+## ENVIRONMENT
 
-**OPENAI_API_KEY**
-:   Direct OpenAI API key.
+`OPENCODE_API_KEY`
+: OpenCode Zen (recommended).
 
-**GOOGLE_API_KEY** (or **GEMINI_API_KEY**)
-:   Direct Google Gemini API key.
+`ANTHROPIC_API_KEY`
+: Direct Anthropic.
 
-**OLLAMA_BASE_URL**
-:   Ollama local base URL (Defaults to `http://localhost:11434`).
+`OPENAI_API_KEY`
+: Direct OpenAI.
 
-**EXA_API_KEY**
-:   Enables built-in `webSearch` and `webContent` tools.
+`GOOGLE_API_KEY` / `GEMINI_API_KEY`
+: Direct Gemini.
 
-## FILES & DIRECTORIES
-**~/.config/mini-coder/**
-:   Application data directory. Contains `sessions.db` (SQLite database for session history, MCP server configs, and model metadata), `api.log`, and `errors.log`.
+`OLLAMA_BASE_URL`
+: Ollama local (defaults to `http://localhost:11434`).
 
-**.agents/ or .claude/ (Local or Global in ~/)**
-:   Configuration directories for advanced features:
-    *   **commands/*.md**: Custom slash commands.
-    *   **agents/*.md**: Custom behavioral wrappers or subagents.
-    *   **skills/<name>/SKILL.md**: Isolated context/instruction snippets.
+`EXA_API_KEY`
+: Enables **webSearch** / **webContent**.
 
-**AGENTS.md / CLAUDE.md**
-:   Auto-loaded system context files for project-specific instructions.
+## FILES
 
-## CORE FEATURES & ARCHITECTURE
-*   **Multi-Provider LLM Routing**: Automatically discovers API keys to route to OpenCode (Zen), Anthropic, OpenAI, Google/Gemini, or local Ollama instances.
-*   **Session Memory**: Persists conversation history in a local SQLite database, allowing users to resume past sessions effortlessly.
-*   **Subagent Delegation**: Includes a tool to spawn parallel instances of itself to tackle independent subtasks simultaneously (up to 10 levels deep).
-*   **Model Context Protocol (MCP)**: Native support for connecting external tools via MCP servers over HTTP or stdio.
-*   **Prompt Caching**: Configurable caching behaviors for supported providers (OpenAI, Gemini).
-*   **Undo Functionality**: Remove the last conversation turn from the current session history. It does not restore filesystem changes.
+`~/.config/mini-coder/`
+: App data directory (sessions.db, api.log, errors.log).
 
+`.agents/` or `.claude/`
+: Config directories for commands, agents, skills.
 
+`AGENTS.md` / `CLAUDE.md`
+: Project context files.

package/lefthook.yml

@@ -0,0 +1,15 @@
+pre-commit:
+  parallel: true
+  commands:
+    jscpd:
+      run: bun run jscpd
+    knip:
+      run: bun run knip
+    typecheck:
+      run: bun run typecheck
+    format:
+      run: bun run format
+    lint:
+      run: bun run lint
+    test:
+      run: bun run test

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "mini-coder",
-	"version": "0.1.0",
+	"version": "0.1.2",
 	"description": "A small, fast CLI coding agent",
 	"module": "src/index.ts",
 	"type": "module",
@@ -18,7 +18,7 @@
 		"test": "bun test --only-failures",
 		"test:verbose": "bun test",
 		"jscpd": "jscpd src",
-		"ui-oneshot": "bun scripts/ui-oneshot.ts"
+		"prepare": "lefthook install"
 	},
 	"dependencies": {
 		"@ai-sdk/anthropic": "^3.0.60",
@@ -37,6 +37,7 @@
 		"@types/bun": "latest",
 		"jscpd": "^4.0.8",
 		"knip": "^5.86.0",
+		"lefthook": "^2.1.4",
 		"typescript": "^5.9.3"
 	},
 	"knip": {

package/docs/configs.md

@@ -1,118 +0,0 @@
-# Config conventions
-
-mini-coder supports both its native `.agents` convention and `.claude` layouts for commands, skills, and agents.
-
-Only commands, skills, agents, and context files are loaded from these roots. Hook directories are ignored.
-
-Discovery is not identical for every config type:
-
-- **Commands** and **agents** are loaded from the current working directory and the home directory only.
-- **Skills** are loaded from the home directory plus local directories discovered by walking up from the current working directory to the git worktree root.
-- **Context files** are only loaded from the current working directory and the home directory.
-
-## Supported config roots
-
-| Root | Purpose |
-|---|---|
-| `.agents/` | mini-coder native config |
-| `.claude/` | Alternate config layout supported by mini-coder |
-
-Each root can exist in:
-
-- **Local (repo):** `./.agents`, `./.claude`
-- **Global (home):** `~/.agents`, `~/.claude`
-
-## Commands
-
-Supported locations:
-
-- `./.agents/commands/*.md`
-- `~/.agents/commands/*.md`
-- `./.claude/commands/*.md`
-- `~/.claude/commands/*.md`
-
-Format:
-
-```md
----
-description: Optional help text
-model: optional/model-override
----
-
-Prompt template body with $ARGUMENTS and $1..$9 support.
-```
-
-Filename becomes the command name (`review.md` => `/review`).
-
-## Skills
-
-Supported locations:
-
-- local: `./.agents/skills/<skill-name>/SKILL.md` and `./.claude/skills/<skill-name>/SKILL.md`
-- global: `~/.agents/skills/<skill-name>/SKILL.md` and `~/.claude/skills/<skill-name>/SKILL.md`
-
-For local skills, mini-coder searches not just the current working directory, but each ancestor directory up to the git worktree root.
-
-Format:
-
-```md
----
-name: required-skill-name
-description: Required help text
----
-
-Skill instructions/content.
-```
-
-Both `name` and `description` are required. Invalid skills are skipped with a warning.
-
-## Agents
-
-Supported locations:
-
-- `./.agents/agents/*.md`
-- `~/.agents/agents/*.md`
-- `./.claude/agents/*.md`
-- `~/.claude/agents/*.md`
-
-Format:
-
-```md
----
-description: Optional help text
-model: optional/model-override
-mode: optional agent mode
----
-
-Agent system prompt.
-```
-
-## Context files
-
-mini-coder loads at most one global context file and at most one local context file, then includes both when present.
-
-Global lookup order:
-
-1. `~/.agents/AGENTS.md`
-2. `~/.agents/CLAUDE.md`
-
-Local lookup order:
-
-1. `./.agents/AGENTS.md`
-2. `./CLAUDE.md`
-3. `./AGENTS.md`
-
-Injection order:
-
-1. Global context (if found)
-2. Local context (if found)
-
-## Precedence and conflicts
-
-Precedence rules for commands, skills, and agents:
-
-1. **Local overrides global**
-2. At the **same scope** (both local or both global), if `.agents` and `.claude` define the same name, **`.agents` wins**
-3. For **skills only**, when the same skill name exists in multiple local ancestor directories, the skill nearest to the current working directory wins
-
-When same-scope `.agents` / `.claude` conflicts are detected for commands, skills, or agents, mini-coder prints a warning and uses the `.agents` version.

package/docs/custom-agents.md

@@ -1,69 +0,0 @@
-# Custom Agents
-
-A custom agent is a reusable system prompt with an optional model override.
-You can activate one with `/agent <name>`, and non-`primary` agents are also exposed to the `subagent` tool.
-
-mini-coder is shell-first, so custom agents should assume repo inspection and verification happen through shell, with targeted edits done via `mc-edit` invoked from shell.
-
-## Where to put them
-
-| Location | Scope |
-|---|---|
-| `.agents/agents/*.md` | Current repo only |
-| `~/.agents/agents/*.md` | All projects (global) |
-| `.claude/agents/*.md` | Current repo only (`.claude` layout) |
-| `~/.claude/agents/*.md` | All projects (global, `.claude` layout) |
-
-Local agents override global ones with the same name. At the same scope, `.agents` wins over `.claude`.
-
-## Create an agent
-
-The filename becomes the agent name.
-
-`~/.agents/agents/reviewer.md`:
-
-```md
----
-description: Strict code reviewer focused on bugs and structure
-model: zen/claude-sonnet-4-6
----
-
-You are a senior engineer doing a code review. Be direct and specific.
-Cite file and line number for every finding. Flag bugs first, then
-structure issues, then style — only if they violate project conventions.
-No flattery. End with a one-line verdict.
-```
-
-Then in the REPL:
-
-```
-/agent reviewer
-review the auth module for race conditions
-```
-
-## Frontmatter fields
-
-| Field | Required | Description |
-|---|---|---|
-| `description` | No | Shown in `/help`. Defaults to filename. |
-| `model` | No | Override the active model for this agent. |
-| `mode` | No | Controls whether the agent is exposed through the `subagent` tool. `primary` excludes it from that tool and is intended for `/agent`. `subagent`, `all`, and an omitted value all keep it available to the `subagent` tool. Any loaded agent can currently still be selected with `/agent <name>`. |
-
-The markdown body (after frontmatter) is the agent's system prompt.
-
-## Combining with files
-
-File references are resolved before the prompt is sent:
-
-```
-/agent reviewer
-@src/auth/session.ts check this file for issues
-```
-
-## Listing agents
-
-```
-/help
-```
-
-Agents are listed in magenta, tagged `(local)` or `(global)`.