nanoagent

中文 | English

Native minimalist Claude Code alternative. ~700 lines of Python, near-zero dependencies.

Features

• Full agentic loop with tool use
• Tools: read, write, edit, glob, grep, bash, websearch
• Ralph Loop: Automated task execution system
• Colored terminal output

Model Compatibility

Tested with MiniMax M2: Tool calling success rate 100% ✅

We welcome testing with:

• OpenAI (GPT-4, GPT-4-turbo, GPT-3.5-turbo)
• Anthropic (Claude 3.5 Sonnet, Claude 3 Opus)
• Google (Gemini Pro, Gemini 1.5 Pro)

All models are accessed via OpenRouter API for unified integration.

Quick Start

Installation

Method 1: Install from PyPI (Recommended)

# Using pipx (isolated environment, recommended)
pipx install nanoagent-cli

# Using uv (fastest)
uv tool install nanoagent-cli

# Using pip
pip install nanoagent-cli

Method 2: Install from Source

# Clone repository
git clone https://github.com/not-yes/nanoagent.git
cd nanoagent

# Install dependencies
pip install python-dotenv

# Install as global command (editable mode)
pip install -e .

Configuration

# Create .env file
MODEL=anthropic/claude-sonnet-4-20250514
OPENROUTER_API_KEY=your-key

Usage

# Interactive mode
nanoagent

# Ralph Loop mode
nanoagent /r "Build a calculator"

Usage Modes

1. Direct Chat Mode

Ask questions or give instructions directly, AI executes immediately.

❯ Analyze performance bottlenecks in app.py
❯ Modify database config in config.json
❯ Search Python best practices on DuckDuckGo

Features:

• ✅ Instant response
• ✅ Suitable for simple tasks (single file edits, code analysis, searches)
• ⚠️ Not ideal for multi-step complex projects

2. Ralph Loop Mode /r

Long tasks auto-decomposition + interactive review + step-by-step execution.

❯ /r Build a blog project

# Process:
# 1. AI generates TODO.md (staged task list)
# 2. Shows plan overview (6 stages, 30 tasks)
# 3. Interactive options:
#    [y] Start execution
#    [v] View full plan
#    [e] Edit plan in editor
#    [n] Cancel
# 4. Auto-execute after confirmation
# 5. Auto-archive to archives/ when done

Features:

• ✅ Auto-decompose complex tasks
• ✅ Preview full plan
• ✅ Edit tasks in your editor
• ✅ Suitable for all long-term projects

Quick Tips:

• Simple tasks: Press y to execute (2s confirmation)
• Complex projects: Press v to view or e to edit

Mode Selection Guide

Command Reference

Tools

bash Safety Restrictions

To prevent accidental damage, bash tool blocks dangerous commands:

• rm -rf - Recursive delete
• mkfs - Format filesystem
• dd if= - Disk-level operations
• > /dev - Write to device files
• curl/wget | sh - Remote script execution

Whitelist Exceptions (auto-allowed safe operations):

• rm -rf node_modules / dist / build / .next / out - Build artifacts
• rm -rf __pycache__ / .pytest_cache / .coverage - Python cache
• rm -rf temp / tmp / *.log / .DS_Store - Temp files
• rm -rf .git/index.lock - Git lock files

Safety Policy:

• Interactive mode: Prompts user confirmation on dangerous commands
• Ralph mode: Auto-blocks dangerous commands (prevents unattended damage)
• Force allow: Set ALLOW_DANGEROUS_BASH=1 to bypass checks

Note: This is basic protection. Use bash tool with caution.

Design Philosophy

"Less is more"

Core Insights

1. Agentic Loop Essence: while tool_results: call_api()
2. Task Scheduling Essence: while "[ ]" in progress: run_once()
3. Tool System Essence: {name: (desc, schema, fn)}

Architecture

nanocode.py      (324 lines) - Core execution engine, single-round agentic loop
ralph_runner.py  (176 lines) - Outer task scheduler, multi-round iteration control
spinner.py       (34 lines)  - Terminal animation
websearch.py     (107 lines) - Search tool
────────────────────────────
Total: 641 lines

Key Decisions

• Zero framework dependencies: No LangChain, AutoGPT, just stdlib + dotenv
• Separation of concerns: nanocode = executor, ralph_runner = scheduler
• Defensive design: File protection, SSL retry, timeout control
• Auto schema generation: Derive JSON Schema from tool definitions

Inspired By

Core design philosophy inspired by nanocode:

• Minimalist philosophy: Single-file Python script, no complex dependencies
• Ralph task-driven mode: Staged execution, automatic verification per step
• Terminal-first experience: Focus on CLI interaction, rapid iteration

License

Apache License 2.0

When using this project code (including commercial use), you must:

• Retain copyright notice and NOTICE file
• Attribute source: https://github.com/not-yes/nanoagent
• Declare modifications when changing code

See LICENSE and NOTICE files for details.