VersperClaw: Not Only AI Assistant Code Agent

📢 News

• 2026-07-01 🗺️ LocationTool unlimited search — Amap places search now paginates (1000/page, up to 10000 results); Google Places uses next_page_token (up to 60); photo limits removed.
• 2026-06-22 🔊 Groq Whisper STT — CLI /voice now uses Groq Whisper API (cloud whisper-large-v3, no Python needed) and node-edge-tts for TTS, matching Friend's stack.
• 2026-06-21 🎙️ Groq Free STT — Friend voice input now supports Groq Whisper API as STT provider; TypeScript-only, no Python subprocess required.
• 2026-06-21 🖥️ Friend Desktop — /friend start launches a Tauri desktop VRM companion app with full-screen mode, real-time TTS/STT, and inter-process communication.
• 2026-06-21 🎤 Microphone Fix — Resolved Microphone access denied in WebKitGTK; switched to arecord/parecord subprocess audio capture.
• 2026-06-20 🤖 /friend Command — In-process VRM companion service: SSE broadcast, voice capture (push-to-talk + streaming), Edge TTS / Qwen TTS, and persona generation from VRM screenshot.
• 2026-06-19 📋 /release-notes — New command to display version release notes and what's new.
• 2026-06-15 🎯 Goal Tracking — New /goal command with prompt input footsider and lastline display for real-time goal tracking.
• 2026-06-15 🖼️ WebSearch Image Preview — WebSearch markdown now displays inline image links natively.
• 2026-06-15 🔊 Feishu Voice — Feishu integration now supports both VoxCPM and Edge-TTS voice synthesis.
• 2026-06-15 📝 Feishu Markdown — Feishu bot messages render with full markdown styling.
• 2026-06-15 🤖 Feishu Connect — New Feishu (飞书) bot integration with message relay and voice TTS.
• 2026-06-14 📱 Desktop Provider Sync — Desktop now syncs provider config from TUI; model list uses sidecar proxy to avoid CORS.
• 2026-06-14 🛡️ NVIDIA Sidecar Fix — Use sidecar for NVIDIA, direct fetch for OpenRouter/OpenCode.
• 2026-06-13 🗣️ Voice CN/TW — Added Chinese (zh-CN) and Taiwanese (zh-TW) voice support for TTS.
• 2026-06-02 🤝 Agent Team — Multi-agent collaboration via Tmux backend with teammate layout manager, dynamic team scaling, and spawn utilities for coordinated task execution.
• 2026-06-01 🧩 SubAgent Swarm Topology — Dedicated Explore 🔍, Plan 📋, and Verification 🧪 subagents for autonomous multi-step task decomposition and execution.
• 2026-05-25 🤖 AI Friend on Desktop — Companion mode with real-time audio/video, avatar & background image upload, edge glow effect on transcript, and localStorage persistence.
• 2026-05-25 🖥️ Desktop app launched — Tauri-based native UI with sidebar, tabs, title bar, and session management. Subagent inherits parent class config. Branding updated to Versper AI.
• 2026-05-23 🧘 Added OpenCode Zen Provider — a new model provider for calm, focused AI interactions.
• 2026-05-22 🔧 Fixed OpenCode login flow and refined prompt identity for clearer agent behavior.
• 2026-05-08 🐛 Fixed model list not refreshing after /login opencode freemodel exit; subagent creation now works without API key in free mode.
• 2026-05-06 🚀 Added OpenCode as a free provider — includes GPT-5 Nano and Big Pickle 🥒 models, /model list with life-free model display, and auto-refresh. Introduced ctx_line context tracking with online persistence. Better collapsing fetch results and auto-compact documentation polish. Merged PR #6 for Tavily search backend migration.
• 2026-04-30 🔍 Added Tavily as optional search backend in WebSearchTool via PR #6.
• 2026-04-24 🧹 Cleaned up empty contributor docs.
• 2026-04-21 🛡️ Fixed auto-compact env in settings.json; VersperClaw now handles Ctrl+C resume gracefully.
• 2026-04-20 📝 Documented ToolSearch behavior and table formatting.
• 2026-04-19 📖 Described auto-dream and subagent features in README; punctuation and layout polish. Tagged v2.0.1 🏷️.
• 2026-04-18 💭 Snapshot auto-dream feature; ToolSearch now uses WebSearch under the hood.
• 2026-04-15 🌙 Auto Dream — AI autonomously reflects and builds internal memory. Fixed chatId overflow by migrating from Number to String.
• 2026-04-13 🧠 All tools allowed in auto mode without classifier; auto-compact triggers on context size exceeded; ToolSearch enabled by default for all providers; OpenRouter full model loading. Tagged v2.0.0 🏷️.
• 2026-04-12 ⚡ Live refresh typing status; WebFetch now supports shouldDefer for lazy loading; symbol links documented as usable everywhere.
• 2026-04-09 🎨 Major README overhaul — VersperAI branding with Banner & Logo, tabular layout, websearch/webfetch documentation, TypeScript main branch vs Python legacy explained. Tagged v2.0.0 🏷️.
• 2026-04-08 🌐 Full WebSearch toolchain — SearXNG integration, Jina AI websearch & fetch, WebFetch UI notes, build fix. Four search approaches landed in one day.
• 2026-04-07 🔍 Zero-search prototype; Python env removed; TLS-enabled web search working end-to-end.
• 2026-04-06 🛠️ Open ripgrep via USE_BUILTIN_RIPGREP=0; WebFetch UI notes; skill message renamed; WebSearch API error fixed.
• 2026-04-05 🤖 AutoMode — autonomous decision-making execution mode. /sandbox with sandbox-runtime @0.0.44. Project renamed to versperclaw. OpenRouter ↔ Local model switching, auto-refresh TUI, Telegram /login local model transition.
• 2026-04-04 📱 Telegram backend — /telegram command, interactive commands, message receiving in TUI, chatId overflow fixed. /buddy companion mode; recent activity in individual directories.
• 2026-04-03 🔄 Reborn as verspercode v0.1.0 — complete /login system (OpenRouter + local models), /model search & UI, free OpenRouter model auto-load, onboarding flow. Local model filesystem-based provider.

