Project Structure

nanobot/
├── agent/              # 🧠 Core agent logic
│   ├── loop.py         #    Agent loop (LLM ↔ tool execution)
│   ├── context.py      #    Prompt builder
│   ├── memory.py       #    Persistent memory (MEMORY.md)
│   ├── skills.py       #    Skills loader
│   ├── subagent.py     #    Background task execution
│   └── tools/          #    Built-in tools
│       ├── base.py     #      Tool interface
│       ├── registry.py #      Tool registry
│       ├── shell.py    #      Execute shell commands
│       ├── filesystem.py #    Read/write/edit/list files
│       ├── web.py      #      Web search and fetch
│       ├── spawn.py    #      Spawn subagents
│       ├── cron.py     #      Schedule tasks
│       ├── message.py  #      Send messages to channels
│       └── mcp.py      #      MCP server integration
│
├── skills/             # 🎯 Bundled skills
│   ├── github.md       #    GitHub operations
│   ├── weather.md      #    Weather queries
│   ├── tmux.md         #    Tmux management
│   └── ...             #    Other skills
│
├── channels/           # 📱 Chat channel integrations
│   ├── base.py         #    BaseChannel interface
│   ├── manager.py      #    Channel lifecycle management
│   ├── telegram.py     #    Telegram bot
│   ├── discord.py      #    Discord bot
│   ├── whatsapp.py     #    WhatsApp bridge
│   ├── feishu.py       #    Feishu/Lark
│   ├── email.py        #    Email (IMAP/SMTP)
│   ├── slack.py        #    Slack (Socket Mode)
│   ├── qq.py           #    QQ bot
│   ├── dingtalk.py     #    DingTalk
│   ├── matrix.py       #    Matrix/Element
│   └── mochat.py       #    Mochat/Claw IM
│
├── bus/                # 🚌 Message routing
│   ├── queue.py        #    MessageBus implementation
│   └── events.py       #    InboundMessage, OutboundMessage
│
├── cron/               # ⏰ Scheduled tasks
│   ├── service.py      #    Cron job scheduler
│   └── types.py        #    Job data structures
│
├── heartbeat/          # 💓 Proactive wake-up
│   └── service.py      #    Periodic task execution (HEARTBEAT.md)
│
├── providers/          # 🤖 LLM providers
│   ├── base.py         #    LLMProvider interface
│   ├── registry.py     #    Provider registry (ProviderSpec)
│   ├── litellm_provider.py # LiteLLM wrapper
│   ├── custom_provider.py  # Direct OpenAI-compatible
│   ├── openai_codex_provider.py # OAuth providers
│   └── transcription.py    # Voice transcription (Groq)
│
├── session/            # 💬 Conversation sessions
│   └── manager.py      #    Session storage and retrieval
│
├── config/             # ⚙️ Configuration
│   ├── schema.py       #    Pydantic models (Config classes)
│   └── loader.py       #    Load and validate config.json
│
├── cli/                # 🖥️ Command-line interface
│   └── commands.py     #    CLI commands (agent, gateway, status, etc.)
│
├── templates/          # 📄 Template files
│   └── memory/         #    MEMORY.md, HEARTBEAT.md templates
│
├── utils/              # 🔧 Utilities
│   └── helpers.py      #    Helper functions
│
├── __main__.py         # 🚪 Entry point (nanobot command)
└── __init__.py         # 📦 Package initialization

Channel → InboundMessage → Bus → AgentLoop
AgentLoop → OutboundMessage → Bus → Channel

{
  "history": [
    {"role": "user", "content": "Hello"},
    {"role": "assistant", "content": "Hi there!"}
  ]
}

{
  "providers": { ... },
  "channels": { ... },
  "tools": { ... },
  "agents": { ... }
}

## Periodic Tasks
- [ ] Check weather
- [ ] Review emails

# Skill Name

Description of what this skill does.

## Usage

When the user asks about X, do Y.

## Example

User: "Create a GitHub issue"
Agent: Uses GitHub API via web_fetch...

~/.nanobot/
├── config.json              # User configuration
├── workspace/               # Agent workspace
│   ├── MEMORY.md            # Persistent memory
│   ├── HEARTBEAT.md         # Periodic tasks
│   ├── cron/
│   │   └── jobs.json        # Scheduled jobs
│   └── ...                  # Agent working files
├── sessions/                # Conversation history
│   ├── telegram_123.json
│   ├── discord_456.json
│   └── ...
├── skills/                  # User-installed skills
│   └── custom_skill.md
├── media/                   # Downloaded media files
│   ├── image_123.jpg
│   └── voice_456.ogg
└── logs/                    # Log files (if configured)

from nanobot.agent.loop import AgentLoop
from nanobot.bus.events import InboundMessage, OutboundMessage
from nanobot.bus.queue import MessageBus
from nanobot.channels.base import BaseChannel
from nanobot.config.loader import load_config
from nanobot.providers.base import LLMProvider
from nanobot.session.manager import SessionManager

if not self.config.api_key:
    logger.error("API key not configured")
    return

await self.client.connect()
logger.info("Connected successfully")

self.client.connect() if self.config.api_key else logger.error("No key")
logger.info("Connected") if self.client.connected else None

def process_message(content: str, sender_id: str) -> dict:
    """Process an incoming message.
    
    Args:
        content: The message text.
        sender_id: The sender's identifier.
    
    Returns:
        A dict with processing results.
    """

try:
    result = await risky_operation()
except Exception as e:
    logger.error("Operation failed: {}", e)
    return default_value

PROVIDERS: tuple[ProviderSpec, ...] = (
    ProviderSpec(name="openai", ...),
    ProviderSpec(name="anthropic", ...),
)

def find_by_name(name: str) -> ProviderSpec | None:
    for spec in PROVIDERS:
        if spec.name == name:
            return spec
    return None

# Channel publishes
await bus.publish_inbound(InboundMessage(...))

# Agent subscribes
msg = await bus.get_inbound()
await agent.process(msg)

# Agent publishes
await bus.publish_outbound(OutboundMessage(...))

# Channel subscribes
msg = await bus.get_outbound()
await channel.send(msg)

class BaseTool(ABC):
    @abstractmethod
    async def execute(self, **kwargs) -> str:
        pass

class ExecTool(BaseTool):
    async def execute(self, command: str) -> str:
        # Implementation
        pass

class BaseChannel(ABC):
    async def start(self):
        pass
    
    async def send(self, msg):
        pass
    
    async def stop(self):
        pass