NANOCODE ✦

A minimal, aesthetic terminal coding agent written in pure Python. Inspired by modern AI engineering practices (Claude Code, Cursor CLI), built step-by-step with clean, understandable primitives.

╭─────────────────────────────────────────────────────────────╮
│  ✦ NANOCODE (Terminal Coding Agent)              [14:30:00] │
│  Commands: /plan │ /compact │ exit                          │
╰─────────────────────────────────────────────────────────────╯

╭─ ✦ NANOCODE ────────────────────────────────────────────────╮
│ ❯ Create a Python CLI tool for checking weather             │
╰─────────────────────────────────────────────────────────────╯

---

✨ Features

• ⚡ Token-by-Token Streaming: Instant live streaming chunk-by-chunk with robust multi-chunk tool call accumulation.
• 🕒 Real-Time Status & Reasoning: Live timestamps ([HH:MM:SS]) and activity logs (✦ thinking..., ◈ running bash..., ✧ finished).
• 🛡️ Interactive Permission Gate: Prompts [y/n] before executing non-read-only commands (like bash), preventing unwanted system modifications.
• 🔒 Plan Mode (/plan or --plan): Locks out destructive tools and engages structured planning mode with checklist generation.
• 🧹 Safe Context Compaction: Automatically compresses long conversation histories into concise summaries while preventing orphaned tool call errors.
• 🤖 Sub-Agent Spawning (task): Launches focused sub-agents with fresh message context and recursion protection.
• 🔮 Rich Tool Arsenal:
  • read_file: Inspects files from local disk (read-only).
  • bash: Executes shell commands with human approval.
  • todo_write: Plans multi-step tasks with visual status checklists.
  • web_fetch: Scrapes and converts web pages to markdown via Firecrawl.
  • task: Recursively isolated sub-agent task executor.
• 🎨 Aesthetic Purple Terminal UI: TrueColor violet and lilac palette with rounded box prompts.

---

🚀 Quickstart

1. Clone the repository

git clone git@github.com:Reyo77/NANOCODE.git
cd NANOCODE

2. Create and activate a virtual environment

python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install dependencies

pip install openai

4. Configure Environment Variables

Copy the template and add your API keys:

cp .env.example .env

Edit .env:

OPENROUTER_API_KEY=your_openrouter_api_key_here
FIRECRAWL_API_KEY=your_firecrawl_api_key_here

Note: .env is included in .gitignore and will never be tracked or pushed to Git.

---

💻 Usage

Interactive REPL

python nanocode.py

Start Directly in Plan Mode

python nanocode.py --plan

One-Shot Prompt

python nanocode.py "Inspect this directory and plan out unit tests"

---

⌨️ In-Session Commands

Command	Action
/plan	Toggle between Plan Mode (read-only) and Execution Mode
/compact	Manually compress conversation history into a concise context summary
exit / quit	Exit NANOCODE

---

📜 Project Instructions (NANOCODE.md)

Create a NANOCODE.md file in any project root to provide custom project-specific rules, coding guidelines, or architectural context. NANOCODE automatically detects and injects it into its system prompt at startup.

---

📄 License

MIT License. Feel free to use, modify, and build upon NANOCODE!