mini-coder 0.0.17 → 0.0.19

package/docs/configs.md

@@ -1,13 +1,13 @@
 # Config conventions
 
-mini-coder supports both its native `.agents` convention and Claude Code's `.claude` convention for commands and skills.
+mini-coder supports both its native `.agents` convention and `.claude` layouts for commands, skills, and agents.
 
 ## Supported config roots
 
 | Root | Purpose |
 |---|---|
 | `.agents/` | mini-coder native config |
-| `.claude/` | Claude Code-compatible commands/skills |
+| `.claude/` | Alternate config layout supported by mini-coder |
 
 Each root can exist in:
 
@@ -58,20 +58,52 @@ Skill instructions/content.
 
 If `name` is omitted, folder name is used.
 
-## Agents (mini-coder specific)
+## Agents
 
-Custom subagents are configured in `.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:
 
-(There is no `.claude` compatibility path for agents. Claude doesn't have custom subagents)
+1. Global context (if found)
+2. Local context (if found)
 
 ## Precedence and conflicts
 
-Precedence rules:
+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 command/skill name, **`.agents` wins**
+2. At the **same scope** (both local or both global), if `.agents` and `.claude` define the same name, **`.agents` wins**
 
-When same-scope conflicts are detected for commands/skills, mini-coder prints a warning and uses the `.agents` version.
+When same-scope conflicts are detected for commands, skills, or agents, mini-coder prints a warning and uses the `.agents` version.

package/docs/custom-agents.md

@@ -1,7 +1,7 @@
 # Custom Agents
 
-An agent is a subagent with a custom system prompt and optional model override.
-Use `@agent-name` anywhere in your prompt to route the message through it.
+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.
 
 ## Where to put them
 
@@ -9,8 +9,10 @@ Use `@agent-name` anywhere in your prompt to route the message through it.
 |---|---|
 | `.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.
+Local agents override global ones with the same name. At the same scope, `.agents` wins over `.claude`.
 
 ## Create an agent
 
@@ -33,12 +35,11 @@ No flattery. End with a one-line verdict.
 Then in the REPL:
 
 ```
-@reviewer review the auth module for race conditions
+/agent reviewer
+review the auth module for race conditions
 ```
 
-The rest of the message (everything except the `@reviewer` token) becomes
-the prompt. The agent runs in its own context window and returns its output
-into the conversation.
+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
 
@@ -46,22 +47,22 @@ into the conversation.
 |---|---|---|
 | `description` | No | Shown in `/help`. Defaults to filename. |
 | `model` | No | Override the active model for this agent. |
-| `mode` | No | `primary` — interactive only (via `/agent <name>`); `subagent` — callable via the `subagent` tool only (default); `all` — both. |
-
+| `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 agent fires:
+File references are resolved before the prompt is sent:
 
 ```
-@reviewer @src/auth/session.ts check this file for issues
+/agent reviewer
+@src/auth/session.ts check this file for issues
 ```
 
 ## Tab completion
 
-Type `@` and press `Tab` to autocomplete agent names alongside files.
+Type `@` and press `Tab` to autocomplete agent names alongside skills and files.
 
 ## Listing agents
 
@@ -69,4 +70,4 @@ Type `@` and press `Tab` to autocomplete agent names alongside files.
 /help
 ```
 
-Agents are listed in magenta, tagged `(local)` or `(global)`.
+Agents are listed in magenta, tagged `(local)` or `(global)`.

package/docs/custom-commands.md

@@ -8,8 +8,10 @@ Custom commands let you define reusable prompts that run as `/command` in the mi
 |---|---|
 | `.agents/commands/*.md` | Current repo only |
 | `~/.agents/commands/*.md` | All projects (global) |
+| `.claude/commands/*.md` | Current repo only (Claude-compatible) |
+| `~/.claude/commands/*.md` | All projects (global, Claude-compatible) |
 
-Local commands override global ones with the same name.
+Local commands override global ones with the same name. At the same scope, `.agents` wins over `.claude`.
 
 ## Create a command
 
@@ -21,7 +23,6 @@ Create a markdown file. The filename becomes the command name.
 ---
 description: Summarise what changed since yesterday
 model: zen/claude-haiku-4-5
-
 ---
 
 Run `!`git log --oneline --since=yesterday`` and summarise the changes