Earlier news

• 2026-04-01 🧹 Removed autoresearch, evolve modules, and Cursor scripts — streamlining toward v2. Tagged v1.0.0 🏷️.
• 2026-03-31 🖥️ CLI update for better terminal interaction.
• 2026-03-30 🐛 Fixed error type-in when using /resume session.
• 2026-03-29 🧠 Memory routing — route-runtime-long_term for persistent context. CLI shell split to <10K lines. Browser vision click/control fixes. Paper GIF in README; --paper API call optimization.
• 2026-03-28 📄 Academic paper pipeline — /evolve autonomous evolution, /compact context compression, LaTeX paper template, main.pdf compilation. Chrome-based research v1.0.
• 2026-03-27 🔬 Research workflow — /paper and /code commands, 4-step research + autoresearch, ANN vector index, hybrid retrieval with semantic cache, external memory, token-budgeted evidence pipeline, IncompleteRead retry, long-term index cache. Workflows engine, /resume session toggle, CLI UI refresh.
• 2026-03-26 🏗️ Configuration overhaul — YAML → JSON + .env + TOML. Clean config dir.
• 2026-03-24 🌐 Browser control — Chrome DevTools MCP integration, WeChat gateway, Telegram gateway. Setup wizard, README with demo GIF, version menu.
• 2026-03-22 🎉 Initial commit — versperclaw v0.1.0 born.

📦 Install

# 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 &&  bun run friend:build && ./VersperClaw

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

🚀 Quick Start

Important

If you no need auto-compact / dream / control context-window and websearch feature. you can no configuration anything

if you no need free local-websearch you can skip config searxng`` and just setTAVILY_API_KEY` in env

# Maximum_Context_Window = min(CLAUDE_CODE_MAX_CONTEXT_TOKENS, CLAUDE_CODE_AUTO_COMPACT_WINDOW) - 20000
# set 200k env in ~/.claude/settings.json or terminal
# the 20k is used to compact as buffer band
# set tool_search env
# set agentteam in tmux
{
  "env": {
    "USER_TYPE": "ant",
    "CLAUDE_CODE_MAX_CONTEXT_TOKENS": "200000",
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "200000",
    "ENABLE_TOOL_SEARCH": "true",
    "TAVILY_API_KEY": "",
    # "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "0", default 1 
    "teammateMode": "tmux", # or in-process
    "groqApiKey": "gsk_" # https://console.groq.com
    # map locationtool
    "AMAP_API_KEY": "b_",
    "GOOGLE_MAPS_API_KEY": "AI_"
  }

  # set auto-dream config
  "autoMemoryEnabled": true,
  "autoDreamEnabled": true,

  # stt-tts support zh-CN
  # TW girl voice
  "voiceLanguage": "zh-TW",
  "voiceTTSVoice": "zh-TW-HsiaoChenNeural"

  # CN girl voice
  "voiceLanguage": "zh-CN",
  "voiceTTSVoice": "zh-CN-XiaoxiaoNeural"
}

# Config SearXNG
# 1. docker configuration
# 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
# 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
# check in every browser
firefox http://localhost:8080

# test
HTTP_PROXY=http://127.0.0.1:8888 HTTPS_PROXY=http://127.0.0.1:8888 <commands>
mitmproxy -p 8888

# /voice
"voiceTTSVoice": "zh-TW-HsiaoChenNeural",
"voiceLanguage": "zh-TW",

# node-edge-tts
# local whisper-stt
uv venv
uv pip install faster-whisper edge-tts voxcpm

hf download Systran/faster-whisper-base \
  --local-dir ~/.cache/huggingface/hub/models--Systran--faster-whisper-base

✨ Features

Agent Team and View via Tmux

Auto Compact & Dream & SubAgent

🧠 Core Mechanisms of Cycle Long Run

• Auto Compact — Automatically optimizes and compresses historical context to bypass sequence length bottlenecks.
• Dream — Asynchronously distills operational data into long-term insights.

🗂️ SubAgent Swarm Topology

SubAgent Type	Core Responsibility
🛡️ General-Purpose	Orchestrates routing, high-level user interaction, and dispatching.
🔍 Explore	Conducts deep semantic search and autonomous tool discovery.
📋 Plan	Handles multi-step chain-of-thought strategy and task decomposition.
🧪 Verification	Executes automated runtime validation, assertion checks, and fault tolerance.

WebSearch & WebFetch Tools