Nano Agent

Watched how we used GPT-5 and Claude Code with nano-agents here.

What? A MCP Server for experimental, small scale engineering agents with multi-provider LLM support.

Why? To test and compare Agentic Capabilities of Cloud and Local LLMs across Performance, Speed, and Cost.

"It's not about a single prompt call anymore. It's about how well your agent chains together multiple tools to accomplish real engineering results on your behalf." - From our evaluation

<img src="images/nano-agent.png" alt="Nano Agent" style="max-width: 800px;">

🎬 See It In Action

Multi-Model Evaluation Flow - Watch 9 models (GPT-5, Claude Opus, Local GPT-OSS) running in parallel on the same M4 Max: <img src="images/multi-model-eval-flow.gif" alt="Multi-Model Evaluation Flow" style="max-width: 800px;">

Model Comparison: GPT-5 vs Local Models - Surprising results: GPT-OSS 20B/120B running on-device with $0.00 cost: <img src="images/model-comparison-gpt5-oss.gif" alt="Model Comparison GPT-5 vs OSS" style="max-width: 800px;">

🔥 Key Findings from Our Testing

• Surprising Winners: GPT-5 Nano/Mini often outperform larger models when factoring in speed and cost
• Local Revolution: GPT-OSS 20B/120B models complete real agentic coding tasks on M4 Max (128GB RAM)
• Cost Reality Check: Claude Opus 4.1 is extraordinarily expensive - performance isn't everything
• The Trade-off Triangle: Performance vs Speed vs Cost - you don't always need the most expensive model

Installation

Quick Install (Recommended)

• Install Astral UV
• Setup Claude Code
• Setup Ollama
• Get your OpenAI API key and Anthropic API key
• Setup dotenv
  • cp ./.env.sample ./.env and fill out variables
  • cp ./apps/nano_agent_mcp_server/.env.sample ./apps/nano_agent_mcp_server/.env and fill out variables
• Clone the repository
  • git clone https://github.com/disler/nano-agent
• Global Install nano-agent to expose it for Claude Code (any mcp client)
  • cd nano-agent/apps/nano_agent_mcp_server
  • ./scripts/install.sh
  • uv tool install -e .
• cp .mcp.json.sample to .mcp.json to use nano-agent
• You should end up with a .mcp.json file that looks like this:

{
  "mcpServers": {
    "nano-agent": {
      "command": "nano-agent",
      "args": []
    }
  }
}

• You can also test without installing nano-agent globally by running it this directory with

{
  "mcpServers": {
    "nano-agent": {
      "command": "uv",
      "args": ["--directory", "apps/nano_agent_mcp_server", "run", "nano-agent"]
    }
  }
}

Now you can follow the Nano Agent Interaction section below to test out the nano agent.

Nano Agent Interaction

There are three ways to interact with the nano agent.

1. Nano Agent Through the CLI (uv run nano-cli run)
   • Great for understanding agent capabilities
2. Nano Agent Through Claude Code or any MCP client (.mcp.json or equivalent configuration)
   • Great for delegating work and scaling up compute in the field
3. Nano Agent Through the Higher Order Prompt (HOP) and Lower Order Prompt (LOP) pattern to test and compare models across providers and models.

Through the CLI

Remember, when running directly your current directory is where ever you run uv run nano-cli run from.

cd apps/nano_agent_mcp_server

# Test tools without API
uv run nano-cli test-tools

# Run with different models (provider auto-detected from model name)
uv run nano-cli run "List all Python files in the current directory"  # gpt-5-mini (default)
uv run nano-cli run "Create a hello world script in python" --model gpt-5-nano
uv run nano-cli run "Summarize the README.md" --model gpt-5

# Test Anthropic models (requires ANTHROPIC_API_KEY)
uv run nano-cli run "Hello" --model claude-3-haiku-20240307 --provider anthropic
uv run nano-cli run "Hello" --model claude-sonnet-4-20250514 --provider anthropic
uv run nano-cli run "Hello" --model claude-opus-4-20250514 --provider anthropic
uv run nano-cli run "Hello" --model claude-opus-4-1-20250805 --provider anthropic

# Test local Ollama models (requires ollama service) (be sure to install the model first with `ollama pull gpt-oss:20b`)
uv run nano-cli run "List files" --model gpt-oss:20b --provider ollama
uv run nano-cli run "List files and count the total number of files and directories" --model gpt-oss:120b --provider ollama

# Verbose mode (shows token usage)
uv run nano-cli run "Create and edit a test file" --verbose

Through Claude Code

Call the MCP server directly

mcp nano-agent: prompt_nano_agent "Create a hello world script in python" --model gpt-5
mcp nano-agent: prompt_nano_agent "Summarize the README.md" --model claude-opus-4-1-20250805 --provider anthropic
mcp nano-agent: prompt