@@ -44,8 +45,6 @@ Then in the REPL:
 | `subtask` | No | Set to `true` to force subagent execution (OpenCode-compatible alias for `context: fork`). |
 | `agent` | No | Run the command under a named agent's system prompt (only applies when `context: fork`). |
 
-
-
 ## Arguments
 
 Use `$ARGUMENTS` for the full argument string, or `$1`, `$2`, … `$9` for individual tokens.
@@ -56,7 +55,6 @@ Use `$ARGUMENTS` for the full argument string, or `$1`, `$2`, … `$9` for indiv
 ---
 description: Search the codebase for a topic
 model: zen/claude-haiku-4-5
-
 ---
 
 Search the codebase for: $ARGUMENTS
@@ -117,7 +115,6 @@ lightweight tasks regardless of what the session is currently set to.
 ---
 description: Quick grep for a symbol
 model: zen/claude-haiku-4-5
-
 ---
 
 Find all usages of $ARGUMENTS across the codebase using grep and glob.
@@ -126,7 +123,6 @@ List each occurrence with file path and line number. No explanations needed.
 
 Large models for deep analysis, small models for search and lookup.
 
-
 ## Precedence
 
 Custom commands shadow built-ins. If you create `.agents/commands/plan.md`
@@ -134,7 +130,6 @@ it will replace the built-in `/plan` for that project. 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.
 
-
 ## Listing commands
 
 ```
@@ -142,4 +137,4 @@ the same way — a local `.agents/commands/review.md` will override it.
 ```
 
 Custom commands are listed at the bottom under **custom commands**, tagged
-with `(local)` or `(global)`.
+with `(local)` or `(global)`.

package/docs/mini-coder.1.md

@@ -0,0 +1,158 @@
+# MINI-CODER(1)
+
+## NAME
+**mini-coder** (executable: `mc`) - A small, fast CLI coding agent built for developers.
+
+## SYNOPSIS
+`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.
+
+## OPTIONS
+**-m, --model <id>**
+:   Specify the model to use (e.g., `zen/claude-sonnet-4-6`).
+
+**-c, --continue**
+:   Continue the most recent session.
+
+**-r, --resume <id>**
+:   Resume a specific session by its ID.
+
+**-l, --list**
+:   List recent sessions.
+
+**--cwd <path>**
+:   Set the working directory (defaults to current directory).
+
+**-h, --help**
+:   Display help information.
+
+**[prompt]**
+:   Optional one-shot prompt text before entering interactive mode.
+
+## INTERACTIVE COMMANDS
+Inside the interactive session, the following slash commands are available:
+
+**/model**
+:   List all available models, indicating free models and context sizes.
+
+**/model <id>**
+:   Switch to a specific model.
+
+**/model effort <low|medium|high|xhigh|off>**
+:   Configure reasoning effort levels for models that support it.
+
+**/reasoning [on|off]**
+:   Toggle the display of the model's reasoning/thought process.
+
+**/context prune <off|balanced|aggressive>**
+:   Configure context window pruning strategies.
+
+**/context cap <off|bytes|kb>**
+:   Set a hard payload cap size for tool results to avoid blowing out context.
+
+**/cache <on|off>**
+:   Toggle prompt caching globally.
+
+**/cache openai <in_memory|24h>**
+:   Set OpenAI prompt cache retention policies.
+
+**/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.
+
+**/new**
+:   Clear context and start a fresh session.
+
+**/mcp list**
+:   List configured MCP servers.
+
+**/mcp add <name> http <url>**
+:   Add an MCP server over HTTP.
+
+**/mcp add <name> stdio <cmd> [args...]**
+:   Add an MCP server over stdio.
+
+**/mcp remove <name>** (or **rm**)
+:   Remove an MCP server.
+
+**/agent [name]**
+:   Set or clear an active primary custom agent.
+
+**/help**
+:   Display command help.
+
+**/exit, /quit, /q**
+:   Leave the session.
+
+## INLINE FEATURES
+**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).
+
+## 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.
+*   **subagent**: Spawn a focused mini-agent with a prompt.
+*   **webSearch**: Search the internet (requires EXA key).
+*   **webContent**: Fetch full page content from a URL (requires EXA key).
+
+## ENVIRONMENT
+**OPENCODE_API_KEY**
+:   OpenCode Zen API key (Recommended provider).
+
+**ANTHROPIC_API_KEY**
+:   Direct Anthropic API key.
+
+**OPENAI_API_KEY**
+:   Direct OpenAI API key.
+
+**GOOGLE_API_KEY** (or **GEMINI_API_KEY**)
+:   Direct Google Gemini API key.
+
+**OLLAMA_BASE_URL**
+:   Ollama local base URL (Defaults to `http://localhost:11434`).
+
+**EXA_API_KEY**
+:   Enables built-in `webSearch` and `webContent` 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`.
+
+**.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.
+
+## 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).
+*   **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.

package/docs/skills.md

@@ -15,8 +15,10 @@ Each skill is a folder containing a `SKILL.md`:
 |---|---|
 | `.agents/skills/<name>/SKILL.md` | Current repo only |
 | `~/.agents/skills/<name>/SKILL.md` | All projects (global) |
+| `.claude/skills/<name>/SKILL.md` | Current repo only (Claude-compatible) |
+| `~/.claude/skills/<name>/SKILL.md` | All projects (global, Claude-compatible) |
 
-Local skills override global ones with the same name.
+Local skills override global ones with the same name. At the same scope, `.agents` wins over `.claude`.
 
 ## Create a skill
 
@@ -60,7 +62,7 @@ included in the message sent to the LLM.
 
 ## Tab completion
 
-Type `@` and press `Tab` to autocomplete skill names alongside files.
+Type `@` and press `Tab` to autocomplete skill names alongside agents and files.
 
 ## Listing skills
 
@@ -68,4 +70,4 @@ Type `@` and press `Tab` to autocomplete skill names alongside files.
 /help
 ```
 
