spoon-bot

# spoon-bot

Local-first AI agent with native OS tools, powered by spoon-core.

## Features

- **Multi-Provider LLM**: Supports Anthropic, OpenAI, DeepSeek, Gemini, OpenRouter (400+ models), and more
- **Agent-centric**: Autonomous execution with safety rails and dynamic tool loading
- **OS-native**: Built-in shell/filesystem tools as priority
- **Memory-first**: Four-layer memory system (file + semantic search via memsearch + short-term + checkpointer)
- **Session Persistence**: Pluggable backends — JSONL files (default), SQLite, or PostgreSQL
- **Web Search**: Built-in Tavily integration for real-time information retrieval
- **Self-managing**: Self-configuration, self-upgrade, memory management tools
- **Web3-enabled**: Blockchain operations via spoon-core and spoon-toolkits
- **Extensible**: MCP servers + Skills ecosystem with dynamic tool activation
- **Multi-channel**: Telegram bot integration with polling/webhook modes
- **Multi-mode**: Agent / Interactive / Gateway (REST + WebSocket)

## Requirements

- **Python 3.12+** (required by spoon-ai-sdk)

## Installation

### Using uv (Recommended)

```bash
# Clone the repository
git clone https://github.com/XSpoonAi/spoon-bot.git
cd spoon-bot

# Install with uv (creates .venv automatically)
uv sync

# Or with all extras
uv sync --all-extras
```

### Using pip

```bash
# Clone the repository
git clone https://github.com/XSpoonAi/spoon-bot.git
cd spoon-bot

# Create virtual environment (Python 3.12+ required)
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install
pip install -e .

# Or with all extras
pip install -e ".[all]"
```

## Configuration

### Environment Variables

Copy `.env.example` to `.env` and configure your API keys:

```bash
cp .env.example .env
```

**At least one LLM API key is required:**

| Provider | Environment Variable | Get API Key |
|----------|---------------------|-------------|
| Anthropic | `ANTHROPIC_API_KEY` | [console.anthropic.com](https://console.anthropic.com/) |
| OpenAI | `OPENAI_API_KEY` | [platform.openai.com](https://platform.openai.com/) |
| DeepSeek | `DEEPSEEK_API_KEY` | [platform.deepseek.com](https://platform.deepseek.com/) |
| Google Gemini | `GEMINI_API_KEY` | [aistudio.google.com](https://aistudio.google.com/) |
| OpenRouter | `OPENROUTER_API_KEY` | [openrouter.ai](https://openrouter.ai/) |
| Tavily (web search) | `TAVILY_API_KEY` | [tavily.com](https://tavily.com/) |

Example `.env` file:

```bash
# Use any ONE of these (or multiple for fallback)
ANTHROPIC_API_KEY=sk-ant-xxx
OPENAI_API_KEY=sk-xxx
DEEPSEEK_API_KEY=xxx
GEMINI_API_KEY=xxx
OPENROUTER_API_KEY=sk-or-xxx

# Optional: web search
TAVILY_API_KEY=tvly-xxx
```

### Channel Configuration (config.yaml)

To enable Telegram or other channel integrations, create a `config.yaml` in the project root:

```yaml
agent:
  provider: anthropic
  model: claude-sonnet-4-20250514
  # api_key: sk-xxx  # Or use environment variable

channels:
  telegram:
    enabled: true
    accounts:
      - name: my_bot
        token: ${TELEGRAM_BOT_TOKEN}   # Reference env var
        mode: polling                   # polling (default) or webhook
        allowed_users: [123456789]      # Optional: restrict to specific user IDs
        proxy_url: "http://127.0.0.1:7897"  # Optional: for restricted networks
        groups:
          enabled: false
          require_mention: true
```

**Telegram setup:**

1. Create a bot via [@BotFather](https://t.me/BotFather) and get the token
2. Set `TELEGRAM_BOT_TOKEN` in `.env` or directly in `config.yaml`
3. Install the Telegram dependency: `uv sync --extra telegram`

**Proxy configuration** (for networks that cannot access Telegram API directly):

The proxy is resolved in priority order: `config.yaml proxy_url` > `TELEGRAM_PROXY` env var > `HTTPS_PROXY` env var. Users with unrestricted network access do not need this.

## Quick Start

### Using Anthropic Claude (Default)

```bash
export ANTHROPIC_API_KEY=your-key

# Initialize workspace
spoon-bot onboard

# Run in interactive mode
spoon-bot agent

# Run in one-shot mode
spoon-bot agent -m "List files in the current directory"
```

### Using Other Providers

```bash
# OpenAI GPT-5.2
export OPENAI_API_KEY=your-key
spoon-bot agent --provider openai --model gpt-5.2

# DeepSeek V3.2
export DEEPSEEK_API_KEY=your-key
spoon-bot agent --provider deepseek --model deepseek-v3.2

# Google Gemini 3
export GEMINI_API_KEY=your-key
spoon-bot agent --provider gemini --model gemini-3-flash-preview

# OpenRouter (access 400+ models with one key)
export OPENROUTER_API_KEY=sk-or-xxx
spoon-bot agent --provider openrouter --model anthropic/claude-sonnet-4.5
```

## LLM Providers

spoon-bot supports multiple LLM providers through the spoon-ai-sdk. You can switch providers without code changes.

### Supported Providers

| Provider | Recommended Models | Context | Notes |
|----------|-------------------|---------|-------|
| **Anthropic** | `claude-opus-4.6`, `claude-sonnet-4.5`, `clau

... (truncated)