A micro coding agent that auto-routes between Claude Code, Codex, and OpenCode styles. 193 lines of core logic, dual-backend support (OpenAI + Anthropic), and Greek mythology-themed loading animations.

• Auto-routing Agent: LLM automatically selects the best agent (Claude/Codex/OpenCode) for your task
• Manual Agent Switching: Use /agent claude|codex|opencode|auto to switch on the fly
• Dual Backend Support: Works with OpenAI-compatible APIs and Anthropic natively
• Minimal Core: Only 193 lines of core scheduling logic (engine + router)
• Full TUI: Textual-based terminal UI with real-time streaming, tool output, and status bar
• Greek Mythology Loading: "Consulting the Oracle at Delphi...", "Weaving code with Athena..." 🏛️
• 100% Test Coverage: 95 tests, TDD-driven development

• Python 3.11+
• OpenAI API key OR Anthropic API key

git clone https://github.com/yourusername/nanocode.git
cd nanocode
pip install -e .

# Using OpenAI-compatible API (default)
export OPENAI_API_KEY=sk-...
export OPENAI_BASE_URL=https://api.openai.com/v1  # optional
nanocode

# Using Anthropic
export ANTHROPIC_API_KEY=sk-ant-...
nanocode --provider anthropic

# Using local LLM (e.g., Ollama)
export OPENAI_API_KEY=dummy
export OPENAI_BASE_URL=http://localhost:8000/v1
nanocode

> /agent auto
Mode: auto (active: none). Available: auto, claude, codex, opencode

> write a python function to calculate fibonacci
⚡ Claude Code ⚡auto
Consulting the Oracle at Delphi...
[AI generates code with careful explanation]

> now optimize it for performance
⚡ Codex ⚡auto
Hermes is delivering...
[AI generates optimized shell commands and code]

> refactor this across multiple files
⚡ OpenCode ⚡auto
Athena reviews the strategy...
[AI performs complex multi-file refactoring]

engine.py (123 lines)
  ├─ Event types (TextEvent, ToolCallEvent, ToolResultEvent, StatusEvent)
  ├─ LLMBackend protocol
  ├─ Engine class (agent loop, tool execution, message history)
  └─ create_backend() factory

router.py (70 lines)
  ├─ Router class (manual + auto routing)
  ├─ /agent command handler
  └─ LLM-based agent classification

backends.py (120 lines)
  ├─ OpenAIBackend (streaming, tool call buffering)
  └─ AnthropicBackend (message format conversion)

agents/ (136 lines)
  ├─ base.py: AgentConfig + SystemPromptBuilder
  ├─ claude.py: Claude Code configuration
  ├─ codex.py: Codex configuration
  └─ opencode.py: OpenCode configuration

tools/ (225 lines)
  ├─ Tool ABC + ToolResult
  ├─ 6 tools: shell, read, write, edit, glob, grep
  └─ TOOL_REGISTRY

ui/ (438 lines)
  ├─ app.py: Textual TUI main app
  ├─ chat_view.py: Message list + input
  ├─ loading.py: Greek mythology animations
  ├─ status_bar.py: Agent status display
  └─ terminal_view.py: Tool output panel

Total: 905 lines (including tests: 1,043 lines)

• Approval Policy: Prompt (asks before write/shell operations)
• Tools: All 6 (shell, read, write, edit, glob, grep)
• Style: Careful, multi-step reasoning; reads before editing
• Best For: Code review, debugging, complex refactoring

• Approval Policy: Auto (executes without asking)
• Tools: Shell only
• Style: Direct, quick; one command at a time
• Best For: Quick code generation, build/test/deploy tasks

• Approval Policy: None (fully autonomous)
• Tools: All 6 (shell, read, write, edit, glob, grep)
• Style: Thorough, systematic; explores before changing
• Best For: Complex multi-file refactoring, project scaffolding

NanoCode's auto-routing system intelligently selects the best agent for your task using a lightweight LLM classification call. This is inspired by Cursor's auto mode but adapted for multi-agent routing.

When you enable /agent auto, NanoCode performs a two-stage routing:

Stage 1: Request Classification (happens once per request)

User Input: "write a python function to calculate fibonacci"
    ↓
Router sends to LLM:
  System: "Classify this coding request into exactly one agent name.
           - 'claude': explanation, debugging, code review, careful multi-step reasoning
           - 'codex': direct code generation, quick shell commands, build/test/deploy
           - 'opencode': complex refactoring, multi-file changes, project scaffolding
           Reply with ONLY the agent name, nothing else."
  User: "write a python function to calculate fibonacci"
    ↓
LLM Response: "codex"
    ↓
Router: "This is direct code generation → switching to Codex"

