min-agent

Minimal AI coding agent for the terminal. Works with any OpenAI-compatible API.

Install

npm install -g min-agent

Quick Start

min-agent setup              # Configure provider
min-agent chat "hello"       # Single message
min-agent chat               # Interactive session
min-agent code               # Project-aware coding mode

Commands

min-agent chat [message]          # Chat (interactive if no message)
min-agent chat -m <model> "msg"   # Override model
min-agent chat -i img.png "msg"   # Attach image
min-agent chat --resume <id>      # Resume session
min-agent code                    # AI coding mode (project scan)
min-agent setup                   # Configure API provider
min-agent models                  # List available models
min-agent history                 # List saved sessions
min-agent rules                   # Show loaded rules
min-agent rules edit              # Edit global rules
min-agent memory                  # List memories
min-agent memory add "text"       # Save memory
min-agent mcp -h                  # MCP server management
min-agent skills -h               # Skills management
min-agent serve                   # Start HTTP API server

Interactive Commands

| Command | Description | |---------|-------------| | /clear | Clear history | | /compact | Force compaction | | /model [name] | Show/change model | | /memory [text] | List/save memory | | /tokens | Context usage | | /paste [text] | Clipboard image | | /path | Working directory | | /help | All commands | | /exit | Exit |

Ctrl+C interrupts current generation.

Configuration

All config in ~/.min-agent/:

// ~/.min-agent/config.json
{
  "provider": {
    "type": "openai-compatible",
    "baseURL": "https://api.openai.com/v1",
    "apiKey": "sk-...",
    "defaultModel": "gpt-5.5",
    "contextWindow": 128000
  },
  "instructions": ["./docs/rules.md"],
  "disabledSkills": []
}

Provider types: openai-compatible | openai | ollama

MCP

min-agent mcp add <name> <cmd...>              # Local stdio
min-agent mcp add <name> --url <url> --token T # Remote HTTP
min-agent mcp list                             # List (name + status)
min-agent mcp info <name>                      # Details
min-agent mcp enable/disable <name...>         # Toggle
min-agent mcp remove <name>                    # Remove
min-agent mcp check                            # Test connectivity

Skills

min-agent skills list                          # List (name + status)
min-agent skills info <name>                   # Details
min-agent skills enable/disable <name...>      # Toggle

Create: .min-agent/skills/<name>/SKILL.md or ~/.agents/skills/<name>/SKILL.md

---
name: my-skill
description: What it does
---
# Instructions...

Rules

| Source | Scope | |--------|-------| | ~/.min-agent/rules.md | Global | | ./AGENTS.md or ./RULES.md | Project | | config.instructions[] | Custom paths/URLs |

Plugins

Custom tools: .min-agent/tools/*.ts or ~/.min-agent/tools/*.ts

export const myTool = {
  description: "...",
  parameters: { arg: { type: "string", description: "..." } },
  execute: async ({ arg }) => "result"
}

HTTP API

min-agent serve [--port 8787]

Full reference: docs/API.md

Environment Variables

| Variable | Description | |----------|-------------| | EXA_API_KEY | Enable Exa code search | | MIN_AGENT_SHOW_THINKING | 0 to hide thinking | | MIN_AGENT_SERVE_TOKEN | API auth token | | MIN_AGENT_SERVE_CORS | 1 to enable CORS |

License

MIT