clawbert 0.0.3a25
Clawbert - AI CLI Assistant with memory and skills
Requires Python: >=3.10

# Clawbert

<p align="center">
  <img src=".github/icon.png" alt="Clawbert Logo" width="256">
</p>

<p align="center">
  <b>Your AI CLI Companion with Memory, Skills, and Endless Capabilities</b>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/python-3.10+-blue" alt="Python">
  <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
  <img src="https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-yellow" alt="Platform">
</p>

---

## Overview

Clawbert is a powerful Python-based AI CLI assistant that brings modern AI capabilities to your terminal. With support for multiple LLM providers, extensive tool calling, persistent memory, customizable skills, and a rich plugin system, Clawbert is your ultimate coding companion.

### Key Features

- **🤖 Multi-Provider AI** - OpenRouter, OpenAI, Anthropic, Ollama
- **🔧 22 Built-in Tools** - File ops, git, databases, HTTP, memory, tasks
- **💾 Persistent Memory** - Key-value + vector semantic search
- **🎯 10 Bundled Skills** - Development, DevOps, web, security
- **🌐 REST API** - Programmatic access with authentication
- **🔌 Plugin System** - Extend with custom tools
- **📊 Usage Tracking** - Privacy-first telemetry
- **✅ Tested** - Comprehensive unit tests

---

## Quick Start

### Install

```bash
git clone https://github.com/ForgedInFiles/Clawbert.git
cd Clawbert
pip install -e .
```

### Configure

```bash
# Interactive wizard (recommended)
clawbert wizard

# Or manually
clawbert config --provider openrouter --api-key YOUR_KEY
```

### Use

```bash
clawbert chat                    # Interactive chat
clawbert chat "Hello!"          # Single prompt
```

---

## CLI Commands

| Command | Description |
|---------|-------------|
| `clawbert chat` | Interactive chat |
| `clawbert config` | Configure settings |
| `clawbert session` | Manage sessions |
| `clawbert memory` | Manage memory |
| `clawbert skill` | Manage skills |
| `clawbert api` | Start REST API |
| `clawbert mcp` | MCP server mode |
| `clawbert plugin` | Manage plugins |
| `clawbert workflow` | Run workflows |
| `clawbert schedule` | Manage scheduled tasks |
| `clawbert expose` | Remote exposure |
| `clawbert wizard` | Setup wizard |
| `clawbert doctor` | Diagnostics |

[Full CLI Reference](./docs/cli-commands.md)

---

## Documentation

### Getting Started
- [Installation](./docs/installation.md) - How to install
- [Getting Started](./docs/getting-started.md) - Quick start guide

### Core Features
- [Configuration](./docs/configuration.md) - Complete config guide
- [Memory](./docs/memory.md) - Persistent memory system
- [Skills](./docs/skills.md) - 10 bundled skills
- [Tools](./docs/tools.md) - 22 available tools

### Advanced Features
- [Providers](./docs/providers.md) - Multi-model support
- [API Server](./docs/api.md) - REST API endpoints
- [Plugins](./docs/plugins.md) - Custom extensions
- [Workflows](./docs/workflows.md) - Task automation
- [Scheduler](./docs/scheduler.md) - Cron-like scheduling
- [Telemetry](./docs/telemetry.md) - Usage tracking
- [MCP](./docs/mcp.md) - Model Context Protocol
- [Exposure](./docs/exposure.md) - Remote access

---

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                        Clawbert                             │
├─────────────────────────────────────────────────────────────┤
│  CLI (chat, config, session, memory, skill, api, mcp...)  │
├─────────────────────────────────────────────────────────────┤
│  Core Modules                                              │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────────┐  │
│  │   LLM   │ │  Tools  │ │ Skills  │ │ Memory System   │  │
│  │Provider │ │Registry │ │Registry │ │ (file + vector) │  │
│  └─────────┘ └─────────┘ └─────────┘ └─────────────────┘  │
├─────────────────────────────────────────────────────────────┤
│  Extensions                                                │
│  ┌──────┐ ┌────────┐ ┌──────────┐ ┌────────┐ │
│  │API   │ │Plugins │ │ Telemetry│ │   UI   │
│  └──────┘ └────────┘ └──────────┘ └────────┘ │
└─────────────────────────────────────────────────────────────┘
```

---

## Project Structure

```
Clawbert/
├── ClawbertCLI/           # Main package
│   ├── __init__.py       # Package init with version
│   ├── cli.py            # CLI commands
│   ├── core/             # Core modules
│   │   ├── config.py     # Configuration
│   │   ├── llm.py       # LLM client
│   │   ├── providers.py  # Multi-provider support
│   │   ├── platform.py  # Platform utilities
│   │   └── todo.py     # Todo management
│   ├── tools/            # Tool registry (22 tools)
│   │   ├── base.py      # Tool base class
│   │   ├── file_tools.py
│   │   ├── git_tools.py
│   │   ├── web_tools.py
│   │   ├── system_tools.py
│   │   ├── database_tools.py
│   │   ├── scheduler_tools.py
│   │   ├── memory_tools.py
│   │   ├── skill_tools.py
│   │   ├── session_tools.py
│   │   ├── mcp_tools.py
│   │   ├── todo_tools.py
│   │   └── registry.py
│   ├── skills/           # Skill system
│   │   ├── registry.py
│   │   └── default/     # 10 bundled skills
│   ├── memory/          # Memory system
│   │   ├── keyvalue.py
│   │   ├── vector.py
│   │   └── files/      # Memory files (AGENTS.md, SOUL.md, etc.)
│   ├── session/         # Session management
│   │   └── manager.py
│   ├── services/        # Extended services
│   │   ├── api.py      # REST API server
│   │   ├── mcp.py     # MCP server/client
│   │   ├── plugins.py  # Plugin system
│   │   ├── workflows.py
│   │   ├── scheduler.py
│   │   ├── telemetry.py
│   │   └── exposure.py
│   ├── ui/             # Console UI
│   └── utils/          # Utilities
│       ├── completions.py
│       └── wizard.py
├── tests/               # Test suite (44 tests)
├── docs/               # Documentation
└── pyproject.toml     # Project config
```

---

## Configuration

Config file: `~/.clawbert/config.json`

```json
{
  "model_provider": "openrouter",
  "default_model": "stepfun/step-3.5-flash:free",
  "temperature": 0.7,
  "max_tokens": 4096,
  "enabled_tools": ["read", "write", "edit", "grep", ...],
  "vector_memory_enabled": false,
  "telemetry_enabled": false
}
```

---

## Development

```bash
# Install with dev dependencies
pip install -e ".[dev]"

# Lint
ruff check ClawbertCLI/

# Format
ruff format ClawbertCLI/

# Run tests
python -m pytest tests/ -v
```

---

## Testing

The test suite includes **44 comprehensive tests** covering:

- Config management
- Tools registry and execution (20+ tools)
- Memory system
- Skills system
- Session management
- LLM providers
- CLI commands
- Integration tests
- Edge cases

Run tests:
```bash
python -m pytest tests/ -v
```

---

## License

MIT

---

## Links

- [GitHub](https://github.com/ForgedInFiles/Clawbert)
- [Issues](https://github.com/ForgedInFiles/Clawbert/issues)

---

<div align="center">

**Built with Python, Rich, and OpenRouter**

</div>