RizzClaw 🐾

AI-Powered Coding Assistant

Introduction

RizzClaw is an AI-powered intelligent coding assistant built on MiniMax large language models. It helps developers with various tasks including code writing, debugging, file operations, web search, and more.

✨ Core Features

🚀 Gateway Multi-Channel Support

RizzClaw 0.2.0 introduces Gateway Mode, supporting multiple channels for AI interaction:

• Feishu (Lark) - Enterprise instant messaging integration
• Console - Command-line interactive mode
• Extensible Architecture - Easy to add Telegram, Discord, and more channels

Gateway Architecture

┌─────────────────────────────────────────┐
│              Gateway                    │
│  ┌─────────┐    ┌──────────────┐       │
│  │ Agent   │◄──►│  MessageBus  │       │
│  │  Loop   │    │              │       │
│  └─────────┘    └──────┬───────┘       │
│         ▲              │                │
│         │         ┌────┴────┐          │
│         │         │ Channels│          │
│         │         ├────┬────┤          │
│         │         │Feishu│Console│      │
│         │         └────┴────┘          │
│         ▲                              │
│    LLM API                             │
└─────────────────────────────────────────┘

Multi-User Session Isolation

Gateway mode supports multiple users simultaneously, with each user/group having independent conversation context:

User A DM → feishu_chat_aaa_user_aaa.jsonl
User B DM → feishu_chat_bbb_user_bbb.jsonl
Group Chat → feishu_group_ccc_user_aaa.jsonl

🧠 Smart Session Management (Auto-Summary)

RizzClaw features an intelligent session compression mechanism that automatically manages context windows during long conversations:

• Auto-Compression Trigger: Compression is triggered when session tokens exceed the threshold (default: 50% of 128K)
• Smart Summary Generation: Early conversations are compressed into concise summaries, preserving key information while significantly reducing token usage
• Configurable Parameters:
  • MaxTokens: Maximum token limit (default: 128000)
  • MaxHistoryShare: Maximum share of history messages (default: 0.5)
  • MinMessagesToKeep: Number of recent messages to keep (default: 10)
  • ChunkRatio: Compression ratio (default: 0.4)

┌─────────────────────────────────────────────────────────────┐
│  Session History                                             │
├─────────────────────────────────────────────────────────────┤
│  [Summary] Summary of 50 earlier messages...                │
│  [Summary] Summary of 30 mid-session messages...            │
├─────────────────────────────────────────────────────────────┤
│  [Recent] User: Help me refactor this function              │
│  [Recent] Assistant: Sure, let me help you...               │
│  ...                                                         │
└─────────────────────────────────────────────────────────────┘

💾 Long-term Memory System (BM25 + RAG)

RizzClaw implements an advanced hybrid retrieval memory system supporting long-term knowledge storage and intelligent recall:

Hybrid Retrieval Architecture

                    ┌──────────────────┐
                    │   User Query      │
                    └────────┬─────────┘
                             │
              ┌──────────────┼──────────────┐
              ▼              ▼              ▼
     ┌────────────────┐ ┌────────────────┐
     │  Vector Search │ │  BM25 Keyword  │
     │  (Semantic)    │ │  (Exact Match) │
     └───────┬────────┘ └───────┬────────┘
             │                  │
             │    ┌─────────────┘
             ▼    ▼
     ┌────────────────────┐
     │   Score Fusion     │
     │  Vector: 0.7       │
     │  Keyword: 0.3      │
     └─────────┬──────────┘
               ▼
     ┌────────────────────┐
     │   MMR Reranking    │
     │   (Optional)       │
     └─────────┬──────────┘
               ▼
     ┌────────────────────┐
     │   Temporal Decay   │
     │   (Optional)       │
     └─────────┬──────────┘
               ▼
         Final Results

Core Technologies

Memory Storage

type MemoryEntry struct {
    ID          string    // Unique identifier
    Content     string    // Memory content
    Embedding   []float32 // Vector embedding
    Keywords    []string  // Extracted keywords
    Source      string    // Source (e.g., "MEMORY.md", "conversation")
    CreatedAt   time.Time // Creation timestamp
    IsEvergreen bool      // Whether it's an evergreen memory
}

Search Configuration

