nanoagent-cli 0.1.12
Minimal AI Coding Agent - A lightweight alternative to Claude Code
Requires Python: >=3.9
Keywords: ai, coding-assistant, claude, agent, cli

# nanoagent

[中文](README_CN.md) | 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)**

```bash
# 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**

```bash
# 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

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

### Usage

```bash
# 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.

```bash
❯ 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.

```bash
❯ /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](https://github.com/Shaxpy/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](LICENSE) and [NOTICE](NOTICE) files for details.