mini-coder 0.0.20 → 0.0.21

package/docs/configs.md

@@ -2,6 +2,14 @@
 
 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 |
@@ -40,23 +48,23 @@ Filename becomes the command name (`review.md` => `/review`).
 
 Supported locations:
 
-- `./.agents/skills/<skill-name>/SKILL.md`
-- `~/.agents/skills/<skill-name>/SKILL.md`
-- `./.claude/skills/<skill-name>/SKILL.md`
-- `~/.claude/skills/<skill-name>/SKILL.md`
+- 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: optional-skill-name
-description: Optional help text
+name: required-skill-name
+description: Required help text
 ---
 
 Skill instructions/content.
 ```
 
-If `name` is omitted, folder name is used.
+Both `name` and `description` are required. Invalid skills are skipped with a warning.
 
 ## Agents
 
@@ -105,5 +113,6 @@ 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 conflicts are detected for commands, skills, or agents, mini-coder prints a warning and uses the `.agents` version.
+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

@@ -3,6 +3,8 @@
 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 |
@@ -39,8 +41,6 @@ Then in the REPL:
 review the auth module for race conditions
 ```
 
-You can also mention `@reviewer` in a prompt as a naming convention, and agent names participate in `@` tab completion alongside skills and files.
-
 ## Frontmatter fields
 
 | Field | Required | Description |
@@ -60,10 +60,6 @@ File references are resolved before the prompt is sent:
 @src/auth/session.ts check this file for issues
 ```
 
-## Tab completion
-
-Type `@` and press `Tab` to autocomplete agent names alongside skills and files.
-
 ## Listing agents
 
 ```

package/docs/custom-commands.md

@@ -2,6 +2,8 @@
 
 Custom commands let you define reusable prompts that run as `/command` in the mini-coder REPL.
 
+mini-coder is shell-first: when a command needs repo inspection or verification, tell it to use shell. When it needs a targeted file edit, tell it to invoke `mc-edit` from shell rather than relying on old local file-edit tools.
+
 ## Where to put them
 
 | Location | Scope |
@@ -59,9 +61,9 @@ model: zen/claude-haiku-4-5
 
 Search the codebase for: $ARGUMENTS
 
-Use glob, grep, and read tools to explore thoroughly. Report all
+Use shell and skill-loading tools as needed to explore thoroughly. Report all
 relevant files, key code snippets with line numbers, and a short summary.
-Be exhaustive but concise. No edits — read only.
+Be exhaustive but concise. No edits.
 ```
 
 ```
@@ -113,11 +115,11 @@ lightweight tasks regardless of what the session is currently set to.
 
 ```md
 ---
-description: Quick grep for a symbol
+description: Quick symbol search
 model: zen/claude-haiku-4-5
 ---
 
-Find all usages of $ARGUMENTS across the codebase using grep and glob.
+Find all usages of $ARGUMENTS across the codebase using shell.
 List each occurrence with file path and line number. No explanations needed.
 ```
 
@@ -125,8 +127,7 @@ Large models for deep analysis, small models for search and lookup.
 
 ## Precedence
 
-Custom commands shadow built-ins. If you create `.agents/commands/plan.md`
-it will replace the built-in `/plan` for that project. The global `/review`
+Custom commands shadow built-ins. The global `/review`
 command (auto-created at `~/.agents/commands/review.md` on first run) works
 the same way — a local `.agents/commands/review.md` will override it.
 

package/docs/mini-coder.1.md

@@ -29,7 +29,7 @@
 :   Display help information.
 
 **[prompt]**
-:   Optional one-shot prompt text before entering interactive mode.
+:   Optional one-shot prompt text. Runs once, then exits.
 
 ## INTERACTIVE COMMANDS
 Inside the interactive session, the following slash commands are available:
@@ -61,14 +61,8 @@ Inside the interactive session, the following slash commands are available:
 **/cache gemini <off|cachedContents/...>**
 :   Attach Google Gemini cached content.
 