type SearchOptions struct {
    MaxResults     int     // Maximum number of results (default: 6)
    MinScore       float64 // Minimum score threshold (default: 0.35)
    VectorWeight   float64 // Vector search weight (default: 0.7)
    KeywordWeight  float64 // Keyword search weight (default: 0.3)
    UseMMR         bool    // Enable MMR (default: false)
    MMRLambda      float64 // MMR relevance weight (default: 0.7)
    TemporalDecay  bool    // Enable temporal decay (default: true)
    HalfLifeDays   float64 // Temporal decay half-life (default: 30 days)
}

🛠️ Other Features

• 🤖 AI-Powered - Built on advanced MiniMax M2.1/M2.5 large language models
• 📁 Rich Tools - Built-in file operations, code execution, web search, and more
• ⚡ Skills System - Compatible with skills.sh ecosystem, load custom skill extensions

🎯 Skills System

RizzClaw supports the skills.sh ecosystem, allowing you to extend AI capabilities with modular skill packages.

Installing Skills

# Install a skill globally
npx skills add vercel-labs/agent-skills

# Install a skill for current project
npx skills add vercel-labs/agent-skills --local

Skills Loading Paths

Skills are automatically loaded from the following directories (in priority order):

Skills CLI Commands

# List all skills
rizzclaw skills list

# List only eligible skills (enabled + dependencies met)
rizzclaw skills list --eligible

# Show skill details
rizzclaw skills info 

# Enable/disable a skill
rizzclaw skills enable 
rizzclaw skills disable 

# Check skill dependencies
rizzclaw skills check [skill-id]

# Reload skills from disk
rizzclaw skills reload

Skill File Format (SKILL.md)

---
name: my-skill
description: "Description of what this skill does"
version: "1.0.0"
author: YourName
emoji: "🚀"
when: "When to use this skill"
tags:
  - tag1
  - tag2
requires:
  bins:
    - git
  env:
    - GITHUB_TOKEN
---

# Skill Instructions

Detailed instructions for the AI agent...

Dependency Checking

Skills can declare dependencies that are checked at runtime:

• requires.bins - Required binaries (all must be available)
• requires.anyBins - Alternative binaries (at least one must be available)
• requires.env - Required environment variables
• os - Supported operating systems

Skills with unmet dependencies are automatically excluded from the prompt.

🔍 Web Search

• DuckDuckGo Integration - Uses DuckDuckGo HTML search instead of Bing for better accessibility
• Proxy Support - Automatically reads proxy configuration from environment variables:
  • HTTP_PROXY / http_proxy - HTTP proxy
  • HTTPS_PROXY / https_proxy - HTTPS proxy
  • NO_PROXY / no_proxy - Bypass proxy for specific hosts

Tech Stack

• Language: Go 1.23+
• CLI Framework: Cobra
• Configuration: Viper
• Database: SQLite3 (memory storage)
• Full-text Search: SQLite FTS5 (BM25)
• LLM Provider: MiniMax API

Quick Start

Screenshot

Installation

# Clone the project
git clone https://github.com/hoorayman/rizzclaw.git
cd rizzclaw

# Build
go build -o rizzclaw ./main.go

# Run
./rizzclaw chat

Configuration

1. Copy the example config file:

cp config.example.json ~/.rizzclaw/config.json

2. Edit config.json and add your MiniMax API Key:

