Building Resilient, Long-Horizon AI Agents with Operating System Principles.
Nimbus is an AI Agent runtime framework inspired by OS kernel design. It treats the LLM as a CPU and builds a complete system abstraction around it — focusing on solving context drift, state management failures, and stability issues that plague agents during complex, long-horizon tasks.
Current version: v0.2.0 (Nimbus Next)
┌─────────────────────────────────────────────────┐
│ AgentOS (Facade) │
├──────────┬──────────┬──────────┬────────────────┤
│ VCPU │ MMU │KernelGate│ ALU / Adapter │
│ FSM引擎 │上下文管理│ 工具执行 │ LLM 接口层 │
├──────────┴──────────┴──────────┴────────────────┤
│ RuntimeLoop (驱动层) │
│ Think → Act → Observe → Think … │
└─────────────────────────────────────────────────┘
FSM-driven Think-Act-Observe loop:
IDLE ──→ THINKING ──→ ACTING ──→ OBSERVING
↑ │
│ (token正常) │ (token > 85%)
└───────────────────────┘
│
↓
COMPRESSING
/ \
(压缩成功) / \ (超过 max_compactions)
↓ ↓
THINKING DEAD
THINKING/ACTING ──→ ERROR ──→ (retryable?) ──→ THINKING
└─────────→ DEAD
COMPRESSING triggers (3 paths):
- Proactive: token usage > 85% detected at loop start
- Reactive: LLM returns
CTX_OVERFLOWerror - Budget: iteration count exceeds limit (
BUDGET_EXCEEDED), resets counter
Safety: max 3 compressions (max_compactions), cooldown of 5 steps between compressions. Exceeding → DEAD.
- Max iterations: 200 (context compression is the real resource boundary)
- Real-time Steering injection (user can insert new instructions mid-run)
- Parallel tool calls via
asyncio.gather
- Pinned Context (Anchors): Fixed system rules and core goals, preventing LLM recency bias from causing "forgetting"
- Dynamic Stream: Auto-tracks conversation history, triggers compression at 85% token usage
- Compression strategies: Sliding Window (default) / Summary Compression / Semantic Relevance filtering (requires embedding service)
- Default context budget: 100k tokens (standard) / 1M tokens (claude-sonnet-4-6)
- Permission whitelist/blacklist filtering
asyncio.wait_fortimeout + process groupSIGKILLisolation- Tool result separation:
output(LLM-visible) +ui_detail(UI-only display) - Doom loop detection: consecutive identical tool calls are intercepted
Three-channel auto-selection:
| Channel | Use Case |
|---|---|
| Anthropic Native (OAuth) | Claude models + Pi OAuth credentials |
| OpenAI Codex (OAuth) | Codex models + ChatGPT subscription credentials |
| LiteLLM (default) | Gemini, OpenAI API Key, all other models |
Unix philosophy: sub-agents are subprocesses, spawned via tool calls.
# Sync: parent agent blocks and waits for result
spawn_agent(role="reader", goal="Read all test files and summarize coverage")
# Async: runs in background, returns PID
spawn_agent(role="worker", goal="Refactor the auth module", mode="async")Key design:
- Sub-agents get a fresh, independent MMU — zero context pollution to parent
- Parent only receives a structured summary (max 4000 chars), not raw output
- Sub-agents operate in
contract_mode: they MUST callsubmit_resultto deliver findings - Each sub-agent writes to its own scratchpad at
.nimbus/sessions/{sub_id}/scratchpad.md - Framework handles timeout, retry, and error isolation — parent just sees success/failure
- Role-based permissions:
readeragents can only Read/Grep;workeragents get full tool access
Context pressure test result: 22 parallel sub-agents reading 100+ files consumed only ~20% of the parent agent's context window — the rest was contained within sub-agent boundaries.
| Tool | Description |
|---|---|
bash |
Execute shell commands with streaming output and auto-truncation |
read |
Read file contents with offset/limit support |
write |
Write files, auto-creates parent directories |
edit |
Exact text replacement with fuzzy fallback |
grep |
Regex search across files with glob filtering |
spawn_agent |
Delegate complex sub-tasks to independent child agents |
submit_result |
Sub-agent result delivery (contract mode) |
Custom tools via @tool decorator:
from nimbus.core.tools.registry import tool
@tool
async def my_tool(param: str) -> str:
return f"result: {param}"Real-time conversational interface built with Next.js 14 + TypeScript + Tailwind CSS.
- SSE real-time streaming (
_pendingStreamMsgrAF buffer — solves same-frame event overwrite) - Session management with create/delete/switch
- Tool execution visualization with expandable cards
- Sub-agent spawn timeline with nested tool call display
- Context window usage indicator (token count + percentage bar)
- Model selector with multi-provider support
- Port:
3000(production) /3001(staging)
# Clone
git clone https://github.com/WQ09CE/nimbus.git
cd nimbus
# Install (uv recommended)
pip install -e ".[llm]"
# Start server
nimbus serve
# Start Web UI (separate terminal)
cd web-ui && npm install && npm run devDocker deployment with the web UI and AgentOS API in one app container, plus Ollama in Compose:
docker compose up --buildDefault local model:
NIMBUS_MODEL=ollama/gemma4:26b
OLLAMA_MODEL=gemma4:26b
OLLAMA_GPU_DEVICE=1See Docker Deployment for ports, token, volumes, and logs.
For backend-only Docker development, use the dev override to mount local
./src into the app container, then restart without rebuilding:
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d
make docker-dev-restartEnvironment variables (pick one):
# API Key mode
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
# Or Pi OAuth (auto-reads from ~/.pi/agent/auth.json)The offline suite runs with no credentials. Provider integration tests are
marked (anthropic, openai, google, ollama) and deselected by default —
they hit live models and need API keys or a local Ollama server.
# Offline suite — no API keys required (expect all green)
pytest -m "not anthropic and not openai and not google and not ollama and not slow"
# Core unit tests only
pytest tests/core --tb=short
# Everything, including live provider integration (needs API keys / Ollama)
pytest tests/ --tb=shortOffline run: 484 passed, 86 deselected. Requires Python 3.10+.
nimbus/
├── src/nimbus/
│ ├── core/
│ │ ├── agent.py # AgentOS facade (367 lines)
│ │ ├── vcpu.py # FSM execution engine (326 lines)
│ │ ├── mmu.py # Context management (486 lines)
│ │ ├── gate.py # KernelGate safety layer (202 lines)
│ │ ├── loop.py # RuntimeLoop driver (593 lines)
│ │ ├── decoder.py # InstructionDecoder
│ │ ├── protocol.py # Event / ActionIR / ToolResult protocol
│ │ ├── storage.py # Conversation persistence
│ │ ├── models/ # Model registry & manifests
│ │ └── tools/ # Built-in tool implementations
│ │ ├── bash.py, read.py, write.py, edit.py, grep.py
│ │ ├── spawn_agent.py # Multi-agent orchestration (421 lines)
│ │ ├── submit_result.py # Sub-agent result delivery
│ │ └── registry.py # Tool registration & schema
│ ├── adapters/
│ │ ├── direct_adapter.py # Three-channel LLM adapter
│ │ ├── llm_factory.py # Model factory
│ │ └── types.py # LLM adapter type definitions
│ ├── server/
│ │ ├── api.py # FastAPI routes
│ │ ├── session.py # SessionManagerV2
│ │ ├── sse.py # SSE Hub
│ │ ├── permission.py # Runtime permission rules
│ │ └── log_hub.py # Real-time log streaming
│ ├── plugins/ # Runtime plugin discovery and activation
│ ├── skills/ # Prompt skill loading
│ └── cli/ # nimbus CLI (serve, run, config, session, acp)
├── web-ui/ # Next.js frontend (21 components)
├── tests/ # Test suite (30 files, 550+ tests)
├── docs/ # Architecture & design documents
└── skills/ # Pluggable skill packs
| Document | Description |
|---|---|
| Architecture Overview | High-level framework design |
| Actual Architecture | Implementation reality vs. design |
| Toolchain Design | Tool system philosophy |
| Plugin System | Plugin discovery, activation, and reload model |
| Multi-Agent Collaboration | spawn_agent design rationale |
| State & Context Management | MMU and context strategies |
| System Rules & Prompting | Prompt engineering approach |
| Key Technologies | Core technical innovations |
| Pi Coding Agent Study | Research on Pi's architecture |
| Pi Robustness Study | Robustness analysis |
| Sub-agent Orchestration | Detailed orchestration design |
- spawn_agent real implementation — Nested
AgentOSinstances with contract mode - Context window usage UI — Token count + percentage indicator in footer
- Sub-agent timeline visualization — Expandable tool call cards in Web UI
- async spawn polling API —
wait_agent(pid)/kill_agent(pid)tools - MMU modularization — Split into
context_manager/compressor/pinned_store - Process tree UI — Visualize parent-child agent relationships
- Semantic Compression — Integrate embedding service for relevance-based filtering
Nimbus — Giving LLMs true system-level execution capabilities.