ClawHand

ClawHand is a persistent AI assistant built on the V1 openhands-sdk with A-MEM long-term memory, LiteLLM Proxy for model routing, and a Discord gateway. It learns and evolves through every conversation, maintaining memory across sessions while operating securely within configurable boundaries.

Prerequisites

• Python 3.12+
• LiteLLM Proxy — for routing LLM requests to any provider (OpenAI, Anthropic, Ollama, etc.)
• Discord bot token — for the Discord gateway channel
• ChromaDB — installed automatically as a dependency for vector storage

Installation

# Clone the repository
git clone <repo-url>
cd clawhand

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

Configuration

1. Copy the example configuration:

cp clawhand/config/clawhand.example.yaml clawhand.yaml

2. Edit clawhand.yaml and fill in your values:

llm:
  model: "litellm_proxy/gpt-4o"
  base_url: "http://localhost:4000"
  api_key_env: "LITELLM_PROXY_KEY"    # Name of the env var holding your key

memory:
  llm_model: "litellm_proxy/gpt-4o-mini"
  chromadb_path: "./data/chromadb"

gateway:
  discord:
    enabled: true
    token_env: "DISCORD_BOT_TOKEN"     # Name of the env var holding your token
    allowed_users: []                  # Empty = allow all; add user IDs to restrict

3. Set the required environment variables:

export LITELLM_PROXY_KEY="your-litellm-api-key"
export DISCORD_BOT_TOKEN="your-discord-bot-token"

LiteLLM Proxy Setup

ClawHand routes all LLM requests through a LiteLLM Proxy instance. Start it before running ClawHand:

pip install litellm[proxy]
litellm --config config/litellm_config.yaml --port 4000

Refer to the LiteLLM documentation for proxy configuration details.

Discord Bot Setup

1. Go to the Discord Developer Portal
2. Create a new application and add a Bot
3. Enable the Message Content Intent under Privileged Gateway Intents
4. Copy the bot token and set it as DISCORD_BOT_TOKEN environment variable
5. Invite the bot to your server using the OAuth2 URL generator with bot scope and Send Messages + Read Message History permissions

Running

# Start ClawHand
clawhand

# Or run directly
python -m clawhand.main

ClawHand will:

1. Load and validate clawhand.yaml
2. Initialize the A-MEM long-term memory system
3. Build the agent with secured tools (terminal, file editor, memory)
4. Connect to Discord and start listening for messages

Architecture

ClawHand uses a composition-based approach with the V1 openhands-sdk:

• Agent — configured with tools (not subclassed), identity loaded from SOUL.md
• SecurityGuard — wraps all destructive tools with command/path/network allowlists
• MemoryTool — exposes A-MEM as an LLM-callable tool (store, recall, flush)
• MessageBus — async queue routing between channels and the conversation runner
• DiscordChannel — runs discord.py in a dedicated thread with message splitting
• ConversationRunner — per-chat locking, ThreadPoolExecutor for conv.run(), condenser hooks

See docs/ for detailed component documentation.

Development

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

# Run all tests
pytest

# Run tests with coverage
pytest --cov=clawhand --cov-report=term-missing

# Type checking
mypy clawhand/

# Linting
ruff check clawhand/ tests/