mini-coder

mini-coder (mc) is a terminal coding agent. The current main branch is a Bun/TypeScript implementation focused on reading files, running shell commands, editing code, and writing new files with a small core tool surface.

Lean runtime. The project uses pi-ai for provider APIs, streaming, tool calling, usage tracking, and OAuth, plus cel-tui for the terminal UI.
Streaming interface. Assistant text, reasoning, tool calls, and tool output are rendered as they arrive.
Local state. Settings, OAuth credentials, and sessions are stored under ~/.config/mini-coder/.

Tools

The current built-in runtime tools are intentionally small. Multi-step work is delegated to task; direct bash and edit calls remain available for immediate actions.

bash

Executes shell commands in the current working directory, strips ANSI output, reports the exit code, and writes very large results to a temporary file after a short preview.

edit

Performs exact-text replacement in one file, creates new files when oldText is empty, and refuses missing or ambiguous matches.

task

Runs a bounded subagent with the same model and prompt context for exploration or implementation work that needs more than one direct tool call.

Interface

The TUI is a scrollable conversation log with markdown rendering, tool call blocks, a multiline input, and status pills for model, working directory, git branch, activity, and context usage.

Controls

Enter submits the current message.
Escape aborts a running turn or clears a non-empty draft.
Ctrl+P opens the menu for providers, models, reasoning effort, and cwd-scoped sessions.
Ctrl+C, Ctrl+D, or Ctrl+Q exits cleanly.
:q exits; :n or /new starts a fresh session.
Mouse wheel scrolling reviews conversation history.

Menu actions

Switch to an available API-key or OAuth-backed provider.
Choose a model from the selected provider.
Set reasoning effort: minimal, low, medium, high, or xhigh.
Resume saved sessions for the current working directory.

Settings, sessions, and context

Global settings live in ~/.config/mini-coder/settings.json. The current schema stores provider, model, effort, and optional customProviders entries using the pi-ai model shape.

Provider setup. mini-coder detects providers with environment API keys, supports OAuth login with --login for OAuth-capable providers, and accepts --provider, --model, and --effort overrides.
Sessions. Conversations are saved as JSON files in ~/.config/mini-coder/sessions/ and listed only for the working directory they came from.
Instructions. mini-coder loads global ~/.agents/AGENTS.md and local ./AGENTS.md content when present.
Skills. Skill metadata is discovered from ~/.agents/skills/*/SKILL.md and ./.agents/skills/*/SKILL.md and added to the prompt.

Headless one-shot mode

For non-interactive use, pass a prompt with -p or --prompt. Headless mode uses the same core agent loop and tools, then writes completed user, assistant, and tool-result messages as JSON lines.

$ mc -p "summarize this repo"
$ mc --provider openai-codex --model gpt-5.5 --effort xhigh -p "fix the failing tests"

Built on proven parts

mini-coder uses pi-ai for provider support and streaming, and cel-tui for the terminal UI. The page is static HTML and intentionally stays close to the current main branch behavior.