Docs

Install

From source (recommended for development). nanoiqqi requires Python ≥ 3.11.

git clone https://github.com/iqqipro/nanoiqqi.git
cd nanoiqqi
pip install -e .

With uv: uv tool install nanoiqqi

Quick Start

Config path: ~/.nanoiqqi/config.json. You can reuse Claude Desktop / Cursor MCP config snippets.

nanoiqqi onboard

{
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-..."
    }
  },
  "agents": {
    "defaults": {
      "model": "anthropic/claude-3.7-sonnet"
    }
  }
}

nanoiqqi agent

What nanoiqqi provides

• –Workspace-driven behavior: AGENTS.md and TOOLS.md define agent and tool instructions.
• –Smart router: scores models by quality, cost, latency, reliability; supports main agent and subagents.
• –Subagents: spawn tool offloads complex tasks to background workers.
• –Brain Office UI: real-time view of tools, turns, and subagent lifecycle.
• –LeadsMx: native skill for Mexico DENUE/INEGI with Spanish-language guardrails.

Architecture

Core engine: nanoiqqi/agent/loop.py. Input → ContextBuilder → LLM (SmartRouter) → ToolRegistry → SubagentManager → Output.

Subagents

The spawn tool lets the main agent say: “Handle this in the background and summarize later.” Each subagent gets a focused system prompt, isolated history, and shared tools (no message/spawn inside subagents). When done, a system message returns task + result + instructions for the main agent to summarize to the user.

Built-in tools

Defined in workspace TOOLS.md. File (read_file, write_file, edit_file, list_dir), shell (exec), web (web_search, web_fetch), image (generate_image), session (message, new_session, dump_session), cron, spawn. LeadsMx for Mexico DENUE/INEGI (buscar, ficha, nombre, etc.). All filesystem tools support restrictToWorkspace.

"tools": {
  "leads_mx": {
    "token": "INEGI_DENUE_TOKEN"
  }
}

Skills

Under nanoiqqi/skills/, OpenClaw-style SKILL.md (YAML front-matter + markdown). Included: leads_mx, leads_mx_localidades, leads_mx_municipios, github, weather, summarize, tmux, clawhub, skill-creator, memory, cron. Loaded dynamically; iterate without restarting.

MCP (Model Context Protocol)

Add servers under tools.mcpServers. Stdio (command + args) or HTTP (url + headers). MCP tools are only available to the main agent, not subagents.

"tools": {
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    }
  }
}

Channels

Run nanoiqqi gateway to connect chat backends. Each channel supports allowFrom allowlist. See Chat providers for the full list.

Brain Office / IQQI Office

Backend: FastAPI (/events, /ws). Frontend: React + Vite + TypeScript. Agent sends tool_start, tool_end, waiting_input, turn_end, subagent_start, subagent_end. Override URL in config:

"brainOffice": {
  "url": "http://localhost:8765"
}

Configuration overview

~/.nanoiqqi/config.json: providers, agents.defaults (model, temperature, always_skills), channels, tools (restrictToWorkspace, leads_mx, mcpServers), brainOffice.url.

CLI reference

Exit interactive mode: exit, quit, /exit, /quit, :q, or Ctrl+D.

Docker

Mount ~/.nanoiqqi for config persistence.

docker build -t nanoiqqi .
docker run -v ~/.nanoiqqi:/root/.nanoiqqi --rm nanoiqqi onboard
# Edit ~/.nanoiqqi/config.json, then:
docker run -v ~/.nanoiqqi:/root/.nanoiqqi -p 18790:18790 nanoiqqi gateway
docker run -v ~/.nanoiqqi:/root/.nanoiqqi --rm nanoiqqi agent -m "Hello from Docker"