🤖 Nanocoder

A minimal, multi-provider coding agent with a beautiful Textual TUI. Supports Google Gemini, OpenAI, and Anthropic Claude via provider-native APIs.

✨ Features

• Multi-Provider Support: Switch between Gemini, OpenAI, and Anthropic with a single environment variable
• Unified Agent Loop: Same UX across all providers
• Streaming Responses: Real-time text and thought/reasoning display
• Parallel Tool Execution: Concurrent file operations and commands
• Trajectory Logging: JSONL traces for debugging, reproducibility, and training data
• Beautiful TUI: Modern terminal interface with Textual

🧭 Overview

Nanocoder pairs a Textual front-end with a provider-agnostic agent core so the UX stays identical whether you call Gemini, OpenAI, or Anthropic. The codebase is intentionally compact and organized around a few focused modules:

• CLI + TUI (nanocoder/cli.py, nanocoder/app_tui.py) – boots the Textual application, renders streaming text/thought panes, and wires up keyboard shortcuts plus chat commands like /trace.
• Agent core (nanocoder/agent/core.py) – streams LLMSession events, manages multi-iteration tool calling, and records trajectories for every turn.
• Tooling layer (nanocoder/agent/tools.py, nanocoder/agent/exec.py) – exposes filesystem/shell helpers with JSON Schema contracts and executes them in parallel with callback hooks for the UI.
• LLM adapters (nanocoder/llm/*.py) – wrap provider-native SDKs while converting their streaming outputs into the unified event model.
• Tracing (nanocoder/tracing/*) – produces JSONL traces in .nanocoder_traces/ for debugging and reproducibility.

🚀 Quick Start

Installation

# Using uv (recommended)
uv tool install nanocoder

# Or clone and install
git clone https://github.com/yuxiang-wu/nanocoder
cd nanocoder
uv sync

Setup API Key

# For Gemini (default)
export GEMINI_API_KEY="your-key"

# Or for OpenAI
export OPENAI_API_KEY="your-key"
export NANOCODER_PROVIDER="openai"

# Or for Anthropic
export ANTHROPIC_API_KEY="your-key"
export NANOCODER_PROVIDER="anthropic"

Run

nanocoder

Repo at a Glance

🛠️ Available Tools

⚙️ Configuration

All configuration is via environment variables:

Provider-Specific Keys

Default Models

All providers show their internal reasoning/thinking in the UI's thought panel.

⌨️ Keyboard Shortcuts

💬 Commands

📊 Trajectory Logging

Every session creates a JSONL trace file for debugging and reproducibility:

.nanocoder_traces/20251227_143022_a1b2c3d4_gemini.jsonl

Trace Contents

Each trace includes:

• Machine metadata: hostname, platform, Python version, Nanocoder version
• Model responses: full text, reasoning/thinking, start/end timestamps, token usage
• Tool calls: arguments and results
• Timing: sufficient for replay without streaming

Trace events: run.start, run.end, turn.start, turn.end, model.request, model.response, tool.start, tool.end, error

🏗️ Architecture

nanocoder/
├── __init__.py     # Package init + version
├── cli.py          # Entry point
├── app_tui.py      # Textual TUI
├── agent/
│   ├── core.py     # Provider-agnostic agent loop
│   ├── tools.py    # Tool definitions + registry
│   └── exec.py     # Parallel tool execution
├── llm/
│   ├── base.py     # Event types & LLMSession protocol
│   ├── gemini.py   # Gemini adapter (google.genai)
│   ├── openai.py   # OpenAI adapter (Responses API)
│   └── anthropic.py # Anthropic adapter (Messages API)
└── tracing/
    ├── logger.py   # TrajectoryLogger + JSONL output
    └── schema.py   # Trace event dataclasses

Design Principles

1. Unify on events, not messages: Provider adapters maintain native conversation state
2. Provider correctness first: No cross-provider message normalization
3. Trace everything: Consistent event schema for debugging, reproducibility, and training
4. Minimal surface area: Thin adapters, provider-agnostic core loop

📝 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

Built with:

• google-genai - Gemini API
• openai - OpenAI API
• anthropic - Anthropic API
• exa_py - Exa web search API
• Textual - Terminal UI framework
• Rich - Rich text formatting