nanoagent-cli 0.1.1

Minimal AI Coding Agent - A lightweight alternative to Claude Code

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

Task Type	Recommended Mode	Example
Single file edit	Direct chat	"Change port to 8080 in app.py"
Code analysis	Direct chat	"Analyze performance issues"
Information search	Direct chat	"Search Flask deployment best practices"
Small project	/r	"Build a calculator"
Medium project	/r	"Build a blog system"
Large project	/r	"Build an e-commerce platform"
Architecture refactor	/r	"Refactor entire project architecture"

---

Command Reference

Command	Description
Direct input	Chat mode, instant response
/r <task>	Ralph Loop mode (auto-review)
/c	Clear chat history
/q	Quit

Tools

Tool	Description
read	Read file with line numbers
write	Write content to file
edit	Replace string in file
glob	Find files by pattern
grep	Search files for regex
bash	Run shell command (with safety blacklist)
websearch	Web search via DuckDuckGo

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.