Quick Start

min-agent is a minimal AI coding agent that lives in your terminal. There are two ways to get started:

Prerequisites

min-agent requires Node.js 20 or newer (npm comes bundled with it). Check whether it's already installed:

node -v    # should print v20.x or newer

If it's missing or too old, download the LTS build from the Node.js website, or install it with the nvm version manager:

# macOS / Linux (nvm must be installed first)
nvm install 20
nvm use 20

Option 1: Install globally (recommended)

npm install -g min-agent

Once installed, run min-agent from any directory. It ships with a free built-in model (OpenRouter openrouter/free) — no sign-up, no configuration needed.

min-agent             # Start chatting (a built-in model is ready)

Configure a model (min-agent setup)

The built-in openrouter/free model lets you get started right away, but its free quota is limited. For real work, run min-agent setup to configure your own AI provider and model:

min-agent setup       # Interactive wizard: pick provider, enter API key, choose model

You can also pass everything on the command line (handy for scripts):

min-agent setup --type ollama
min-agent setup --type openai-compatible --url https://api.example.com/v1 --api-key "$KEY" --name groq --default-model llama-3.1-70b
min-agent setup --switch ollama

• Works with OpenAI, Ollama, and any OpenAI-compatible provider
• Config is saved to ~/.min-agent/config.json; your own providers always take over the built-in preset
• In chat, use /provider and /model to switch anytime

Option 2: Run without installing (npx) — a temporary option

Temporary option

The npx route is great for a quick try or one-off tasks, but it is not recommended for regular use. For real work, install globally as in Option 1.

Don't want to install anything? Use npx to run it in one shot:

npx -y min-agent "your question or task"

-y auto-confirms the package download. The first run downloads the package, then executes. For example:

npx -y min-agent "write me a sort function"
npx -y min-agent "what files are in this directory?"

What's the difference?

• Option 1 (recommended): install once and get everything — session history, memory, the / command menu. The way to go for regular use.
• Option 2: only for a quick try — downloads again every time and lacks the full interactive experience. Run and forget.

Upgrading

npm update -g min-agent     # if installed globally
min-agent update            # or just run this command

Next steps

• Basic Usage — interactive sessions, one-shot questions, resuming sessions
• Configuration — adding your own AI provider