Stage 2: Agent Execution (uses selected agent's config)

Engine: Switches to Codex config
  ├─ System Prompt: "You are Codex, a coding assistant..."
  ├─ Tools: shell only (fast, direct)
  ├─ Approval Policy: auto (no prompts)
  └─ Style: Quick, one command at a time
    ↓
AI: Generates code directly without asking for approval

> /agent auto
Mode: auto (active: none). Available: auto, claude, codex, opencode

> write a fibonacci function
⚡ Codex ⚡auto
Hermes is delivering...
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

> now explain how it works
⚡ Claude Code ⚡auto
Consulting the Oracle at Delphi...
This recursive function calculates Fibonacci numbers by...
[detailed explanation with examples]

> optimize it for large n values
⚡ OpenCode ⚡auto
Athena reviews the strategy...
[performs multi-file refactoring with memoization]

The router uses this exact prompt for classification:

Classify this coding request into exactly one agent name.
- "claude": explanation, debugging, code review, careful multi-step reasoning
- "codex": direct code generation, quick shell commands, build/test/deploy
- "opencode": complex refactoring, multi-file changes, project scaffolding
Reply with ONLY the agent name, nothing else.

This prompt is:

• Concise: Forces LLM to make a quick decision
• Explicit: Clear boundaries between agent responsibilities
• Deterministic: Expects single-word response (easy to parse)

✅ Good Use Cases

• Mixed coding tasks (explanation → generation → optimization)
• Exploratory sessions where you don't know which agent you need
• Rapid prototyping with varied requests
• Learning which agent works best for your workflow

❌ When to Use Manual Mode

• You know exactly which agent you need
• You want consistent behavior across requests
• You're optimizing for latency (skip the classification call)
• You're testing a specific agent's capabilities

/agent auto          # Enable auto-routing (classify each request)
/agent claude        # Lock to Claude Code (no classification)
/agent codex         # Lock to Codex (no classification)
/agent opencode      # Lock to OpenCode (no classification)
/agent               # Show current mode and available agents

The router implementation (70 lines in router.py):

1. Receives user input from the chat interface
2. Checks current mode:
   • If auto: calls _classify() to determine agent
   • If locked: uses the locked agent
3. Compares with current agent:
   • If same: reuses existing config (no reconfiguration)
   • If different: creates new agent config and reconfigures engine
4. Returns agent config to engine for execution

This design ensures:

• Efficiency: No redundant reconfigurations
• Responsiveness: Classification happens in parallel with UI updates
• Reliability: Fallback to "claude" on classification errors

# Run all tests
pytest tests/ -v

# Run specific test suite
pytest tests/test_engine.py -v
pytest tests/test_tools.py -v
pytest tests/test_agents.py -v
pytest tests/test_router.py -v
pytest tests/test_ui.py -v

# Coverage
pytest tests/ --cov=src/nanocode

95 tests, 100% passing — TDD-driven development ensures reliability.

nanocode/
├── pyproject.toml          # Build config
├── README.md               # This file
├── src/nanocode/           # Source code
│   ├── __main__.py         # Entry point
│   ├── engine.py           # ★ Core agent loop
│   ├── router.py           # ★ Auto-routing
│   ├── backends.py         # LLM backends
│   ├── agents/             # Agent configs
│   ├── tools/              # Tool implementations
│   └── ui/                 # Textual TUI
└── tests/                  # Test suite (95 tests)

1. Create a class inheriting from Tool in tools/__init__.py
2. Implement name, description, parameters, execute()
3. Register in TOOL_REGISTRY
4. Add tests in tests/test_tools.py

Example:

class MyTool(Tool):
    name = "my_tool"
    description = "Does something useful"
    parameters = {"type": "object", "properties": {...}}
    is_read_only = False

    def execute(self, **kwargs) -> ToolResult:
        # Implementation
        return ToolResult("success")

TOOL_REGISTRY["my_tool"] = MyTool()

1. Create a class inheriting from AgentConfig in agents/
2. Set name, display_name, color, approval_policy, tool_names, identity_prompt, constraints
3. Register in AGENT_REGISTRY via @register_agent decorator
4. Add tests in tests/test_agents.py

• Real-time Streaming: See AI responses character-by-character
• Tool Visualization: Tool calls and results displayed in terminal panel
• Agent Status Bar: Shows current agent name, color, and routing mode
• Greek Mythology Loading: 12 thinking phrases + 6 tool phrases
• Syntax Highlighting: Code blocks highlighted by language
• Message History: Scrollable chat with user/AI/system messages

Implement the LLMBackend protocol:

class MyBackend:
    def stream(self, system: str, messages: list, tools: list[Tool]) -> AsyncIterator[Event]:
        # Yield TextEvent, ToolCallEvent, etc.
        ...

Register in create_backend() factory.

Subclass AgentConfig and register:

@register_agent("my_agent")
class MyAgent(AgentConfig):
    name = "my_agent"
    # ... configuration

• Startup: < 1s
• First LLM Call: Depends on backend (typically 1-3s)
• Streaming: Real-time token-by-token display
• Memory: ~50MB baseline (grows with conversation history)

• Ensure you're running nanocode from the command line, not in a Jupyter notebook
• Use conda activate nano && nanocode if using conda

• Check that the tool is registered in TOOL_REGISTRY
• Verify the agent config includes the tool in tool_names

• Verify OPENAI_API_KEY or ANTHROPIC_API_KEY is set
• Check OPENAI_BASE_URL or ANTHROPIC_BASE_URL if using custom endpoints
• Test connectivity: curl http://localhost:8000/v1/models (for local LLM)

MIT License — see LICENSE file for details.

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Write tests for new functionality (TDD)
4. Ensure all tests pass (pytest tests/)
5. Submit a pull request

• Inspired by Claude Code, Codex, and OpenCode
• Built with Textual for TUI
• Powered by OpenAI and Anthropic

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [email protected]

Made with ❤️ and 193 lines of core logic