Complete Professional Manual

Agent Mint

Welcome to the definitive guide for Mint. This document covers everything from your first installation to advanced autonomous engineering workflows.

1. Installation

Option A: Global NPM (Recommended)

Install Mint globally to use the mint command anywhere in your terminal.

$npm install -g @pheem49/mint@latest

Option B: Manual Build (For Developers)

Perfect for contributing or testing the latest experimental branch.

$git clone https://github.com/Pheem49/Mint.git
$cd Mint
$npm install

2. Initial Setup (The Onboarding Wizard)

Configuring a powerful AI assistant can be complex, so Mint includes a built-in Onboarding Wizard to handle everything in one go. Run it by typing:

$mint onboard

Step 1: Core AI Activation (Gemini)

Mint is powered primarily by Google Gemini. You will be prompted for:

  • API Key: Paste your key from Google AI Studio. This key is stored locally and never shared.
  • Model Selection: Choose between flash (fast & cheap) or pro (highly intelligent). We recommend gemini-3.1-flash-lite-preview for daily tasks.

Step 2: QuickStart Provider Selection

This is where you choose which "plugins" or "channels" Mint should connect to. The menu uses an interactive checkbox system:

Keyboard Controls:
  • ↑ / ↓ : Navigate through the list.
  • Space : Toggle (Select/Deselect) an item. Selected items show a ◉.
  • a : Select all items.
  • i : Invert your current selection.
  • Enter : Confirm and move to configuration.

Step 3: Categorized Services

💬 Chat Bridges

Connect Mint to Telegram, Discord, WhatsApp, Slack, or LINE. This allows you to talk to your desktop agent from your phone!

🤖 Alternative AI

Enable support for Anthropic (Claude), OpenAI, or Hugging Face if you prefer their models for specific coding tasks.

🏠 Local AI

Privacy first. Connect to Ollama or LM Studio running on your machine to use Mint without sending data to the cloud.

🔎 Search Engines

Enable Google Search or Brave Search to give Mint real-time internet browsing capabilities for technical research.

Step 4: Dynamic Detail Entry

Based on your selections in Step 2, the wizard will now ask for the specific details needed for each service (e.g., Discord Bot Tokens, Search Engine IDs, or Local API URLs). Simply follow the prompts until you see the ✅ Configuration saved successfully! message.

3. Primary CLI Commands

Use these global commands to interact with Mint from your terminal:

mint / mint chat

Starts the unified interactive agent UI. This is your main gateway to talking with Mint.

mint code "<task>"

Executes a specific autonomous coding task in the current directory (Workspace Mode).

mint task "<task>"

Queues a long-running background task for the headless agent to perform autonomously.

mint mcp

Primary command for managing Model Context Protocol (MCP) servers and tools.

mint list

Displays an exhaustive list of all available features, tools, and terminal commands.

4. The Agent Workflow

Mint operates on a Plan-Act-Observe loop. It understands that complex tasks require a multi-step sequence of operations.

Thinking & Tool Selection

When given a task, Mint plans its moves, selects the appropriate tool (like web search or file editing), executes it, and then observes the results to decide the next action.

5. Coding Agent & Workspace

The specialized engineering mode (mint code) is optimized for technical integrity and idiomatic code standards.

Autonomous Safety

Before any destructive change (shell commands or file edits), Mint will prompt for your y/n approval, ensuring you remain in control of your machine.

6. Slash Commands In-Depth

In the interactive TUI, typing / opens the command menu. These allow you to control the agent's state directly.

/help (or /?) Displays a quick reference for all available slash commands and usage tips.
/code <task> Force-activates the autonomous engineering agent for complex coding tasks in your project.
/models [name] List all configured AI models or switch between them instantly (Gemini, Claude, GPT, Ollama).
/agent <type> Switch between specialized personas: chat, code, reviewer, or custom agents.
/workspace <cmd> Manage multi-project workflows: add, list, remove, or use to switch project contexts.
/cd <path> Changes the agent's working directory. Useful for moving between sub-modules of a project.
/stats Fetch real-time hardware telemetry: CPU load, available RAM, and operating system info.
/review Invokes the Reviewer Agent to analyze and critique the last response for technical accuracy.
/config Prints your current local configuration, active providers, and enabled chat bridges.
/copy Surgically copies the last AI response directly to your system clipboard (requires xclip/xsel on Linux).
/clear (or /reset) Wipes the current conversation history to refresh the AI's context and start a new session.
/exit (or /quit) Safely terminates the CLI session and returns to your primary shell.

7. Autonomous Toolset

  • web_search: Real-time internet access for up-to-date answers.
  • open_url: Launches any website or URL in your system's default browser.
  • open_app: Opens local applications (e.g., VS Code, Spotify, Slack) by name.
  • open_file / open_folder: Opens files or directories using your system's default apps (e.g., Nautilus, Finder, Explorer).
  • read_file / write_file: High-speed I/O operations with line range support.
  • apply_patch: Surgical, non-destructive code edits using exact matching.
  • run_shell: Executes terminal commands (Requires your y/n approval).
  • find_path: Advanced fuzzy search to locate files and folders by name.
  • system_automation: Controls hardware like Volume, Brightness, and Power.

8. Desktop GUI Features

Screen Vision

Let Mint "see" your screen to analyze errors, translate UI elements, or provide context-aware help based on your active windows.

Proactive Engine

Background monitoring that offers suggestions before you even ask, identifying task optimizations in real-time.

9. Advanced MCP (Extensions)

The Model Context Protocol (MCP) is the universal standard for connecting AI agents to data sources and tools. Mint acts as a host that can orchestrate multiple MCP servers simultaneously.

Adding a New Server

Use the following template to connect any MCP-compatible server to Mint:

# Template
mint mcp add <name> <command> --args <args...> --env <KEY=VALUE>

Common Extension Examples

Copy and run these commands in your terminal to extend Mint's capabilities:

🔍 Google Search

Allows Mint to perform deep web searches beyond its basic internal browser.

$mint mcp add google-search npx --args -y @modelcontextprotocol/server-google-search --env GOOGLE_API_KEY=YOUR_KEY GOOGLE_SEARCH_ENGINE_ID=YOUR_ID
📊 SQLite Database

Gives Mint the ability to query and analyze local SQLite databases.

$mint mcp add my-db npx --args -y @modelcontextprotocol/server-sqlite /path/to/your/database.db
☁️ Fetch Weather

Provides Mint with real-time weather data for any location.

$mint mcp add weather npx --args -y @modelcontextprotocol/server-everything

*The 'everything' server includes weather, time, and more.

📂 Git Repository Manager

Allows Mint to perform advanced Git operations like branching and merging across folders.

$mint mcp add git npx --args -y @modelcontextprotocol/server-git /path/to/repo
🛠️ Command Management
  • mint mcp list - View all connected servers and their tools.
  • mint mcp remove <name> - Disconnect a specific server.
  • mint mcp clear - Wipe all extensions and start fresh.