{
  "models": {
    "mode": "merge",
    "providers": {
      "minimax": {
        "baseUrl": "https://api.minimaxi.com/anthropic",
        "apiKey": "API_KEY",
        "api": "anthropic-messages",
        "models": [
          {
            "id": "MiniMax-M2.1",
            "name": "MiniMax M2.1",
            "reasoning": false,
            "input": ["text"],
            "cost": {
              "input": 0.3,
              "output": 1.2,
              "cacheRead": 0.03,
              "cacheWrite": 0.12
            },
            "contextWindow": 200000,
            "maxTokens": 8192
          },
          {
            "id": "MiniMax-M2.1-lightning",
            "name": "MiniMax M2.1 Lightning",
            "reasoning": false,
            "input": ["text"],
            "cost": {
              "input": 0.3,
              "output": 1.2,
              "cacheRead": 0.03,
              "cacheWrite": 0.12
            },
            "contextWindow": 200000,
            "maxTokens": 8192
          },
          {
            "id": "MiniMax-M2.5",
            "name": "MiniMax M2.5",
            "reasoning": true,
            "input": ["text"],
            "cost": {
              "input": 0.3,
              "output": 1.2,
              "cacheRead": 0.03,
              "cacheWrite": 0.12
            },
            "contextWindow": 200000,
            "maxTokens": 8192
          },
          {
            "id": "MiniMax-M2.5-Lightning",
            "name": "MiniMax M2.5 Lightning",
            "reasoning": true,
            "input": ["text"],
            "cost": {
              "input": 0.3,
              "output": 1.2,
              "cacheRead": 0.03,
              "cacheWrite": 0.12
            },
            "contextWindow": 200000,
            "maxTokens": 8192
          },
          {
            "id": "MiniMax-VL-01",
            "name": "MiniMax VL 01",
            "reasoning": false,
            "input": ["text", "image"],
            "cost": {
              "input": 0.3,
              "output": 1.2,
              "cacheRead": 0.03,
              "cacheWrite": 0.12
            },
            "contextWindow": 200000,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "minimax/MiniMax-M2.5": {
          "primary": "minimax/MiniMax-M2.5",
          "alias": "Minimax"
        }
      },
      "timeout": 120
    }
  }
}

Usage

# Show help
rizzclaw --help

# Start interactive chat (Console mode)
rizzclaw chat

# Start Gateway service
rizzclaw gateway

# Start Gateway in debug mode (show message logs)
rizzclaw gateway -d

# List available models
rizzclaw models

# Show current configuration
rizzclaw config show

# Skills management
rizzclaw skills list              # List all skills
rizzclaw skills list --eligible   # List eligible skills only
rizzclaw skills info    # Show skill details
rizzclaw skills enable  # Enable a skill
rizzclaw skills disable # Disable a skill
rizzclaw skills check             # Check skill dependencies
rizzclaw skills reload            # Reload skills from disk

Interactive Commands

In chat mode, the following commands are available:

Feishu Integration

1. Create an enterprise app on Feishu Open Platform and obtain App ID and App Secret

2. Add Feishu configuration to config.json:

{
  "channels": {
    "feishu": {
      "enabled": true,
      "app_id": "cli_xxxxxxxx",
      "app_secret": "xxxxxxxx",
      "encrypt_key": "optional",
      "verification_token": "optional",
      "allow_from": []
    }
  }
}

3. Start the Gateway service:

rizzclaw gateway

4. Search for your app in Feishu and start chatting

Feishu Conversation Examples

Project Structure

rizzclaw/
├── cmd/                # CLI command entry
│   ├── root.go         # Root command and chat command
│   ├── gateway.go      # Gateway command
│   └── skills.go       # Skills management commands
├── internal/           # Internal packages
│   ├── agent/          # Agent core logic
│   │   ├── agent.go    # Agent implementation
│   │   └── session.go  # Session management
│   ├── llm/            # LLM client abstraction
│   ├── tools/          # Tool collection
│   ├── skills/         # Skills system
│   │   ├── loader.go   # Skill loader (SKILL.md parser)
│   │   └── registry.go # Skill registry & dependency checking
│   ├── context/        # Context management
│   │   ├── manager.go  # Context manager
│   │   ├── session.go  # Session storage & compression
│   │   ├── memory.go   # Memory storage & retrieval
│   │   └── types.go    # Type definitions
│   ├── minimax/        # MiniMax API integration
│   └── config/         # Configuration management
├── docs/               # Documentation resources
│   └── pics/           # Image resources
└── main.go             # Program entry point

Supported Models

Data Storage Location

All data is stored in the .rizzclaw folder in the user’s home directory:

~/.rizzclaw/
├── config.json        # Configuration file
├── memory.db          # Memory database (SQLite)
├── sessions/          # Session storage
│   └── session-*.jsonl
├── workspace/         # Context files
│   ├── MEMORY.md      # Long-term memory
│   ├── USER.md        # User preferences
│   └── ...
└── skills/            # Skills registry
    └── skills.json    # Skills state (enabled/disabled)

~/.agents/skills/      # Global skills (npx skills add)
├── skill-a/
│   └── SKILL.md
└── skill-b/
    └── SKILL.md

License

MIT License - See LICENSE file for details

---

Made with ❤️ by RizzClaw