README.md

# VersperClaw: Not Only AI Assistant Code Agent

<div align="center">
  <img src="assets/VersperAI_Banner.png" alt="VersperAI">
</div>

## 1. Quick Start

```bash
# script install
curl -fsSL https://raw.githubusercontent.com/versperai/VersperClaw/main/install.sh | bash

# source install
git clone https://github.com/versperai/VersperClaw.git && cd VersperClaw && bun install && bun run build:dev:full && ./VersperClaw 

# if want global use bin file
cp VersperClaw ~/.local/bin
# then can use VersperClaw in everywhere
```

## 2. WebSearch & WebFetch Tools - 100% local free no remote api fee

<table align="center">
  <tr>
    <td><img src="assets/WebSearchTool.png"></td>
    <td><img src="assets/WebSearchTool2.png"></td>
    <td><img src="assets/WebSearchTool3.png"></td>
  </tr>
</table>

### Choice One - SearXNG:

#### 1. Docker Configuration

```bash
# local config search engine - searxng in archlinux
# make sure have install docker and docker-compose
sudo pacman -S docker-compose && docker
docker --version && docker compose version
sudo usermod -aG docker $USER

# make sure open pc and now start docker daemon
sudo systemctl enable --now docker
```

#### 2. Docker-Compose Pull

> use VersperSearch a pre-build docker config in https://github.com/versperai/VersperSearch

```bash
# or install searxng in docker-compose by yourself
curl -fsSL \
  -O https://raw.githubusercontent.com/searxng/searxng/master/container/docker-compose.yml \
  -O https://raw.githubusercontent.com/searxng/searxng/master/container/.env.example

# add json source in formats behind html - jsonl in 87 lines
cd searxng/core-config/ && sudo nvim settings.yml

# start searxng engine
docker compose up -d
```

#### 3. Check Search Feature

```bash
# check in every browser
firefox http://localhost:8080

# set tool_search env in ~/.claude/settings.json
{
  "env": {
    "ENABLE_TOOL_SEARCH": "true"
  }
}

# or allow tool search in ~/.bashrc
export ENABLE_TOOL_SEARCH=true
```

### Choice Two - Tavily:

> when TAVILY_API_KEY is set in env

## 3. SubAgent - back run & tool call agent and swap file output

### 3.1 Auto Creat SubAgent

<table align="center">
  <tr>
    <td><img src="assets/subagent/sub_agent1" width="100%"></td>
    <td><img src="assets/subagent/sub_agent2_background" width="100%"></td>
    <td><img src="assets/subagent/subagent_backcontext" width="100%"></td>
  </tr>
</table>

### 3.2 Tool Agent Call Chains and Swap File Context

<table align="center">
  <tr>
    <td><img src="assets/subagent/subagent_toolcall_chain1" width="100%"></td>
    <td><img src="assets/subagent/subagent_toolcall_chain2" width="100%"></td>
    <td><img src="assets/subagent/subagent_toolcall_chain3" width="100%"></td>
  </tr>
</table>

## 4. Auto Dream

<div align="center">
  <img src="assets/auto_dream.png" alt="VersperAI">
</div>

```bash
# set auto-dream config
nvim ~/.claude/settings.json

{
  "autoMemoryEnabled": true,
  "autoDreamEnabled": true
}

# ● Improved 1 memory fold
# ⎿ user_profile.md
# cd ~/.claude/projects
```

## 5. Telegram - Interactive Config

```bash
# On startup, the CLI runs silently in the background, maintains a persistent Telegram connection, and listens for messages.
# start VersperClaw Cli
./cli-dev

# enter it into the cli input field and interactive configuration parameters
/telegram
```

## 6. Auto Compact

```bash
# set env in ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "57344",
    "CLAUDE_CODE_MAX_CONTEXT_TOKENS": "61440"
  }
}

# or via bash set env
echo 'export CLAUDE_CODE_AUTO_COMPACT_WINDOW=57344' >> ~/.bashrc
echo 'export CLAUDE_CODE_MAX_CONTEXT_TOKENS=61440' >> ~/.bashrc

# effective = 108K - effectiveContextWindow - used for auto-compact summary
# threshold = 95K - autoCompactThreshold - buffer to avoid failed
```

# Legacy Python Version

> Demos dev/python

## 1. Auto Scientific Research & evolve code and write ccf/sci & checkpoint

<table align="center">
  <tr>
    <td><img src="assets/legacy/paper.gif"/></td>
    <td><img src="assets/legacy/versper.gif"/></td>
  </tr>
</table>

## 2. WebToolAgent

<table align="center">
  <tr>
    <td align="center"><b>Web Search</b></td>
    <td align="center"><b>Deep Search</b></td>
    <td align="center"><b>Live Chrome Control</b></td>
  </tr>
  <tr>
    <td><img src="assets/legacy/versperclaw1.jpg" width="100%"></td>
    <td><img src="assets/legacy/versperclaw2.jpg" width="100%"></td>
    <td><img src="assets/legacy/control_browser_use_gemini.jpg" width="100%"></td>
  </tr>
</table>

## 3. Gateway - WeXin, Telegram and so on

```bash
# telegram, wechat and whatsapp
versper setup gateway

# then start listen
versper gateway
```

```bash
# Source install
git clone -b dev/python https://github.com/versperai/VersperClaw.git

# If you want check out the have been legacyed python version code, just switch to the dev/python branch

# make sure you have installed uv and creat .venv via uv venv
uv pip install -r requirements.txt # or uv sync
source .venv/bin/activate
uv pip install -e .

# use codex, openrouter, or claude remote model via api
versper setup
```

```bash
# if use vllm or llama.cpp in local model for inference 
# for example use llama.cpp
llama-server \
  --model unsloth/Qwen3.5-4B-GGUF/Qwen3.5-4B-UD-Q4_K_XL.gguf \
  --mmproj unsloth/Qwen3.5-4B-GGUF/mmproj-F16.gguf \
  --seed 3407 \
  --temp 1.0 \
  --top-p 0.95 \
  --min-p 0.01 \
  --top-k 40 \
  -c 49152 \
  --port 8001 \
  --chat-template-kwargs '{"enable_thinking":true}' \
  --host 0.0.0.0

# check model name and pass inference
curl http://localhost:8001/v1/models

curl http://localhost:8001/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen",
    "messages": [
      {"role": "user", "content": "hello"}
    ]
  }'

cd ~/.versper && nvim config.yaml
# model:
#  api_key: sk-no-key-required
#  base_url: http://localhost:8001/v1
#  default: unsloth/Qwen3.5-4B-GGUF
#  provider: custom
```

```bash
versper doctor # make sure all checks passed
```

## 4. Add-on - mcp dependency and env

```bash
if ban mcp in ~/.versper/.env:
export VERSPER_BROWSER_USE_MCP=0
```

```bash
# live chrome control
npm install -g chrome-devtools-mcp@latest
npm install -g agent-browser@latest

# make sure you have installed chrome
google-chrome-stable

# fill it in the search bar and click the box
chrome://inspect/#remote-debugging

# check chrome connect
versper
/browser status
```