-**/plan**
-:   Toggle read-only planning mode.
-
-**/ralph**
-:   Toggle autonomous execution looping.
-
 **/undo**
-:   Revert the last turn and restore files.
+:   Remove the last conversation turn. This does not revert filesystem changes.
 
 **/new**
 :   Clear context and start a fresh session.
@@ -88,6 +82,10 @@ Inside the interactive session, the following slash commands are available:
 **/agent [name]**
 :   Set or clear an active primary custom agent.
 
+**/review**
+:   Custom command that reviews the current session's changes (defined via `.agents/commands/`).
+
+
 **/help**
 :   Display command help.
 
@@ -98,21 +96,22 @@ Inside the interactive session, the following slash commands are available:
 **Shell Integration**
 :   Prefix user prompts with `!` to run shell commands inline directly into the context.
 
-**File & Agent Referencing**
-:   Prefix words with `@` to reference files, custom agents, or skills within prompts (supports tab completion).
+**File & Skill Referencing**
+:   Prefix words with `@` to reference files or skills within prompts (supports tab completion).
 
 ## BUILT-IN TOOLS
 The agent has access to the following tools:
-*   **glob**: Discover files by glob pattern across the project.
-*   **grep**: Search file contents using regular expressions.
-*   **read**: Read file contents with line-range pagination support.
-*   **create**: Write a new file or completely overwrite an existing one.
-*   **replace**: Replace or delete targeted lines using hashline anchors.
-*   **insert**: Insert new lines before/after an anchor without replacing existing content.
-*   **shell**: Execute bash commands and capture output.
+*   **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**
@@ -135,14 +134,13 @@ The agent has access to the following tools:
 
 ## FILES & DIRECTORIES
 **~/.config/mini-coder/**
-:   Application data directory. Contains `sessions.db` (SQLite database for session history, tool snapshots, MCP server configs, and model metadata), `api.log`, and `errors.log`.
+:   Application data directory. Contains `sessions.db` (SQLite database for session history, MCP server configs, and model metadata), `api.log`, and `errors.log`.
 
 **.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.
-    *   **hooks/post-<tool>**: Executable scripts triggered upon tool execution.
 
 **AGENTS.md / CLAUDE.md**
 :   Auto-loaded system context files for project-specific instructions.
@@ -151,8 +149,8 @@ The agent has access to the following tools:
 *   **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).
-*   **Autonomous Mode (Ralph)**: An autonomous looping mode that runs tasks in an isolated context loop (up to 20 iterations) until completion.
-*   **Plan Mode**: A read-only thinking mode utilizing read tools + MCP, safely analyzing code without making mutations or executing shell commands.
 *   **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**: Roll back the last conversation turn, cleanly restoring previous file states and git history via snapshots.
+*   **Undo Functionality**: Remove the last conversation turn from the current session history. It does not restore filesystem changes.
+
+

package/docs/skills.md

@@ -2,6 +2,8 @@
 
 Skills are reusable instruction files discovered automatically from local and global directories.
 
+When a skill tells mini-coder how to work with files, prefer shell for inspection/search/verification and `mc-edit` from shell for targeted edits.
+
 - The model sees **skill metadata only** by default (name, description, source).
 - Full `SKILL.md` content is loaded **on demand**:
 	- when explicitly requested with the runtime skill tools (`listSkills` / `readSkill`), or
@@ -28,19 +30,22 @@ If multiple skills share the same `name`, precedence is deterministic:
 2. Any local skill wins over global.
 3. At the same scope/path level, `.agents` wins over `.claude`.
 
-## Frontmatter validation
+## Frontmatter
 
-`SKILL.md` frontmatter must include:
+`SKILL.md` frontmatter supports:
 
-- `name` (required)
-- `description` (required)
+- `name` (**required**)
+- `description` (**required**)
 
 `name` constraints:
 
 - lowercase alphanumeric and hyphen format (`^[a-z0-9]+(?:-[a-z0-9]+)*$`)
 - 1–64 characters
 
-Invalid skills are skipped with warnings. Unknown frontmatter fields are allowed.
+Unknown frontmatter fields are allowed.
+
+If either `name` or `description` is missing, mini-coder skips the skill and prints a warning.
+
 
 ## Create a skill
 

package/package.json

@@ -1,18 +1,19 @@
 {
 	"name": "mini-coder",
-	"version": "0.0.20",
+	"version": "0.0.21",
 	"description": "A small, fast CLI coding agent",
 	"module": "src/index.ts",
 	"type": "module",
 	"bin": {
-		"mc": "dist/mc.js"
+		"mc": "dist/mc.js",
+		"mc-edit": "dist/mc-edit.js"
 	},
 	"scripts": {
 		"build": "bun run scripts/build.ts",
 		"dev": "bun run src/index.ts",
 		"typecheck": "tsc --noEmit",
 		"lint": "biome check src",
-		"format": "biome format --write src",
+		"format": "biome check --write src",
 		"knip": "knip",
 		"test": "bun test --only-failures",
 		"test:verbose": "bun test",
@@ -25,8 +26,9 @@
 		"@ai-sdk/openai-compatible": "^2.0.36",
 		"@modelcontextprotocol/sdk": "^1.27.1",
 		"ai": "^6.0.127",
-		"ignore": "^7.0.5",
+		"diff": "^8.0.3",
 		"yoctocolors": "^2.1.2",
+		"yoctomarkdown": "^0.0.4",
 		"zod": "^4.3.6"
 	},
 	"devDependencies": {
@@ -36,5 +38,10 @@
 		"knip": "^5.86.0",
 		"typescript": "^5.9.3"
 	},
+	"knip": {
+		"entry": [
+			"src/mc-edit.ts"
+		]
+	},
 	"license": "MIT"
 }

package/research.md

@@ -0,0 +1,38 @@
+I want your help exploring how could we use yoctocolor to add color ouput to commonly used shell commands. Let's first check the db, check the recent past sessions for a sample. Then check for the shell usage and assert the most common commands
+
+Response:
+
+## Shell Usage Analysis (from 101 sessions)
+
+Most common commands:
+| Command | Count | Opportunity |
+|---------|-------|-------------|
+| `cat` | 72 | File content preview |
+| `git` | 54 | Status/diff output |
+| `bun` | 32 | Test/build output |
+| `sed` | 29 | Transform preview |
+| `mc-edit` | 26 | File edits |
+| `nl` | 12 | Line numbers |
+| `rg` | 11 | Search matches |
+| `npm` | 9 | Package output |
+| `grep` | 7 | Match highlighting |
+| `ls` | 5 | File listings |
+
+## Current Shell Output Coloring (in `tool-result-renderers.ts`)
+
+The shell result renderer already uses yoctocolors:
+
+- **Status badges**: `c.green("done")` / `c.red("error")` / `c.yellow("timeout")`
+- **Stderr lines**: `c.red()` for error emphasis
+- **Stdout/stderr line separators**: `c.dim()` or colored pipe character
+
+## Enhancement Opportunities
+
+1. **Command syntax highlighting** - Color `git`, `bun`, `npm` commands differently in the tool call line
+2. **File path highlighting** - Use `c.cyan()` for paths in output
+3. **Git diffs from mc-edit** - Render a colored diff
+4. **Line numbers** - `nl` output could use `c.yellow()` for numbers
+5. **Git output** - Branch names in `c.cyan()`, commit hashes in `c.yellow()`, file statuses (M/A/D) in color
+6. **rg/grep matches** - Highlight matching text in `c.greenBright()` or `c.yellow()`
+7. **Exit code** - Non-zero codes in `c.red()` or `c.yellow()`
+8. **Test output** - `bun test` results: passes in `c.green()`, fails in `c.red()`, skips in `c.yellow()`

package/docs/tool-hooks.md

@@ -1,142 +0,0 @@
-# Tool Hooks
-
-A tool hook is an executable script that runs automatically after a specific tool call succeeds. Use hooks to trigger side effects — linting, formatting, logging, notifications — without modifying the agent's behaviour.
-
-> Hooks fire **after** the tool succeeds. Failures are silently swallowed and never crash the agent.
-
-## Where to put them
-
-Hooks live in a `hooks/` folder inside an `.agents` config root:
-
-| Location | Scope |
-|---|---|
-| `.agents/hooks/post-<tool>` | Current repo only |
-| `~/.agents/hooks/post-<tool>` | All projects (global) |
-
-Local hooks take precedence over global ones. The filename must match `post-<tool>` exactly — no extension.
-
-## Supported tools
-
-| Tool | Hook filename |
-|---|---|
-| `glob` | `post-glob` |
-| `grep` | `post-grep` |
-| `read` | `post-read` |
-| `create` | `post-create` |
-| `replace` | `post-replace` |
-| `insert` | `post-insert` |
-| `shell` | `post-shell` |
-
-MCP tools are not hookable.
-
-## Script requirements
-
-The script must be executable (`chmod +x`). It can be written in any language — bash, Python, Node, etc. It receives context via environment variables and its exit code is reported in the UI (zero = success, non-zero = failure).
-
-## Environment variables
-
-All hooks receive:
-
-| Variable | Description |
-|---|---|
-| `TOOL` | Name of the tool that fired |
-| `CWD` | Working directory of the session |
-
-Plus tool-specific variables:
-
-### `post-create`
-
-| Variable | Description |
-|---|---|
-| `FILEPATH` | Absolute path of the file written |
-| `DIFF` | Unified diff of the change |
-| `CREATED` | `true` if the file was newly created, `false` if overwritten |
-
-### `post-replace`
-
-| Variable | Description |
-|---|---|
-| `FILEPATH` | Absolute path of the file modified |
-| `DIFF` | Unified diff of the change |
-| `DELETED` | `true` if lines were deleted (no replacement content), `false` otherwise |
-
-### `post-insert`
-
-| Variable | Description |
-|---|---|
-| `FILEPATH` | Absolute path of the file modified |
-| `DIFF` | Unified diff of the change |
-
-### `post-shell`
-
-| Variable | Description |
-|---|---|
-| `COMMAND` | The shell command that was run |
-| `EXIT_CODE` | Exit code of the command |
-| `TIMED_OUT` | `true` if the command timed out |
-| `STDOUT` | Captured standard output |
-| `STDERR` | Captured standard error |
-
-### `post-glob`
-
-| Variable | Description |
-|---|---|
-| `PATTERN` | The glob pattern that was searched |
-
-### `post-grep`
-
-| Variable | Description |
-|---|---|
-| `PATTERN` | The regex pattern that was searched |
-
-### `post-read`
-
-| Variable | Description |
-|---|---|
-| `FILEPATH` | Absolute path of the file read |
-
-## Examples
-
-### Auto-format on write
-
-`.agents/hooks/post-create`:
-
-```bash
-#!/usr/bin/env bash
-# Run the project formatter whenever the agent creates or overwrites a file.
-bun run format -- "$FILEPATH"
-```
-
-```bash
-chmod +x .agents/hooks/post-create
-```
-
-Pair with a matching `post-replace` and `post-insert` to cover all write tools.
-
-### Log every shell command
-
-`~/.agents/hooks/post-shell`:
-
-```bash
-#!/usr/bin/env bash
-# Append a record of every shell command to a global audit log.
-echo "$(date -u +%FT%TZ)  exit=$EXIT_CODE  $COMMAND" >> ~/.config/mini-coder/shell-audit.log
-```
-
-```bash
-chmod +x ~/.agents/hooks/post-shell
-```
-
-### Notify on file write
-
-`.agents/hooks/post-replace`:
-
-```bash
-#!/usr/bin/env bash
-# macOS notification when the agent edits a file.
-osascript -e "display notification \"$FILEPATH\" with title \"mini-coder wrote a file\""
-```
-
-## Hook lookup
-
-Hooks are resolved once at session start and cached in memory — there is no filesystem access per tool call. Changing a hook script takes effect on the next session.