-Skills are listed in yellow, tagged `(local)` or `(global)`.
+Skills are listed in yellow, tagged `(local)` or `(global)`.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "mini-coder",
-	"version": "0.0.17",
+	"version": "0.0.19",
 	"description": "A small, fast CLI coding agent",
 	"module": "src/index.ts",
 	"type": "module",

package/docs/chatgpt-subscription-auth.md

@@ -1,68 +0,0 @@
-# ChatGPT/Codex subscription auth notes
-
-mini-coder does **not** currently support logging in with a ChatGPT Plus/Pro/Codex subscription.
-
-## Why
-
-We looked at two implementations:
-
-- OpenCode in `/tmp/opencode-src`
-- official Codex in `/tmp/openai-codex/codex-rs`
-
-Both rely on OpenAI **first-party/private** auth and backend APIs rather than a documented public developer API.
-
-## What those implementations do
-
-### Auth
-
-They use OAuth-like flows against `https://auth.openai.com`, including:
-
-- browser login with PKCE and a localhost callback server
-- device-code / headless login
-- refresh tokens via `POST /oauth/token`
-
-Both also rely on a hardcoded first-party client id embedded in their source trees.
-
-Examples:
-
-- official Codex: `/tmp/openai-codex/codex-rs/core/src/auth.rs`
-- OpenCode: `/tmp/opencode-src/packages/opencode/src/plugin/codex.ts`
-
-### Runtime API
-
-After login, requests are sent to ChatGPT backend endpoints such as:
-
-- `https://chatgpt.com/backend-api/codex`
-- `https://chatgpt.com/backend-api/codex/responses`
-
-with headers like:
-
-- `Authorization: Bearer <oauth access token>`
-- `ChatGPT-Account-Id: <account id>`
-
-Examples:
-
-- official Codex: `/tmp/openai-codex/codex-rs/core/src/model_provider_info.rs`
-- official Codex headers: `/tmp/openai-codex/codex-rs/backend-client/src/client.rs`
-- OpenCode rewrite layer: `/tmp/opencode-src/packages/opencode/src/plugin/codex.ts`
-
-## Why mini-coder is not adopting this
-
-- It depends on undocumented/private auth endpoints.
-- It depends on a hardcoded first-party client id.
-- It depends on private ChatGPT backend routes.
-- Browser login would require running a local callback server.
-- Even the official Codex source does not expose a clean public API-based alternative here.
-
-## Future stance
-
-We may revisit support if OpenAI exposes a stable, documented path for:
-
-- ChatGPT subscription login for third-party tools, or
-- a public Codex/ChatGPT backend API intended for external clients
-
-Until then, mini-coder only supports providers with clearer public integration paths.
-
-## Note
-
-If you want a supported hosted integration instead of ChatGPT subscription auth, mini-coder already supports OpenCode Zen via `OPENCODE_API_KEY`. See the existing `zen/<model>` provider path.