NimbusZero

An open-source AI coding agent framework. Modular, async-first, multi-provider.

Features

• Multi-LLM support — Anthropic, OpenAI-compatible, OpenRouter, Ollama (local)
• Rich tool set — file operations, search, shell execution, web access
• Sub-agent system — spawn specialized agents for complex tasks
• Agent Teams — multiple persistent agents collaborating via messages and shared tasks
• Context management — automatic compaction, persistent memory, session continuity
• Extensible — custom tools (TOML), custom agents (AGENT.md), custom skills (SKILL.md)
• Two interfaces — CLI (Rich terminal) and Web UI (FastAPI + WebSocket)

Quick Start

Install

pip install -e .

Configure

Create ~/.nimbus-zero/config.yaml:

llm:
  default_provider: anthropic
  default_model: claude-sonnet-4-6
  providers:
    anthropic:
      api_key: ${ANTHROPIC_API_KEY}

Or just set the environment variable — NimbusZero will auto-detect:

export ANTHROPIC_API_KEY=sk-ant-...

Run

# CLI mode
nimbus-zero

# Web UI
nimbus-zero launch
nimbus-zero launch --port 8080 --host 0.0.0.0

# Continue previous session
nimbus-zero -c

Project Structure

nimbus_zero/
├── cli.py                  # CLI entry point
├── config.py               # YAML config loader
├── core/
│   ├── agent_loop.py       # 3-checkpoint execution engine
│   ├── interaction.py      # Event channel (I/O bridge)
│   ├── message.py          # Data models
│   ├── orchestrator.py     # Component wiring
│   ├── permission.py       # Permission controller
│   └── prompt.py           # Template-based prompt builder
├── llm/
│   ├── gateway.py          # Multi-provider LLM router
│   └── providers/          # Anthropic, OpenAI, OpenRouter, Ollama
├── tools/
│   ├── base.py             # Tool ABC
│   ├── registry.py         # Tool registration + schema serving
│   └── builtin/            # 20+ built-in tools
├── agents/
│   ├── registry.py         # Agent type configs
│   ├── loader.py           # Custom agent discovery (AGENT.md)
│   └── manager.py          # Sub-agent + teammate lifecycle
├── teams/
│   ├── coordinator.py      # Team lifecycle facade
│   ├── messaging.py        # Async message bus
│   └── config.py           # Team config persistence
├── tasks/
│   ├── manager.py          # Task CRUD + dependencies
│   └── store.py            # JSON file persistence
├── memory/
│   ├── manager.py          # Memory facade
│   ├── session_store.py    # JSONL session logs
│   ├── compact.py          # LLM-based context compaction
│   ├── auto_memory.py      # Persistent project memory
│   └── instructions.py     # CLAUDE.md loader
├── skills/                 # Skill system (slash commands)
├── prompts/                # System prompt templates
├── web/
│   ├── server.py           # FastAPI + WebSocket
│   ├── channel.py          # Web interaction channel
│   └── static/             # Frontend (HTML/CSS/JS)
└── configs/
    ├── agents.toml         # Built-in agent types
    └── tools.toml          # Built-in tool registry

Architecture

NimbusZero is built around the AgentLoop, a 3-checkpoint execution engine:

1. CP1 (Pre-LLM) — drain inbound events, check context compaction, check abort
2. LLM Call — streaming chat via the gateway
3. CP2 (Pre-Tool) — per-tool permission checks
4. Tool Execution — read-only tools run in parallel, write tools run sequentially
5. CP3 (Post-Tool) — drain urgent events

The loop repeats until the LLM returns text without tool calls.

For detailed architecture documentation, see documents/architecture.md.

Agent Types

Type	Purpose	Model	Tools
orchestrator	Main agent, full capabilities	Sonnet	All
general-purpose	Multi-step sub-tasks	Sonnet	File, Search, Bash, Web
explore	Fast codebase exploration	Haiku	Read-only
plan	Architecture & planning	Sonnet	Read-only
teammate	Persistent team member	Sonnet	File, Search, Bash, Web, SendMessage

Agent Teams

NimbusZero supports multi-agent collaboration through the Agent Teams system. A team lead spawns persistent teammate agents that:

• Work in parallel on shared tasks
• Communicate via direct messages and broadcasts
• Coordinate through a shared task list with dependencies
• Run in background asyncio tasks with idle loops

For detailed documentation, see documents/agent-teams.md.

Tool System

20+ built-in tools covering file operations, search, shell execution, web access, task management, and team communication. Tools are registered via TOML configs with a 3-layer merge (built-in → user → project).

Framework tools (Agent, Task*, Team*, SendMessage) use a schema-only pattern — the LLM sees the JSON Schema, but execution is handled by the AgentLoop framework.

For the full tool reference, see documents/tools.md.

Customization

Custom Tools

Create a Python class extending Tool and register via .nimbus-zero/tools.toml:

[[tools]]
name = "MyTool"
class_path = "my_package.tools.MyTool"

Custom Agents

Create .nimbus-zero/agents/{name}/AGENT.md with YAML frontmatter:

---
name: my-agent
description: A specialized agent
model: anthropic/claude-sonnet-4-6
tools: [Read, Grep, Glob, Bash]
max_turns: 30
---

You are a specialized agent that ...

Custom Skills

Create .nimbus-zero/skills/{name}/SKILL.md:

---
name: my-skill
description: Does something useful
---

Perform the following task: ...

Invoke with /my-skill in the chat.

Instructions

Project-level instructions are loaded from:

• .nimbus-zero/CLAUDE.md — project-level
• ~/.nimbus-zero/CLAUDE.md — user-level
• .nimbus-zero/rules/*.md — additional rules

Configuration

~/.nimbus-zero/config.yaml:

llm:
  default_provider: anthropic
  default_model: claude-sonnet-4-6
  providers:
    anthropic:
      api_key: ${ANTHROPIC_API_KEY}
    openrouter:
      api_key: ${OPENROUTER_API_KEY}
    ollama: {}
  aliases:
    fast: anthropic/claude-haiku-4-5-20251001
    local: ollama/llama3.2

memory:
  auto_memory_enabled: true
  auto_compact_enabled: true
  session_cleanup_days: 30

permissions:
  mode: default          # default | bypass | dont_ask | accept_edits
  allowed_tools: []      # always allowed without prompting
  disallowed_tools: []   # always require permission

Environment variable substitution is supported via ${VAR_NAME} syntax.

Requirements

• Python >= 3.12
• Dependencies: anthropic, openai, rich, prompt_toolkit, pyyaml, tiktoken, fastapi, uvicorn

License

MIT