Full Documentation

Complete reference for QuantClaw features and APIs.

Table of Contents

• Quick Start
• Installation
• Configuration
• CLI Reference
• API Reference
• Plugin Development
• Architecture
• Troubleshooting

Quick Start

Get QuantClaw running in 5 minutes:

# 1. Install
git clone https://github.com/QuantClaw/quantclaw.git
cd quantclaw
mkdir build && cd build
cmake ..
cmake --build . --parallel

# 2. Configure
quantclaw onboard --quick

# 3. Run
quantclaw agent --id=main

Then open the web interface at http://localhost:8000.

Installation

See the Installation Guide for:

• Linux/Ubuntu setup
• Windows (WSL2) setup
• macOS setup
• Docker setup
• Building from source

Configuration

See the Configuration Guide for:

• Configuration file structure
• Provider setup
• Model selection
• Memory configuration
• Tool permissions
• Channel setup

CLI Reference

See the CLI Reference for complete command documentation.

Common Commands

# Agent operations
quantclaw agent --id=main              # Start agent
quantclaw agent --id=main --port 9000  # Custom port

# Run commands
quantclaw run "What is 2+2?"          # Execute command
quantclaw eval "What is 2+2?" --no-session  # Eval without session

# Session management
quantclaw sessions list                # List sessions
quantclaw sessions history SESS-ID     # View session history
quantclaw sessions compact SESS-ID     # Compact session

# Configuration
quantclaw config get                   # View config
quantclaw config validate              # Validate config
quantclaw config schema                # Show schema

# Gateway
quantclaw gateway run                  # Start gateway
quantclaw gateway status               # Check gateway status

# File operations
quantclaw file list                    # List workspace files
quantclaw file read WORKSPACE/FILE     # Read file
quantclaw file write WORKSPACE/FILE    # Write file

# Skills
quantclaw skill create my-skill        # Create new skill
quantclaw skill install ./my-skill     # Install plugin
quantclaw skill status                 # List installed skills

# Status and monitoring
quantclaw status                       # Overall status
quantclaw logs tail                    # View logs
quantclaw usage cost                   # Token usage

API Reference

QuantClaw exposes a JSON-RPC API via the gateway.

Gateway Endpoints

Base URL: http://localhost:8000

Agent Operations

POST /api/rpc
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": "req-1",
  "method": "agent.run",
  "params": {
    "message": "What is 2+2?",
    "session_id": "optional-session-id"
  }
}

Session Management

{
  "method": "sessions.list",
  "params": {}
}

{
  "method": "sessions.history",
  "params": {
    "session_id": "SESS-123"
  }
}

{
  "method": "sessions.send",
  "params": {
    "session_id": "SESS-123",
    "message": "Continue previous conversation"
  }
}

Configuration

{
  "method": "config.get",
  "params": {}
}

{
  "method": "config.validate",
  "params": {}
}

{
  "method": "config.schema",
  "params": {}
}

Tools

{
  "method": "tools.catalog",
  "params": {
    "agent_id": "main"
  }
}

{
  "method": "tools.execute",
  "params": {
    "name": "bash",
    "params": {
      "command": "ls -la"
    }
  }
}

Monitoring

{
  "method": "usage.cost",
  "params": {}
}

{
  "method": "sessions.usage",
  "params": {}
}

{
  "method": "logs.tail",
  "params": {
    "lines": 100
  }
}

WebSocket Connection

For real-time updates, connect via WebSocket:

const ws = new WebSocket('ws://localhost:8000/ws');

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  console.log('Received:', message);
};

// Send RPC request
ws.send(JSON.stringify({
  jsonrpc: '2.0',
  id: 'req-1',
  method: 'agent.run',
  params: { message: 'Hello' }
}));

Plugin Development

See the Plugin Development Guide for:

• Creating custom skills
• Implementing hooks
• Building channel adapters
• Testing plugins
• Publishing plugins

Quick Example

import type { QuantClawPlugin, SkillContext } from '@quantclaw/sdk'

export default class MyPlugin implements QuantClawPlugin {
  async initialize(context: SkillContext) {
    console.log('Plugin initialized')
  }

  getSkills() {
    return [{
      name: 'my_skill',
      description: 'My custom skill',
      input_schema: {
        type: 'object',
        properties: {
          input: { type: 'string' }
        }
      }
    }]
  }

  async executeSkill(name: string, params: any) {
    if (name === 'my_skill') {
      return JSON.stringify({ result: params.input })
    }
    throw new Error(`Unknown skill: ${name}`)
  }
}

Architecture

See the Architecture Guide for:

• System overview
• Core modules
• Data flow
• Security model
• Performance optimizations

Built-in Tools

Bash Execution

quantclaw tool bash "ls -la /home"

Schema:

{
  "name": "bash",
  "description": "Execute bash commands",
  "input_schema": {
    "properties": {
      "command": { "type": "string" }
    },
    "required": ["command"]
  }
}

Browser Control

quantclaw tool browser.launch "https://example.com"

Schema:

{
  "name": "browser",
  "description": "Chrome DevTools Protocol control",
  "input_schema": {
    "properties": {
      "action": {
        "type": "string",
        "enum": ["launch", "navigate", "screenshot", "execute"]
      }
    }
  }
}

Web Search

quantclaw tool web_search "latest AI news"

Supports multiple providers:

• Tavily (professional API)
• DuckDuckGo (free)
• Perplexity
• Grok

Web Fetch

quantclaw tool web_fetch "https://example.com"

Features:

• HTML to markdown conversion
• SSRF protection
• Timeout handling
• Cookie support

Memory Search

quantclaw tool memory_search "user preferences"

Uses BM25 scoring for relevance.

Memory Get

quantclaw tool memory_get "WORKSPACE/MEMORY.md"

Direct file access from workspace.

Troubleshooting

Common Issues

Build errors

# Clean and rebuild
rm -rf build
mkdir build && cd build
cmake ..
cmake --build .

Configuration errors

# Validate configuration
quantclaw config validate

# Reset to defaults
quantclaw onboard --reset

Plugin not loading

# Check plugin directory
ls ~/.quantclaw/plugins/

# View logs
quantclaw logs tail --level=debug

API connection issues

# Verify gateway is running
quantclaw gateway status

# Check port
netstat -tuln | grep 8000

# Test connection
curl http://localhost:8000/health

Performance Tips

1. Model Selection: Use fast model for quick tasks
2. Context Management: Enable context compaction
3. Memory: Limit search results with searchTopK
4. Tool Timeout: Set reasonable timeouts
5. Logging: Use warn level in production

Security Best Practices

1. API Keys: Store in environment variables
2. HTTPS: Enable TLS in gateway config
3. Tool Permissions: Restrict tool access
4. Sandboxing: Enable process isolation
5. Audit Logs: Enable and monitor logs

Advanced Topics

Custom Models

Configure Ollama or local models:

{
  "agents": {
    "main": {
      "providers": {
        "default": "local"
      },
      "models": {
        "default": "llama2"
      }
    }
  }
}

Multi-Agent Setup

Run multiple agents on the same gateway:

quantclaw gateway run &
quantclaw agent --id=main &
quantclaw agent --id=reasoning &

Distributed Deployment

Deploy across multiple machines with shared gateway:

# Machine 1: Run gateway
quantclaw gateway run --host 0.0.0.0

# Machine 2: Connect to remote gateway
quantclaw agent --id=main --gateway machine1:8000

---

Need help? Check the Getting Started guide or open an issue on GitHub.