Agent Mini

A minimal, local-first AI agent you can actually understand and extend.

• ~3,000 lines of Python — read the whole thing in an afternoon
• Local-first — Ollama as default, OpenAI if you want cloud, or any OpenAI-compatible server
• Zero frameworks — pure httpx + asyncio, no LangChain, no LiteLLM
• Built-in tools — shell, files, web search, persistent memory
• Vision — drop an image path or URL into any message; works on Ollama, OpenAI, and OpenAI-compatible providers
• Extensible — drop a Python file in ~/.agent-mini/plugins/ and it's a tool
• Small-model optimized — tier-scaled system prompt, token-aware context pruning, tool-call repair, and a task-eval harness to measure whether the tuning actually pays off

Quick Start

pip install agent-mini
agent-mini init
agent-mini chat

The init wizard walks you through picking a provider, model, and basic settings. It creates ~/.agent-mini/config.json — you're ready to chat.

Providers

Agent Mini ships with three providers. Set "provider" in your config:

Ollama (default) — Local Models

ollama pull llama3.1

{
  "provider": "ollama",
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434",
      "model": "llama3.1",
      "think": false
    }
  }
}

think controls thinking mode — false, true, or "low" / "medium" / "high".

OpenAI

{
  "provider": "openai",
  "providers": {
    "openai": {
      "apiKey": "sk-...",
      "model": "gpt-4o"
    }
  }
}

Local — Any OpenAI-Compatible Server

Works with LM Studio, vLLM, llama.cpp, text-generation-webui, etc.

{
  "provider": "local",
  "providers": {
    "local": {
      "baseUrl": "http://localhost:8080/v1",
      "apiKey": "no-key",
      "model": "my-model"
    }
  }
}

All providers support streaming and tool calling.

Tools

Available out of the box — no API keys needed:

Plugins

Extend with custom tools — drop a .py file in ~/.agent-mini/plugins/:

# ~/.agent-mini/plugins/timestamp.py
from datetime import datetime, timezone

TOOL_DEF = {
    "type": "function",
    "function": {
        "name": "get_timestamp",
        "description": "Get the current UTC timestamp.",
        "parameters": {"type": "object", "properties": {}, "required": []},
    },
}

async def handler(arguments: dict) -> str:
    return datetime.now(timezone.utc).isoformat()

Chat Commands

/clear              Reset conversation
/model <name>       Switch provider/model (e.g. ollama/llama3.1)
/tools              List available tools
/memory [query]     Browse or search memories
/status             Show config and token usage
/save [file]        Export conversation as Markdown
/sessions           List saved sessions
/load <id>          Resume a session
/help               Show commands

Multi-line input: wrap with """ or '''. Line continuation: end with \.

Telegram Gateway

1. Create a bot via @BotFather
2. Run agent-mini init and enable Telegram during setup, or edit config:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allowFrom": ["YOUR_USER_ID"],
      "streamResponses": true
    }
  }
}

3. agent-mini gateway

Sandbox & Security

Control tool access:

{ "tools": { "sandboxLevel": "readonly" } }

Dangerous shell commands (rm -rf, sudo, mkfs, etc.) are blocked by default. Treat the shell blocklist as friction, not a boundary — a determined caller can bypass it, so don't run the agent in an untrusted context and expect the blocklist to save you.

web_fetch is guarded against basic SSRF: requests to localhost, loopback (::1), RFC-1918 private ranges, and link-local (including the cloud metadata endpoint 169.254.169.254) are refused, and the final URL is re-checked after every redirect. DNS rebinding can still bypass — use sandboxLevel: readonly if you need a stronger guarantee.

Sessions

Conversations auto-save after each turn. Resume:

agent-mini chat -s 20260307_143022

Or inside the REPL: /sessions to list, /load <id> to resume.

How It Works

Agent Mini is a ReAct loop — the LLM reasons, picks a tool, observes the result, and repeats until it has an answer.

Key design choices for small/local models:

• Tier-scaled system prompt — tiny models get a compact rules block and no memory recall; larger tiers get the full descriptive prompt and recent context
• Inline tool list — <available_tools> block in the system prompt so small models can see tool names at a glance without inferring from the JSON schema
• Token-aware context — estimates token usage and prunes old tool results when approaching the model's effective context window
• Model tier classification — auto-detects tiny/small/medium/cloud (including large open-weight sizes like :32b, :70b, 8x7b) and adjusts context budgets, iteration limits, and output caps
• Tool call repair — fixes malformed JSON from small models (trailing commas, single quotes, unquoted keys)
• Loop detection — catches repeated identical tool calls and nudges the LLM to try a different approach
• History summarization — compresses long conversations to stay within context
• Task-eval harness — measures success rate, iterations, tokens, and JSON-repair fire-rate across model tiers so the tuning above is testable, not hand-waved

Configuration Reference

{
  "provider": "ollama",
  "providers": {
    "ollama": { "baseUrl": "http://localhost:11434", "model": "llama3.1", "think": false },
    "openai": { "apiKey": "", "model": "gpt-4o" },
    "local":  { "baseUrl": "http://localhost:8080/v1", "apiKey": "no-key", "model": "local-model" }
  },
  "agent": {
    "maxIterations": 20,
    "temperature": 0.7,
    "systemPrompt": ""
  },
  "channels": {
    "telegram": { "enabled": false, "token": "", "allowFrom": [], "streamResponses": true }
  },
  "tools": { "restrictToWorkspace": false, "sandboxLevel": "workspace", "blockedCommands": [] },
  "memory": { "enabled": true, "maxEntries": 1000 },
  "workspace": "~/.agent-mini/workspace"
}

Key paths:

• Config: ~/.agent-mini/config.json
• Workspace: ~/.agent-mini/workspace/
• Memory: ~/.agent-mini/memory.json
• Plugins: ~/.agent-mini/plugins/
• Sessions: ~/.agent-mini/sessions/

CLI

Project Structure

src/agent_mini/
├── cli.py                  # CLI commands (Click)
├── config.py               # Typed config
├── bus.py                  # Message routing
├── sessions.py             # Session persistence
├── agent/
│   ├── loop.py             # ReAct agent loop
│   ├── context.py          # System prompt builder
│   ├── memory.py           # JSON memory + TF-IDF search
│   ├── tools.py            # Built-in tools + plugin loader
│   ├── token_estimator.py  # Token counting + model tiers
│   └── vision.py           # Image detection + encoding
├── providers/
│   ├── base.py             # Provider interface
│   ├── ollama.py           # Ollama
│   ├── openai.py           # OpenAI
│   └── local.py            # OpenAI-compatible
└── channels/
    ├── base.py             # Channel interface
    └── telegram.py         # Telegram bot

Development

git clone https://github.com/mohsinkaleem/agent-mini.git
cd agent-mini
uv sync --extra dev
uv run pytest tests/ -v
uv run ruff check src/ tests/

Task evals

The evals/ directory contains a small, framework-free task-eval harness that runs the agent end-to-end against real fixtures (refactor a codebase, fix a failing test, answer a codebase question, etc.). Use it to measure whether the small-model optimizations actually pay off:

python evals/run.py                        # run all tasks against config model
python evals/run.py --task refactor_rename # single task
python evals/run.py --compare results/*.json  # cross-tier comparison table

See evals/README.md for the full workflow.

See CONTRIBUTING.md for guidelines.

License

MIT