CheetahClaws

CheetahClaws (Nano Claude Code) : A Fast, Easy-to-Use, Production-Ready, Python-Native Personal AI Assistant for Any Model, Inspired by OpenClaw and Claude Code, Built to Work for You Autonomously 24/7

Website · Brief Intro · Issue · The newest source of Claude Code

Quick Install

curl -fsSL https://raw.githubusercontent.com/SafeRL-Lab/cheetahclaws/main/scripts/install.sh | bash

After installation:

source ~/.zshrc     # macOS
# or: source ~/.bashrc   # Linux
cheetahclaws        # start chatting!

Other install methods: pip install | uv install | run from source | full details

🔥🔥🔥 News (Pacific Time)

May 10, 2026 (latest, v3.05.79): Web Chat UI session organization (folders, drag-drop, ChatGPT-style active-folder context, batch select + export, resizable sidebar) + headless-bridges slash handler (#84 follow-up: Telegram/Slack/WeChat /help/monitor/model/status now respond in Docker/--web) + stale-session reaper crash fix + #111 slash duplicate fix + --web --model persistence. Details: docs/news.md.
May 10, 2026: Web Chat UI fixes — slash commands no longer reply twice; --web --model X actually applies the model (#111). Details: docs/news.md.
May 10, 2026: Small-context local models survive large workloads — 4-part fix: ctx cap, auto-fanout, stagnation-stop, output paths under ~/.cheetahclaws/. Details: docs/news.md.
May 9, 2026: fix/agentic-on-every-model branch — make every model produce useful work + make /brainstorm an actual adversarial debate (9 commits, 269 new tests). Details: docs/news.md.
May 8, 2026: Agent-OS layer (cc_kernel/) reaches v1.0 — 27 RFCs shipped, 1771 tests passing, zero regressions on the legacy REPL/bridges path.
May 8, 2026: F-2/F-3 follow-ups + CI unblock (feature/fix-f2).
May 8, 2026 (v3.05.78): Research lab Phase A — autonomous multi-day research; WeChat smart-reply + /draft semi-auto reply; reliability + UX hardening across the lab pipeline.
May 7, 2026 (v3.05.77): MCP HTTP/SSE transport + OAuth 2.0 PKCE, .env loader, ANTHROPIC_ENDPOINT corporate-proxy override, AskUserQuestion UI polish (#88, #89)
May 5, 2026: Telegram bridge file round-trip + cross-channel pickable permission prompts (#84)
May 3, 2026: Research Lab — autonomous multi-agent paper writing with sandboxed experiments + web UI.
May 2, 2026: Daemon foundation lands (#80) — cheetahclaws serve + cheetahclaws daemon {status, stop, logs, rotate-token} are real.
May 2, 2026: Docker chat UI assets 404 follow-up (#73) — _WEB_DIR resolves via importlib.resources.files("web") so editable & non-editable installs both find static files; package-data widened to ship full web/static/ subtree. Details: docs/news.md.
Apr 30, 2026: Docker / home-server support (#73)
Apr 24, 2026: Support Deepseek V4 models, multi-model prompt adaptation
Apr 20, 2026 (v3.05.76): Research pipeline — 20 sources across academia/tech/finance/social/web + cross-platform attention heat table, publication trend sparkline, notable-citer analysis, entity extraction, multi-query expansion, side-by-side compare, saved reports, weekly trend tracking via /monitor, one-click /ssj wizard. Also including Chinese platforms: Zhihu (知乎) · Bilibili (B站) · Weibo (微博) · Rednote (小红书).
Apr 18, 2026 (v3.05.75): External plugin discovery via CHEETAHCLAWS_PLUGIN_PATH + safer dependency management; tool-history integrity fix for OpenAI-compatible providers (DeepSeek et al.); end-to-end prompt-cache token tracking across providers with full checkpoint round-trip
Apr 16, 2026 (v3.05.74): Web UI production hardening — persistence, multi-user auth, ops endpoints, JS module split, pytest suite

For more news, see here

CheetahClaws

CheetahClaws: A Lightweight and Easy-to-Use Python Reimplementation of Claude Code Supporting Any Model, such as Claude, GPT, Gemini, Kimi, Qwen, Zhipu, DeepSeek, MiniMax, and local open-source models via Ollama or any OpenAI-compatible endpoint.

Content

Why CheetahClaws
CheetahClaws vs OpenClaw
Features
Supported Models
Installation
Usage: Closed-Source API Models
Usage: Open-Source Models (Local)
Model Name Format
Trading Agent (multi-agent analysis, backtesting, memory)
Web UI (chat interface, settings, API endpoints)
Documentation (guides for all features)
Contributing
FAQ
Citation

Demos

Interactive terminal recordings (animated SVG — plays inline, no click needed)

_{Code review: profile a slow Python function, switch to local Ollama, apply the fix — 11× faster}

Task Excution

Web UI: Browser Chat — Sidebar, Tool Cards, Approval Prompts, Markdown Streaming

Brainstorm Mode: Multi-Agent Brainstorm

Proactive Mode: Autonomous Agent

SSJ Mode (Simple and Smart Job Mode): Power Menu Workflow

Telegram Bridge: Control cheetahclaws from Your Phone

WeChat Bridge: Control cheetahclaws from WeChat (微信)

Slack Bridge: Control cheetahclaws from Slack

Autonomous Trading Agent

Why CheetahClaws

Claude Code is a powerful, production-grade AI coding assistant — but its source code is a compiled, 12 MB TypeScript/Node.js bundle (~1,300 files, ~283K lines). It is tightly coupled to the Anthropic API, hard to modify, and impossible to run against a local or alternative model.

CheetahClaws reimplements the same core loop in ~40K lines of readable Python, keeping everything you need and dropping what you don't. See here for more detailed analysis (CheetahClaws v3.03), English version and Chinese version

At a glance

Dimension	Claude Code (TypeScript)	CheetahClaws (Python)
Language	TypeScript + React/Ink	Python 3.8+
Source files	~1,332 TS/TSX files	~85 Python files
Lines of code	~283K	~40K
Built-in tools	44+	27
Slash commands	88	36
Voice input	Proprietary Anthropic WebSocket (OAuth required)	Local Whisper / OpenAI API — works offline, no subscription
Model providers	Anthropic only	8+ (Anthropic · OpenAI · Gemini · Kimi · Qwen · DeepSeek · MiniMax · Ollama · …)
Local models	No	Yes — Ollama, LM Studio, vLLM, any OpenAI-compatible endpoint
Build step required	Yes (Bun + esbuild)	No — run directly with `python cheetahclaws.py` (or install to use `cheetahclaws`)
Runtime extensibility	Closed (compile-time)	Open — `register_tool()` at runtime, Markdown skills, git plugins
Task dependency graph	No	Yes — `blocks` / `blocked_by` edges in `task/` package

Where Claude Code wins

UI quality — React/Ink component tree with streaming rendering, fine-grained diff visualization, and dialog systems.
Tool breadth — 44 tools including RemoteTrigger, EnterWorktree, and more UI-integrated tools.
Enterprise features — MDM-managed config, team permission sync, OAuth, keychain storage, GrowthBook feature flags.
AI-driven memory extraction — extractMemories service proactively extracts knowledge from conversations without explicit tool calls.
Production reliability — single distributable cli.js, comprehensive test coverage, version-locked releases.

Where CheetahClaws wins

Multi-provider — switch between Claude, GPT-4o, Gemini 2.5 Pro, DeepSeek, Qwen, MiniMax, or a local Llama model with --model or /model — no recompile needed.
Local model support — run entirely offline with Ollama, LM Studio, or any vLLM-hosted model.
Readable source — the full agent loop is 174 lines (agent.py). Any Python developer can read, fork, and extend it in minutes.
Zero build — pip install -r requirements.txt and you're running. Changes take effect immediately.
Dynamic extensibility — register new tools at runtime with register_tool(ToolDef(...)), install skill packs from git URLs, or wire in any MCP server.
Task dependency graph — TaskCreate / TaskUpdate support blocks / blocked_by edges for structured multi-step planning (not available in Claude Code).
Two-layer context compression — rule-based snip + AI summarization, configurable via preserve_last_n_turns.
Notebook editing — NotebookEdit directly manipulates .ipynb JSON (replace/insert/delete cells) with no kernel required.
Diagnostics without LSP server — GetDiagnostics chains pyright → mypy → flake8 → py_compile for Python and tsc/shellcheck for other languages, with zero configuration.
Offline voice input — /voice records via sounddevice/arecord/SoX, transcribes with local faster-whisper (no API key, no subscription), and auto-submits. Keyterms from your git branch and project files boost coding-term accuracy.
Cloud session sync — /cloudsave backs up conversations to private GitHub Gists with zero extra dependencies; restore any past session on any machine with /cloudsave load <id>.
SSJ Developer Mode — /ssj opens a persistent power menu with 10 workflow shortcuts: Brainstorm → TODO → Worker pipeline, expert debate, code review, README generation, commit helper, and more. Stays open between actions; supports /command passthrough.
Telegram Bot Bridge — /telegram <token> <chat_id> turns cheetahclaws into a Telegram bot: receive user messages, run the model, and send back responses — all from your phone. Slash commands pass through, and a typing indicator keeps the chat feeling live.
WeChat Bridge — /wechat login authenticates with WeChat via a QR code scan (the same iLink Bot API used by the official WeixinClawBot / openclaw-weixin plugin), then starts a long-poll bridge. Slash command passthrough, interactive menu routing, typing indicator, session auto-recovery, and per-peer context_token management all work out of the box.
Slack Bridge — /slack <xoxb-token> <channel_id> connects cheetahclaws to a Slack channel using the Slack Web API (stdlib only — no slack_sdk required). Polls conversations.history every 2 seconds; replies update an in-place "Thinking…" placeholder. Slash command passthrough, interactive menu routing, and auto-start on launch.
Worker command — /worker auto-implements pending tasks from brainstorm_outputs/todo_list.txt, marks each one done after completion, and supports task selection by number (e.g. 1,4,6).
Force quit — 3× Ctrl+C within 2 seconds triggers immediate os._exit(1), unblocking any frozen I/O.
Proactive background monitoring — /proactive 5m activates a sentinel daemon that wakes the agent automatically after a period of inactivity, enabling continuous monitoring loops, scheduled checks, or trading bots without user prompts.
Rich Live streaming rendering — When rich is installed, responses stream as live-updating Markdown in place (no duplicate raw text), with clean tool-call interleaving.
Native Ollama reasoning — Local reasoning models (deepseek-r1, qwen3, gemma4) stream their <think> tokens directly to the terminal via ThinkingChunk events; enable with /verbose and /thinking.
Native Ollama vision — /image [prompt] captures the clipboard and sends it to local vision models (llava, gemma4, llama3.2-vision) via Ollama's native image API. No cloud required.
Built-in Web UI — --web launches a production-ready browser interface: multi-user accounts (bcrypt + JWT), SQLite-backed session history that survives restarts, rich Chat UI at /chat with streaming messages, tool cards, permission approval, sidebar session CRUD + search + markdown export, light/dark/system theme, settings panel with per-provider API keys. Full xterm.js PTY terminal at / keeps 100% CLI parity. Ops endpoints (/health, /metrics) + structured JSON logs + 21 pytest end-to-end tests. Nine tiny vanilla-JS modules under web/static/js/ — no Node.js, no React, no build step. cheetahclaws --web auto-picks a free port if 8080 is taken.
Reliable multi-line paste — Bracketed Paste Mode (ESC[?2004h) collects any pasted text — code blocks, multi-paragraph prompts, long diffs — as a single turn with zero latency and no blank-line artifacts.
Rich Tab completion — Tab after / shows all commands with one-line descriptions and subcommand hints; subcommand Tab-complete works for /mcp, /plugin, /tasks, /cloudsave, and more.
Checkpoint & rewind — /checkpoint lists all auto-snapshots of conversation + file state; /checkpoint <id> rewinds both files and history to any earlier point in the session.
Plan mode — /plan <desc> (or the EnterPlanMode tool) puts Claude into a structured read-only analysis phase; only the plan file is writable. Claude writes a detailed plan, then /plan done restores full write permissions for implementation.

CheetahClaws vs OpenClaw

OpenClaw is another popular open-source AI assistant built on TypeScript/Node.js. The two projects have different primary goals — here is how they compare.

At a glance

Dimension	OpenClaw (TypeScript)	CheetahClaws (Python)
Language	TypeScript + Node.js	Python 3.8+
Source files	~10,349 TS/JS files	~85 Python files
Lines of code	~245K	~12K
Primary focus	Personal life assistant across messaging channels	AI coding assistant / developer tool
Architecture	Always-on Gateway daemon + companion apps	Zero-install terminal REPL
Messaging channels	20+ (WhatsApp · Telegram · Slack · Discord · Signal · iMessage · Matrix · WeChat · …)	Terminal + Telegram bridge + WeChat bridge (iLink) + Slack bridge (Web API)
Model providers	Multiple (cloud-first)	7+ including full local support (Ollama · vLLM · LM Studio · …)
Local / offline models	Limited	Full — Ollama, vLLM, any OpenAI-compatible endpoint
Voice	Wake word · PTT · Talk Mode (macOS/iOS/Android)	Offline Whisper STT (local, no API key)
Code editing tools	Browser control, Canvas workspace	Read · Write · Edit · Bash · Glob · Grep · NotebookEdit · GetDiagnostics
Build step required	Yes (`pnpm install` + daemon setup)	No — `pip install` and run
Mobile companion	macOS menu bar + iOS/Android apps	—
Live Canvas / UI	Yes (A2UI agent-driven visual workspace)	—
MCP support	—	Yes (stdio/SSE/HTTP)
Runtime extensibility	Skills platform (bundled/managed/workspace)	`register_tool()` at runtime, MCP, git plugins, Markdown skills
Hackability	Large codebase (245K lines), harder to modify	~12K lines — full agent loop visible in one file

Where OpenClaw wins

Omni-channel inbox — connects to 20+ messaging platforms (WhatsApp, Signal, iMessage, Discord, Teams, Matrix, WeChat…); users interact from wherever they already are.
Always-on daemon — Gateway runs as a background service (launchd/systemd); no terminal required for day-to-day use.
Mobile-first — macOS menu bar, iOS Voice Wake / Talk Mode, Android camera/screen recording — feels like a native app, not a CLI tool.
Live Canvas — agent-driven visual workspace rendered in the browser; supports A2UI push/eval/snapshot.
Browser automation — dedicated Chrome/Chromium profile with snapshot, actions, and upload tools.
Production reliability — versioned npm releases, comprehensive CI, onboarding wizard, openclaw doctor diagnostics.

Where CheetahClaws wins

Coding toolset — Read/Write/Edit/Bash/Glob/Grep/NotebookEdit/GetDiagnostics are purpose-built for software development; CheetahClaws understands diffs, file trees, and code structure.
True local model support — full Ollama/vLLM/LM Studio integration with streaming, tool-calling, and vision — no cloud required.
8+ model providers — switch between Claude, GPT-4o, Gemini, DeepSeek, Qwen, MiniMax, and local models with a single --model flag.
Hackable in minutes — 12K lines of readable Python; the entire agent loop is in agent.py; extend with register_tool() at runtime without rebuilding.
Zero setup — pip install cheetahclaws and run cheetahclaws; no daemon, no pairing, no onboarding wizard.
MCP support — connect any MCP server (stdio/SSE/HTTP); tools auto-registered.
SSJ Developer Mode — /ssj power menu chains Brainstorm → TODO → Worker → Debate in a persistent interactive session; automates entire dev workflows.
Offline voice — /voice transcribes locally with faster-whisper; no subscription, no OAuth, works without internet.
Session cloud sync — /cloudsave backs up full conversations to private GitHub Gists with zero extra dependencies.

When to choose which

If you want…	Use
A personal assistant you can message on WhatsApp/Signal/Discord	OpenClaw
An AI coding assistant in your terminal	CheetahClaws
Full offline / local model support	CheetahClaws
A mobile-friendly always-on experience	OpenClaw
To read and modify the source in an afternoon	CheetahClaws
Browser automation and a visual Canvas	OpenClaw
Multi-provider LLM switching without rebuilding	CheetahClaws

Key design differences

Agent loop — CheetahClaws uses a Python generator that yields typed events (TextChunk, ToolStart, ToolEnd, TurnDone). The entire loop is visible in one file, making it easy to add hooks, custom renderers, or logging.

Tool registration — every tool is a ToolDef(name, schema, func, read_only, concurrent_safe) dataclass. Any module can call register_tool() at import time; MCP servers, plugins, and skills all use the same mechanism.

Context compression

	Claude Code	CheetahClaws
Trigger	Exact token count	`len / 3.5` estimate, fires at 70 %
Layer 1	—	Snip: truncate old tool outputs (no API cost)
Layer 2	AI summarization	AI summarization of older turns
Control	System-managed	`preserve_last_n_turns` parameter

Memory — Claude Code's extractMemories service has the model proactively surface facts. CheetahClaws's memory/ package is tool-driven: the model calls MemorySave explicitly, which is more predictable and auditable. Each memory now carries confidence, source, last_used_at, and conflict_group metadata; search re-ranks by confidence × recency; and /memory consolidate offers a manual consolidation pass without silently modifying memories in the background.

Who should use CheetahClaws

Developers who want to use a local or non-Anthropic model as their coding assistant.
Researchers studying how agentic coding assistants work — the entire system fits in one screen.
Teams who need a hackable baseline to add proprietary tools, custom permission policies, or specialised agent types.
Anyone who wants Claude Code-style productivity without a Node.js build chain.

Features

Feature	Details
Multi-provider	Anthropic · OpenAI · Gemini · Kimi · Qwen · Zhipu · DeepSeek · MiniMax · Ollama · LM Studio · Custom endpoint
Interactive REPL	readline history, Tab-complete slash commands with descriptions + subcommand hints; Bracketed Paste Mode for reliable multi-line paste
Agent loop	Streaming API + automatic tool-use loop
27 built-in tools	Read · Write · Edit · Bash · Glob · Grep · WebFetch · WebSearch · NotebookEdit · GetDiagnostics · MemorySave · MemoryDelete · MemorySearch · MemoryList · Agent · SendMessage · CheckAgentResult · ListAgentTasks · ListAgentTypes · Skill · SkillList · AskUserQuestion · TaskCreate/Update/Get/List · SleepTimer · EnterPlanMode · ExitPlanMode · (MCP + plugin tools auto-added at startup)
MCP integration	Connect any MCP server (stdio/SSE/HTTP), tools auto-registered and callable by Claude
Plugin system	Install/uninstall/enable/disable/update plugins from git URLs or local paths; multi-scope (user/project); recommendation engine
AskUserQuestion	Claude can pause and ask the user a clarifying question mid-task, with optional numbered choices
Task management	TaskCreate/Update/Get/List tools; sequential IDs; dependency edges; metadata; persisted to `.cheetahclaws/tasks.json`; `/tasks` REPL command
Diff view	Git-style red/green diff display for Edit and Write
Context compression	Auto-compact long conversations to stay within model limits. Four cooperating layers: (1) per-call dynamic max_tokens cap based on actual prompt size — `input + output + 1024 safety ≤ ctx`; (2) per-model context-window registry for Qwen 2.5/3, Llama 3.x, Mistral/Mixtral, Phi, Gemma, DeepSeek local variants — small-context local models no longer fall through to a stale 128k default; (3) two-layer compaction (snip + AI summarize) at 70% threshold; (4) auto-fanout when a single tool output exceeds 0.4 × ctx — split + parallel sub-LLM map calls + reduce. Custom-endpoint live `/v1/models` lookup backfills the real `max_model_len`.
Auto-fanout	When a single tool result (Read on a 6.6 MB PDF, Grep over a giant tree, WebFetch of a long article) is too big to fit in the model's context window, instead of letting the next API call overflow, split it into chunks at paragraph boundaries with token overlap, dispatch parallel sub-LLM map calls (default cap 5 subagents), merge with one reduce call. Substitutes the merged summary in the conversation history. Transparent UX: `[Auto-fanout: <Tool> returned ~N chars → dispatching K parallel sub-summaries]`. Configurable: `auto_fanout_enabled` / `_threshold` / `_max_subagents` / `_chunk_overlap_tokens`. Critical for 32 K local models reading large source material.
Persistent memory	Dual-scope memory (user + project) with 4 types, confidence/source metadata, conflict detection, recency-weighted search, `last_used_at` tracking, and `/memory consolidate` for auto-extraction
Multi-agent	Spawn typed sub-agents (coder/reviewer/researcher/…), git worktree isolation, background mode
Skills	Built-in `/commit` · `/review` + custom markdown skills with argument substitution and fork/inline execution
Plugin tools	Register custom tools via `tool_registry.py`
Permission system	`auto` / `accept-all` / `manual` / `plan` modes
Checkpoints	Auto-snapshot conversation + file state after each turn; `/checkpoint` to list, `/checkpoint <id>` to rewind; `/rewind` alias; 100-snapshot sliding window
Plan mode	`/plan <desc>` enters read-only analysis mode; Claude writes only to the plan file; `EnterPlanMode` / `ExitPlanMode` agent tools for autonomous planning
37 slash commands	`/model` · `/config` · `/save` · `/cost` · `/memory` · `/skills` · `/agents` · `/voice` · `/proactive` · `/checkpoint` · `/plan` · `/compact` · `/status` · `/doctor` · `/theme` · …
Console themes	`/theme` lists 15 curated palettes (default · dracula · nord · gruvbox · solarized · tokyo-night · catppuccin · matrix · synthwave · midnight · ocean · monokai · cheetah · mono · none); each row shows a live `info / ok / warn / err` swatch in the theme's own colors. `/theme <name>` applies and persists the choice — also drives Rich's Markdown code-block style.
Voice input	Record → transcribe → auto-submit. Backends: `sounddevice` / `arecord` / SoX + `faster-whisper` / `openai-whisper` / OpenAI API. Works fully offline.
Brainstorm	`/brainstorm [topic]` generates N expert personas suited to the topic (2–100, default 5, chosen interactively), runs an iterative debate, saves results to `brainstorm_outputs/`, and synthesizes a Master Plan + auto-generates `brainstorm_outputs/todo_list.txt`.
SSJ Developer Mode	`/ssj` opens a persistent interactive power menu with 15 shortcuts: Brainstorm, TODO viewer, Worker, Expert Debate, Propose, Review, Readme, Commit, Scan, Promote, Video factory, TTS factory, Monitor, Trading, Agent. Stays open between actions; `/command` passthrough supported.
Trading agent v3.1	Automatic candidate discovery: `/trading discover all` scans an S&P 100 universe and surfaces tickers from four orthogonal sources — SEC EDGAR Form 4 insider clusters, recent ≥10% earnings beats with post-print drift, momentum-quality factor intersection, leading sector ETFs' top holdings — then merges with a cross-source confluence bonus. `/trading rank` composite-ranks candidates by factor + discovery + calibration tilt. `/trading anomaly` flags unusual volume / price gaps / vol regime spikes. `/trading monitor scan --notify telegram slack wechat` runs anomaly + stop-loss + earnings + new-insider-filing detection and dispatches alerts to bridges. Single-name analysis: `/trading analyze <SYMBOL>` runs a multi-agent pipeline (Bull/Bear → Judge → Risk Panel → PM) with macro / earnings / insider / sentiment / trends / book context auto-injected. `/trading review` runs incremental HOLD/ADD/TRIM/EXIT debate on existing positions. Autonomous mode: `/trading manage start hundred 100` creates a virtual `$100` portfolio that the agent allocates + rebalances via mean-variance optimization (`step` / `report`). Persistent paper-trade tracker → `/trading calibration` answers "is the agent any good?" with hit-rate by confidence + t-stat vs zero. Hard risk verifier enforces position / sector / stop / earnings-blackout caps. `/trading walkforward` does honest OOS rolling-chunk backtesting. `/trading ml train` builds a LightGBM stacker. Broker abstraction: `PaperBroker` works out of the box, `IBKRBroker` stub for `pip install ib_insync` + IB Gateway. Supports US/HK/A-share stocks and 20+ cryptos.
Monitor	`/monitor` (no args → wizard) subscribes to AI-monitored topics on a schedule and pushes reports to Telegram/Slack/console. Topics: `ai_research` (arxiv), `stock_<TICKER>`, `crypto_<SYMBOL>`, `world_news` (Reuters/BBC/AP), `custom:<query>`. Schedules: 15m to weekly. Background scheduler daemon with `/monitor start/stop/status`.
Research (multi-source)	`/research <topic>` fans out to 20 sources in parallel and synthesizes a brief with inline citations, a cross-platform attention heat table, top-mentioned entities (models / benchmarks / orgs / people), and a 12-month publication trend sparkline: arXiv · Semantic Scholar · OpenAlex · HuggingFace Papers · alphaXiv · Google Scholar · HackerNews · GitHub · Reddit · StackOverflow · Google News · Polymarket · SEC EDGAR · Tavily · Brave · Twitter/X · 知乎 Zhihu · B站 Bilibili · 微博 Weibo · 小红书 Xiaohongshu. Supports `--range 30d\|6m\|1y\|…` / `--since YYYY-MM-DD` / `--until YYYY-MM-DD` — each source translates to its native date filter. `--citations` surfaces "Notable citing authors" with ≥10k total citations. `--expand` asks the model for 2-6 sibling subqueries and merges their results for broader coverage. `/research compare "A" vs "B" [vs "C"]` produces a side-by-side comparative brief with `[A-N]`/`[B-N]`/`[C-N]`-prefixed citations. Every run auto-saves to `~/.cheetahclaws/research_reports/`; `/reports list\|open\|delete\|path` to browse, `--save-as PATH` to export. Weekly trend tracking: `/subscribe research:<topic> weekly` (or `/ssj` → `17. Trend Track`) re-runs the whole pipeline automatically and pushes digests to Telegram / Slack / console. One-click wizard via `/ssj` → `16. Research` / `17. Trend Track` / `18. Reports`. 13/20 sources zero-config; 7 optional (Tavily · Brave · Twitter · Zhihu · Weibo · Xiaohongshu · Google Scholar). See docs/guides/research.md.
Autonomous Agents	`/agent` (no args → wizard) launches autonomous background agent loops driven by Markdown task templates. 4 built-in templates: `research_assistant`, `auto_bug_fixer`, `paper_writer`, `auto_coder`. Iteration summaries pushed via bridge. Custom templates: drop a `.md` file into `~/.cheetahclaws/agent_templates/`. Output paths under `~/.cheetahclaws/`: relative output filenames (e.g. `research_notes.md`) are auto-resolved to `~/.cheetahclaws/agents/<name>/output/<filename>` so generated artifacts stay out of your CWD; absolute paths pass through unchanged. The Summary block + post-start info show the resolved absolute path in green so you always know where the file landed. Stagnation-stop: when the model emits the same summary N iterations in a row (default 3, whitespace-normalized), the loop stops with a clear notification instead of burning thousands of API calls — controlled by `auto_agent_dup_summary_limit` (0 disables).
Remote Control job queue	All three bridges (Telegram/Slack/WeChat) maintain a per-bridge FIFO job queue when the AI is busy. `!jobs` / `!j` — dashboard; `!job <id>` — detail; `!retry <id>` — re-run a failed job; `!cancel [id]` — stop current job. Tool step tracking with `on_tool_start`/`on_tool_end` hooks. Persistent log at `~/.cheetahclaws/jobs.json`.
Worker	`/worker [task#s]` reads `brainstorm_outputs/todo_list.txt`, implements each pending task with a dedicated model prompt, and marks it done (`- [x]`). Supports task selection (`/worker 1,4,6`), custom path (`--path`), and worker count limit (`--workers`). Detects and redirects accidental brainstorm `.md` paths.
Telegram bridge	`/telegram <token> <chat_id>` starts a bot bridge: receive messages from Telegram, run the model, and reply — all from your phone. Typing indicator, slash command passthrough (including interactive menus), and auto-start on launch if configured.
WeChat bridge	`/wechat login` authenticates via QR code scan (same as WeixinClawBot / openclaw-weixin plugin), then starts the iLink long-poll bridge. `context_token` echoed per peer, typing indicator, slash command passthrough, session expiry auto-recovery. Credentials saved for auto-start on next launch.
Slack bridge	`/slack <xoxb-token> <channel_id>` connects to a Slack channel via the Web API (no external packages). Polls `conversations.history` every 2 s; replies update an in-place "Thinking…" placeholder. Slash command passthrough, interactive menu routing, auth validation on start, auto-start on next launch.
Video factory	`/video [topic]` runs the full AI video pipeline: story generation (active model) → TTS narration (Edge/Gemini/ElevenLabs) → AI images (Gemini Web free or placeholders) → subtitle burn (Whisper) → FFmpeg assembly → final `.mp4`. 10 viral content niches, landscape or short format, zero-cost path available.
TTS factory	`/tts` interactive wizard: AI writes script (or paste your own) → synthesize to MP3 in any voice style (narrator, newsreader, storyteller, ASMR, motivational, documentary, children, podcast, meditation, custom). Engine auto-selects: Gemini TTS → ElevenLabs → Edge TTS (always-free). CJK text auto-switches to a matching voice.
Vision input	`/image` (or `/img`) captures the clipboard image and sends it to any vision-capable model — Ollama (`llava`, `gemma4`, `llama3.2-vision`) via native format, or cloud models (GPT-4o, Gemini 2.0 Flash, …) via OpenAI `image_url` multipart format. Requires `pip install cheetahclaws[vision]`; Linux also needs `xclip`.
Tmux integration	11 tmux tools for direct terminal control: create sessions/windows/panes, send commands, capture output. Auto-detected; zero impact if tmux is absent. Enables long-running tasks that outlive Bash tool timeouts. Cross-platform (tmux on Unix, psmux on Windows).
Shell escape	Type `!command` in the REPL to execute any shell command directly without AI involvement (`!git status`, `!ls`, `!python --version`). Output prints inline.
Proactive monitoring	`/proactive [duration]` starts a background sentinel daemon; agent wakes automatically after inactivity, enabling continuous monitoring loops without user prompts
Force quit	3× Ctrl+C within 2 seconds triggers `os._exit(1)` — kills the process immediately regardless of blocking I/O
Rich Live streaming	When `rich` is installed, responses render as live-updating Markdown in place. Auto-disabled in SSH sessions to prevent repeated output; override with `/config rich_live=false`.
Context injection	Auto-loads `CLAUDE.md`, git status, cwd, persistent memory
Session persistence	Autosave on exit to `daily/YYYY-MM-DD/` (per-day limit) + `history.json` (master, all sessions) + `session_latest.json` (/resume); sessions include `session_id` and `saved_at` metadata; `/load` grouped by date
Cloud sync	`/cloudsave` syncs sessions to private GitHub Gists; auto-sync on exit; load from cloud by Gist ID. No new dependencies (stdlib `urllib`).
Extended Thinking	Toggle on/off for Claude models; native `<think>` block streaming for local Ollama reasoning models (deepseek-r1, qwen3, gemma4)
Cost tracking	Token usage + estimated USD cost
Non-interactive mode	`--print` flag for scripting / CI
Web UI	`--web` opens the browser. Multi-user accounts (bcrypt + JWT), SQLite-persisted history, session CRUD + markdown export, light/dark/system theme, `/health` + `/metrics`, auto-picks a free port if 8080 is busy. `pip install 'cheetahclaws[web]'`.

Supported Models

Closed-Source (API)

Provider	Model	Context	Strengths	API Key Env
Anthropic	`claude-opus-4-6`	200k	Most capable, best for complex reasoning	`ANTHROPIC_API_KEY`
Anthropic	`claude-sonnet-4-6`	200k	Balanced speed & quality	`ANTHROPIC_API_KEY`
Anthropic	`claude-haiku-4-5-20251001`	200k	Fast, cost-efficient	`ANTHROPIC_API_KEY`
OpenAI	`gpt-4o`	128k	Strong multimodal & coding	`OPENAI_API_KEY`
OpenAI	`gpt-4o-mini`	128k	Fast, cheap	`OPENAI_API_KEY`
OpenAI	`gpt-4.1`	128k	Latest GPT-4 generation	`OPENAI_API_KEY`
OpenAI	`gpt-4.1-mini`	128k	Fast GPT-4.1	`OPENAI_API_KEY`
OpenAI	`gpt-5`	128k	Next-gen flagship	`OPENAI_API_KEY`
OpenAI	`gpt-5-nano`	128k	Fastest GPT-5 variant	`OPENAI_API_KEY`
OpenAI	`gpt-5-mini`	128k	Balanced GPT-5 variant	`OPENAI_API_KEY`
OpenAI	`o4-mini`	200k	Fast reasoning	`OPENAI_API_KEY`
OpenAI	`o3`	200k	Strong reasoning	`OPENAI_API_KEY`
OpenAI	`o3-mini`	200k	Compact reasoning	`OPENAI_API_KEY`
OpenAI	`o1`	200k	Advanced reasoning	`OPENAI_API_KEY`
Google	`gemini-2.5-pro-preview-03-25`	1M	Long context, multimodal	`GEMINI_API_KEY`
Google	`gemini-2.0-flash`	1M	Fast, large context	`GEMINI_API_KEY`
Google	`gemini-1.5-pro`	2M	Largest context window	`GEMINI_API_KEY`
Moonshot (Kimi)	`moonshot-v1-8k`	8k	Chinese & English	`MOONSHOT_API_KEY`
Moonshot (Kimi)	`moonshot-v1-32k`	32k	Chinese & English	`MOONSHOT_API_KEY`
Moonshot (Kimi)	`moonshot-v1-128k`	128k	Long context	`MOONSHOT_API_KEY`
Alibaba (Qwen)	`qwen-max`	32k	Best Qwen quality	`DASHSCOPE_API_KEY`
Alibaba (Qwen)	`qwen-plus`	128k	Balanced	`DASHSCOPE_API_KEY`
Alibaba (Qwen)	`qwen-turbo`	1M	Fast, cheap	`DASHSCOPE_API_KEY`
Alibaba (Qwen)	`qwq-32b`	32k	Strong reasoning	`DASHSCOPE_API_KEY`
Zhipu (GLM)	`glm-4-plus`	128k	Best GLM quality	`ZHIPU_API_KEY`
Zhipu (GLM)	`glm-4`	128k	General purpose	`ZHIPU_API_KEY`
Zhipu (GLM)	`glm-4-flash`	128k	Free tier available	`ZHIPU_API_KEY`
DeepSeek	`deepseek-chat`	64k	Strong coding	`DEEPSEEK_API_KEY`
DeepSeek	`deepseek-reasoner`	64k	Chain-of-thought reasoning	`DEEPSEEK_API_KEY`
MiniMax	`MiniMax-Text-01`	1M	Long context, strong reasoning	`MINIMAX_API_KEY`
MiniMax	`MiniMax-VL-01`	1M	Vision + language	`MINIMAX_API_KEY`
MiniMax	`abab6.5s-chat`	256k	Fast, cost-efficient	`MINIMAX_API_KEY`
MiniMax	`abab6.5-chat`	256k	Balanced quality	`MINIMAX_API_KEY`

Open-Source (Local via Ollama)

Model	Size	Strengths	Pull Command
`llama3.3`	70B	General purpose, strong reasoning	`ollama pull llama3.3`
`llama3.2`	3B / 11B	Lightweight	`ollama pull llama3.2`
`qwen2.5-coder`	7B / 32B	Best for coding tasks	`ollama pull qwen2.5-coder`
`qwen2.5`	7B / 72B	Chinese & English	`ollama pull qwen2.5`
`deepseek-r1`	7B–70B	Reasoning, math	`ollama pull deepseek-r1`
`deepseek-coder-v2`	16B	Coding	`ollama pull deepseek-coder-v2`
`mistral`	7B	Fast, efficient	`ollama pull mistral`
`mixtral`	8x7B	Strong MoE model	`ollama pull mixtral`
`phi4`	14B	Microsoft, strong reasoning	`ollama pull phi4`
`gemma3`	4B / 12B / 27B	Google open model	`ollama pull gemma3`
`codellama`	7B / 34B	Code generation	`ollama pull codellama`
`llava`	7B / 13B	Vision — image understanding	`ollama pull llava`
`llama3.2-vision`	11B	Vision — multimodal reasoning	`ollama pull llama3.2-vision`

Note: Tool calling requires a model that supports function calling. Recommended local models: qwen2.5-coder, llama3.3, mistral, phi4.

OpenAI newer models (gpt-5 / o3 / o4 family): These models require max_completion_tokens instead of the legacy max_tokens parameter. CheetahClaws handles this automatically — no configuration needed.

Reasoning models: deepseek-r1, qwen3, and gemma4 stream native <think> blocks. Enable with /verbose and /thinking to see thoughts in the terminal. Note: models fed a large system prompt (like cheetahclaws's 25 tool schemas) may suppress their thinking phase to avoid breaking the expected JSON format — this is model behavior, not a bug.

Installation

Quick Install (one command)

curl -fsSL https://raw.githubusercontent.com/SafeRL-Lab/cheetahclaws/main/scripts/install.sh | bash

Or

pip install cheetahclaws

Works on Linux, macOS, WSL2, and Android (Termux). The installer handles everything: checks Python 3.10+, clones the repo, installs via pip, and adds cheetahclaws to your PATH.

After installation:

source ~/.zshrc     # macOS (zsh)
# or: source ~/.bashrc   # Linux (bash)
cheetahclaws        # start chatting!

First run will guide you through setup (pick provider, set API key). Or run cheetahclaws --setup anytime.

Windows: Native Windows is not supported. Install WSL2 and run the command above inside WSL.

Android / Termux: The installer auto-detects Termux and skips incompatible optional dependencies. Manual install: pkg install python git && pip install cheetahclaws.

Alternative: install with `pip`

git clone https://github.com/SafeRL-Lab/cheetahclaws.git
cd cheetahclaws
pip install .

After that, cheetahclaws is available as a global command:

cheetahclaws                        # start REPL
cheetahclaws --model gpt-4o         # choose a model
cheetahclaws -p "explain this"      # non-interactive
cheetahclaws --setup                # re-run setup wizard

To update after pulling new code:

cd cheetahclaws
git pull
pip install --force-reinstall .

Upgrading from a pre-2026-05-08 install? If you see ModuleNotFoundError: No module named 'prompts' (or modular.trading.discover, etc.) at startup, your existing wheel is from before the issue #97 packaging fix and is missing several sub-packages. pip install --force-reinstall . rebuilds and ships them all — see #97 for the root-cause writeup.

Optional extras

pip install ".[voice]"              # voice input (sounddevice)
pip install ".[vision]"             # clipboard image capture (Pillow)
pip install ".[autosuggest]"        # typing-time slash command autosuggest (prompt_toolkit)
pip install ".[browser]"            # headless browser for JS-rendered pages (playwright)
pip install ".[files]"              # PDF + Excel reading (pymupdf, openpyxl)
pip install ".[ocr]"                # image OCR (pytesseract, Pillow)
pip install ".[trading]"            # trading agent (yfinance, rank-bm25)
pip install ".[all]"                # everything above

Note: After installing [browser], run playwright install chromium to download the browser binary.

Alternative: install with `uv`

uv installs cheetahclaws into an isolated environment and puts it on your PATH:

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and install with all optional dependencies (voice, vision, autosuggest, browser, files, OCR, trading etc.)
git clone https://github.com/SafeRL-Lab/cheetahclaws.git
cd cheetahclaws
uv tool install ".[all]"

Prefer a minimal install? Use uv tool install . (core only) and add extras later, e.g. uv tool install ".[voice,vision,autosuggest]" --reinstall.

To update: uv tool install ".[all]" --reinstall

To uninstall: uv tool uninstall cheetahclaws

Alternative: run directly from source (no install)

git clone https://github.com/SafeRL-Lab/cheetahclaws.git
cd cheetahclaws
pip install -r requirements.txt
python cheetahclaws.py

This is useful for development — changes take effect immediately without reinstalling.

Usage: Closed-Source API Models

Anthropic Claude

Get your API key at console.anthropic.com.

export ANTHROPIC_API_KEY=sk-ant-api03-...

# Default model (claude-opus-4-6)
cheetahclaws

# Choose a specific model
cheetahclaws --model claude-sonnet-4-6
cheetahclaws --model claude-haiku-4-5-20251001

# Enable Extended Thinking
cheetahclaws --model claude-opus-4-6 --thinking --verbose

OpenAI GPT

Get your API key at platform.openai.com.

export OPENAI_API_KEY=sk-...

cheetahclaws --model gpt-4o
cheetahclaws --model gpt-4o-mini
cheetahclaws --model gpt-4.1-mini
cheetahclaws --model o3-mini

Google Gemini

Get your API key at aistudio.google.com.

export GEMINI_API_KEY=AIza...

cheetahclaws --model gemini/gemini-3-flash-preview
cheetahclaws --model gemini/gemini-3.1-pro-preview

Kimi (Moonshot AI)

Get your API key at platform.moonshot.cn.

export MOONSHOT_API_KEY=sk-...

cheetahclaws --model kimi/moonshot-v1-32k
cheetahclaws --model kimi/moonshot-v1-128k

Qwen (Alibaba DashScope)

Get your API key at dashscope.aliyun.com.

export DASHSCOPE_API_KEY=sk-...

cheetahclaws --model qwen/Qwen3.5-Plus
cheetahclaws --model qwen/Qwen3-MAX
cheetahclaws --model qwen/Qwen3.5-Flash

Zhipu GLM

Get your API key at open.bigmodel.cn.

export ZHIPU_API_KEY=...

cheetahclaws --model zhipu/glm-4-plus
cheetahclaws --model zhipu/glm-4-flash   # free tier

DeepSeek

Get your API key at platform.deepseek.com.

export DEEPSEEK_API_KEY=sk-...

cheetahclaws --model deepseek/deepseek-chat
cheetahclaws --model deepseek/deepseek-reasoner

MiniMax

Get your API key at platform.minimaxi.chat.

export MINIMAX_API_KEY=...

cheetahclaws --model minimax/MiniMax-Text-01
cheetahclaws --model minimax/MiniMax-VL-01
cheetahclaws --model minimax/abab6.5s-chat

Usage: Open-Source Models (Local)

Option A — Ollama (Recommended)

Ollama runs models locally with zero configuration. No API key required.

Step 1: Install Ollama

# macOS / Linux
curl -fsSL https://ollama.com/install.sh | sh

# Or download from https://ollama.com/download

Step 2: Pull a model

# Best for coding (recommended)
ollama pull qwen2.5-coder          # 4.7 GB (7B)
ollama pull qwen2.5-coder:32b      # 19 GB (32B)

# General purpose
ollama pull llama3.3               # 42 GB (70B)
ollama pull llama3.2               # 2.0 GB (3B)

# Reasoning
ollama pull deepseek-r1            # 4.7 GB (7B)
ollama pull deepseek-r1:32b        # 19 GB (32B)

# Other
ollama pull phi4                   # 9.1 GB (14B)
ollama pull mistral                # 4.1 GB (7B)

Step 3: Start Ollama server (runs automatically on macOS; on Linux run manually)

ollama serve     # starts on http://localhost:11434

Step 4: Run cheetahclaws

cheetahclaws --model ollama/qwen2.5-coder
cheetahclaws --model ollama/llama3.3
cheetahclaws --model ollama/deepseek-r1

Or

python cheetahclaws.py --model ollama/qwen2.5-coder
python cheetahclaws.py --model ollama/llama3.3
python cheetahclaws.py --model ollama/deepseek-r1
python cheetahclaws.py --model ollama/qwen3.5:35b

List your locally available models:

ollama list

Then use any model from the list:

cheetahclaws --model ollama/<model-name>

Option B — LM Studio

LM Studio provides a GUI to download and run models, with a built-in OpenAI-compatible server.

Step 1: Download LM Studio and install it.

Step 2: Search and download a model inside LM Studio (GGUF format).

Step 3: Go to Local Server tab → click Start Server (default port: 1234).

Step 4:

cheetahclaws --model lmstudio/<model-name>
# e.g.:
cheetahclaws --model lmstudio/phi-4-GGUF
cheetahclaws --model lmstudio/qwen2.5-coder-7b

The model name should match what LM Studio shows in the server status bar.

Option C — vLLM / Self-Hosted OpenAI-Compatible Server

For self-hosted inference servers (vLLM, TGI, llama.cpp server, etc.) that expose an OpenAI-compatible API:

Quick Start for option C: Step 1: Start vllm:

CUDA_VISIBLE_DEVICES=7 python -m vllm.entrypoints.openai.api_server \
     --model Qwen/Qwen2.5-Coder-7B-Instruct \
     --host 0.0.0.0 \
     --port 8000 \
     --enable-auto-tool-choice \
     --tool-call-parser hermes

Step 2: Start cheetahclaws：

  export CUSTOM_BASE_URL=http://localhost:8000/v1
  export CUSTOM_API_KEY=none
  cheetahclaws --model custom/Qwen/Qwen2.5-Coder-7B-Instruct

# Example: vLLM serving Qwen2.5-Coder-32B
python -m vllm.entrypoints.openai.api_server \
    --model Qwen/Qwen2.5-Coder-32B-Instruct \
    --port 8000 \
    --enable-auto-tool-choice \
    --tool-call-parser hermes

# Then run cheetahclaws pointing to your server:
cheetahclaws

Inside the REPL:

/config custom_base_url=http://localhost:8000/v1
/config custom_api_key=token-abc123    # skip if no auth
/model custom/Qwen2.5-Coder-32B-Instruct

Or set via environment:

export CUSTOM_BASE_URL=http://localhost:8000/v1
export CUSTOM_API_KEY=token-abc123

cheetahclaws --model custom/Qwen2.5-Coder-32B-Instruct

For a remote GPU server:

/config custom_base_url=http://192.168.1.100:8000/v1
/model custom/your-model-name

Using vLLM with the Web UI

--web --model <name> now persists the model into ~/.cheetahclaws/config.json before the server starts, so the Chat UI hits the right endpoint on the very first request:

export CUSTOM_BASE_URL=http://localhost:8000/v1
export CUSTOM_API_KEY=dummy            # vLLM doesn't validate but the OpenAI SDK requires non-empty
cheetahclaws --web --no-auth --port 8080 --model custom/qwen2.5-72b

If you skip --model, the Chat UI uses whatever was previously saved (it will not silently fall back to a default). Switch models on the fly from the Chat UI's Settings panel or with /model custom/<name> in the message box. The model name after custom/ must match the vLLM --served-model-name exactly.

Model Name Format

Three equivalent formats are supported:

# 1. Auto-detect by prefix (works for well-known models)
cheetahclaws --model gpt-4o
cheetahclaws --model gemini-2.0-flash
cheetahclaws --model deepseek-chat

# 2. Explicit provider prefix with slash
cheetahclaws --model ollama/qwen2.5-coder
cheetahclaws --model kimi/moonshot-v1-128k

# 3. Explicit provider prefix with colon (also works)
cheetahclaws --model kimi:moonshot-v1-32k
cheetahclaws --model qwen:qwen-max

Auto-detection rules:

Model prefix	Detected provider
`claude-`	anthropic
`gpt-`, `o1`, `o3`	openai
`gemini-`	gemini
`moonshot-`, `kimi-`	kimi
`qwen`, `qwq-`	qwen
`glm-`	zhipu
`deepseek-`	deepseek
`MiniMax-`, `minimax-`, `abab`	minimax
`llama`, `mistral`, `phi`, `gemma`, `mixtral`, `codellama`	ollama

Trading Agent

CheetahClaws includes a built-in AI-powered trading analysis and backtesting module. Install trading dependencies:

pip install "cheetahclaws[trading]"

Multi-agent analysis

/trading analyze NVDA

Runs a 5-phase pipeline: data collection (technical indicators, fundamentals, news) → Bull/Bear researcher debate → research judge recommendation → risk management panel (aggressive / conservative / neutral) → portfolio manager final decision with a 5-tier rating: BUY / OVERWEIGHT / HOLD / UNDERWEIGHT / SELL.

Each agent uses BM25 memory to recall similar past situations and learns from outcomes via post-trade reflection.

Backtesting

/trading backtest AAPL dual_ma           # single strategy
/trading backtest TSLA                   # AI picks best strategy

4 built-in strategies: dual_ma (SMA crossover), rsi_mean_reversion, bollinger_breakout, macd_crossover. Engines for US/HK equities and crypto. Reports Sharpe, Sortino, Calmar, max drawdown, win rate, profit factor.

SSJ integration

/ssj → 14. 📈 Trading opens a guided sub-menu:

Option	Action
a. Quick Analyze	Full multi-agent analysis for any symbol
b. Backtest	Pick strategy or compare all 4
c. Price Check	Current price + key metrics
d. Indicators	11 technical indicators report
e. Trading Bot	Autonomous multi-symbol analysis
f. History	Past trading decisions
g. Memory	Trading memory status

Supported markets

US stocks (AAPL), HK stocks (0700.HK), A-shares (000001.SZ), crypto (BTC, ETH, + 18 more). Data sources with automatic fallback chains — no API keys required.

Full guide: docs/guides/trading.md

Web UI

A production-ready browser interface with real user accounts, SQLite-backed session history, and ops endpoints — bundled Python stdlib HTTP server plus nine small vanilla-JS modules, no Node.js / React / build step.

Install and start

pip install 'cheetahclaws[web]'              # pulls sqlalchemy + bcrypt + PyJWT

cheetahclaws --web                           # auto-picks a free port (tries 8080 first)
cheetahclaws --web --port 9000               # bind exactly :9000 (fails loudly if taken)
cheetahclaws --web --host 0.0.0.0            # open to the local network
cheetahclaws --web --no-auth                 # skip login (localhost dev only)

On first visit to http://localhost:<port>/chat, the UI routes you to a registration form — the first account becomes admin. Subsequent visits show Sign in. Credentials: bcrypt-hashed password + 7-day JWT cookie (ccjwt, HttpOnly, SameSite=Strict). The JWT signing key is persisted to ~/.cheetahclaws/web_secret so logins survive restarts.

Chat UI (`/chat`)

Feature	Details
Streaming chat	WebSocket for live prompts + SSE for long-running slash commands
Persistent history	Every session + message lives in SQLite (`~/.cheetahclaws/web.db`). Server restart does not lose state.
Sidebar session management	Title auto-titled from first user message, relative time ("12m ago"), message count, busy dot, client-side search, right-click menu (Rename / Export Markdown / Move to / Delete)
Folders + ChatGPT-style Projects	`+ Folder` button creates per-user folders; drag a session onto a folder header (or right-click → Move to ▸) to file it; click a folder name to "enter" — `+ New` and direct-typing then auto-drop the new session into that folder, with a `Chat · in <Folder>` topbar breadcrumb. Deleting a folder reparents its sessions to "Ungrouped" rather than deleting them.
Batch operations	"Select" button enters multi-select mode (checkboxes, Select all respects the search filter); a footer action bar batch-deletes (single confirm + total-message count) or batch-exports as a single combined Markdown (`chats-N-sessions.md`).
Resizable sidebar	Drag the 4-px divider between the sidebar and the chat pane (200–600 px clamp); double-click resets; width persists across reloads.
Cross-user isolation	Each user only sees their own sessions and folders — enforced at DB query and in-memory cache
Tool cards	Collapsible cards show tool name, inputs, outputs, status (running / done / denied)
Permission approval	Inline Allow / Deny buttons
45+ slash commands	`/status`, `/model`, `/brainstorm`, `/ssj`, `/plan`, `/telegram`, `/wechat`, `/slack`, `/voice`, `/image`, etc.
Settings panel	Model picker (11 providers), permission mode, thinking/verbose toggles, per-provider API key entry, quick-action buttons
Theme	Light default, `@media (prefers-color-scheme: dark)` follows the OS automatically. Toggle cycles system → light → dark → system; choice stored in localStorage, no flash-of-wrong-theme on first paint
Feature dashboard	Welcome screen with 4×6 clickable cards — Core, Agent Features, Session & Memory, Multi-Model, Development Tools, Bridges, Multi-Modal Media
Export as Markdown	`GET /api/sessions/{id}/export` downloads the conversation with all tool calls
Favicon	Leaping-cheetah icon served at `/favicon.ico` and `/static/favicon.png`

PTY Terminal (`/`)

Full xterm.js terminal — still there, still 100% CLI parity. Uses the same one-time generated password (printed on startup) — separate from the chat JWT flow.

API shape

Browser ──→ /chat                ──→ 9 JS modules load from /static/js/*.js
        ──→ /api/auth/login      ──→ bcrypt + JWT cookie
        ──→ /api/prompt (POST)   ──→ persists to SQLite, fans events out
        ──→ /api/events (WS)     ──→ real-time text_chunk / tool_* / permission_*
        ──→ /api/sessions/*      ──→ list / get / rename / delete / export
                                       + batch_delete / batch_export
                                       + {id}/folder (move to folder)
        ──→ /api/folders         ──→ list / create / rename / delete folders

        ──→ /                     ──→ xterm.js PTY (password-gated)
        ──→ /health               ──→ { ok, db, uptime_s }        (unauthenticated)
        ──→ /metrics              ──→ Prometheus text              (unauthenticated)

Endpoint	Method	Purpose
`/api/auth/bootstrap`	GET	Any users registered yet?
`/api/auth/register`	POST	Create user (first one is admin)
`/api/auth/login`	POST	Verify bcrypt + issue JWT cookie
`/api/auth/logout`	POST	Clear cookie
`/api/auth/whoami`	GET	Current user
`/api/prompt`	POST	Submit prompt / slash command (inline JSON or SSE for long commands)
`/api/events`	WS	Structured event stream for a session
`/api/approve`	POST	Respond to a permission request
`/api/sessions`	GET	List this user's sessions
`/api/sessions/{id}`	GET / PATCH / DELETE	Detail / rename / remove
`/api/sessions/{id}/export`	GET	Download conversation as Markdown
`/api/config`	GET / PATCH	Read or update session config
`/api/models`	GET	Providers + models + API-key status
`/health`	GET	Liveness + DB probe
`/metrics`	GET	Prometheus counters (`requests_total`, `auth_logins_failed`, `users_total`, ...)

Observability

Structured logs — one JSON line per HTTP response on stderr, e.g.

{"ts":1776368300.054,"level":"info","logger":"web.server","msg":"req","method":"POST","path":"/api/prompt","status":200,"dur_ms":650,"user_id":1}

Tune with CHEETAHCLAWS_LOG_LEVEL=DEBUG|INFO|WARNING.

Metrics — point Prometheus at /metrics. Counters increment inside _send_http and the auth routes.
Tests — pytest tests/test_web_api.py runs 21 end-to-end HTTP tests against a real server in ~5 seconds (no mocks, real SQLite, real bcrypt, real JWT).

Full guide: docs/guides/web-ui.md

Docker / Home Server

For headless deployments (home server with local Ollama, cloud VM, container host) the repo ships a Dockerfile and docker-compose.yml. The web UI plus any configured Telegram / WeChat / Slack bridge run together in a single container:

cp .env.example .env       # set UID/GID and any cloud API keys
mkdir -p workspace data
docker compose up -d --build
# open http://<host-ip>:8080/chat

The container reaches an Ollama instance running on the host via host.docker.internal:11434. Mount ./workspace into the container and share it over Samba to access the agent's working files from your phone or other PCs.

Full guide: docs/guides/docker.md

Documentation

Detailed guides have been moved to docs/guides/ to keep this README focused. Click any link below:

Guide	What's Inside
Web UI	Chat UI, PTY terminal, API endpoints, settings panel, model switching, dark/light theme, SSE streaming, session management, authentication
Docker / Home Server	Dockerfile + docker-compose for home-server deployments: web UI + bridges in one container, host Ollama via `host.docker.internal`, workspace bind-mount, Samba sharing
Reference	CLI, 36+ commands, 33 built-in tools (incl. WebBrowse, ReadEmail, SendEmail, ReadPDF, ReadImage, ReadSpreadsheet), session search, auxiliary model, error classification, prompt injection detection, tool cache, parallel tools
Extensions	Memory system, Skills, Sub-Agents, MCP servers, Plugin system, Monitor subscriptions, Autonomous Agents
Bridges	Telegram, WeChat, Slack setup and remote control from your phone
Voice & Video	Voice input (offline Whisper), Video Content Factory, TTS Content Factory
Trading	Multi-agent analysis (Bull/Bear debate, Risk panel, PM), backtesting (4 strategies, equity + crypto engines), BM25 memory, data fallback chains, SSJ integration
Advanced	Brainstorm, SSJ Developer Mode, Tmux, Proactive monitoring, Checkpoints, Plan mode, Session management, Cloud sync
Recipes	12 step-by-step examples: code review, Telegram remote control, autonomous research, bug fix, brainstorm, session search, browse web pages, email, PDF/Excel analysis, and more
Plugin Authoring	Build your own plugin: tools, commands, skills, MCP servers, publishing checklist
Example Plugin	Copy-and-edit starter template with working tools, commands, and skills
Research Lab	`[engine v0]` `/lab start <topic>` — autonomous multi-agent paper writing with 9 specialised agents (PI, Engineer, Reviewer × 3, …), sandboxed Python experiment execution, citation verification (arXiv / Semantic Scholar / CrossRef), reviewer-author iteration. CLI + web UI. Targets arXiv-grade preprint quality
Daemon RFC	Design note: IPC, permission routing, local auth — contract for the daemon foundation (issue #68, PR #74)
Daemon Spike Notes	Reference scaffolding (`cc_daemon/`) that validates the RFC 0001 contract end-to-end (PR #77 → reverted → re-landed via #81). `cheetahclaws spike-daemon ...` preserved as a backward-compat alias
Daemon Foundation Roadmap	F-1..F-9 PR breakdown. F-1 (`cheetahclaws serve` + `cheetahclaws daemon {status, stop, logs, rotate-token}`) merged via PR #80
Agent OS overview	The `cc_kernel/` layer: process table, capability model, quota ledger, scheduler, mailbox, AgentFS, observability, tool inventory, streaming, RFC 0003-0032 index
Agent-OS RFC index	All 27 design notes (0003-0032) — capability/sandbox/scheduler/mailbox/AgentFS/observability/tool-dispatch/streaming, each with acceptance criteria
Contributing	Project structure, architecture guide, PR checklist

Quick Reference

cheetahclaws [OPTIONS] [PROMPT]

Options:
  -p, --print          Non-interactive: run prompt and exit
  -m, --model MODEL    Override model (e.g. gpt-4o, ollama/llama3.3)
  --accept-all         Auto-approve all operations (no permission prompts)
  --verbose            Show thinking blocks and per-turn token counts
  --thinking           Enable Extended Thinking (Claude only)
  --web                Start web server (Chat UI + PTY terminal in browser)
  --port PORT          Web server port (default: 8080)
  --host HOST          Web server host (default: 127.0.0.1)
  --no-auth            Disable web password (local use only)
  --version            Print version and exit
  -h, --help           Show help

Examples:

# Interactive REPL with default model
cheetahclaws

# Switch model at startup
cheetahclaws --model gpt-4o
cheetahclaws -m ollama/deepseek-r1:32b

# Non-interactive / scripting
cheetahclaws --print "Write a Python fibonacci function"
cheetahclaws -p "Explain the Rust borrow checker in 3 sentences" -m gemini/gemini-2.0-flash

# CI / automation (no permission prompts)
cheetahclaws --accept-all --print "Initialize a Python project with pyproject.toml"

# Debug mode (see tokens + thinking)
cheetahclaws --thinking --verbose

# Web UI (browser-based chat + terminal)
cheetahclaws --web
cheetahclaws --web --port 8008 --no-auth

See Reference Guide for the full list of 37+ slash commands, tool descriptions, and configuration options.

Contributing

We welcome contributions! See the Contributing Guide for project architecture, code conventions, and PR checklist.

Quick start for contributors:

git clone https://github.com/SafeRL-Lab/cheetahclaws.git
cd cheetahclaws
pip install -r requirements.txt
pip install pytest
python -m pytest tests/ -x -q       # 341+ tests should pass
python cheetahclaws.py               # run the REPL

Building a plugin? See the Plugin Authoring Guide and the example plugin template.

FAQ

Q: How do I add an MCP server?

Option 1 — via REPL (stdio server):

/mcp add git uvx mcp-server-git

Option 2 — create .mcp.json in your project:

{
  "mcpServers": {
    "git": {"type": "stdio", "command": "uvx", "args": ["mcp-server-git"]}
  }
}

Then run /mcp reload or restart. Use /mcp to check connection status.

Q: An MCP server is showing an error. How do I debug it?

/mcp                    # shows error message per server
/mcp reload git         # try reconnecting

If the server uses stdio, make sure the command is in your $PATH:

which uvx               # should print a path
uvx mcp-server-git      # run manually to see errors

Q: Can I use MCP servers that require authentication?

For HTTP/SSE servers with a Bearer token:

{
  "mcpServers": {
    "my-api": {
      "type": "sse",
      "url": "https://myserver.example.com/sse",
      "headers": {"Authorization": "Bearer sk-my-token"}
    }
  }
}

For stdio servers with env-based auth:

{
  "mcpServers": {
    "brave": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-brave-search"],
      "env": {"BRAVE_API_KEY": "your-key"}
    }
  }
}

Q: Tool calls don't work with my local Ollama model.

Not all models support function calling. Use one of the recommended tool-calling models: qwen2.5-coder, llama3.3, mistral, or phi4.

ollama pull qwen2.5-coder
cheetahclaws --model ollama/qwen2.5-coder

Q: How do I connect to a remote GPU server running vLLM?

/config custom_base_url=http://your-server-ip:8000/v1
/config custom_api_key=your-token
/model custom/your-model-name

Q: How do I check my API cost?

/cost

  Input tokens:  3,421
  Output tokens:   892
  Est. cost:     $0.0648 USD

Q: Can I use multiple API keys in the same session?

Yes. Set all the keys you need upfront (via env vars or /config). Then switch models freely — each call uses the key for the active provider.

Q: How do I make a model available across all projects?

Add keys to ~/.bashrc or ~/.zshrc. Set the default model in ~/.cheetahclaws/config.json:

{ "model": "claude-sonnet-4-6" }

Q: Qwen / Zhipu returns garbled text.

Ensure your DASHSCOPE_API_KEY / ZHIPU_API_KEY is correct and the account has sufficient quota. Both providers use UTF-8 and handle Chinese well.

Q: Can I pipe input to cheetahclaws?

echo "Explain this file" | cheetahclaws --print --accept-all
cat error.log | cheetahclaws -p "What is causing this error?"

Q: How do I run it as a CLI tool from anywhere?

Use uv tool install — it creates an isolated environment and puts cheetahclaws on your PATH:

cd cheetahclaws
uv tool install ".[all]"

After that, just run cheetahclaws from any directory. To update after pulling changes, run uv tool install ".[all]" --reinstall. For a minimal install, use uv tool install . and add extras as needed.

Q: How do I set up voice input?

# Minimal setup (local, offline, no API key):
pip install sounddevice faster-whisper numpy

# Then in the REPL:
/voice status          # verify backends are detected
/voice                 # speak your prompt

On first use, faster-whisper downloads the base model (~150 MB) automatically. Use a larger model for better accuracy: export NANO_CLAUDE_WHISPER_MODEL=small

Q: Voice input transcribes my words wrong (misses coding terms).

The keyterm booster already injects coding vocabulary from your git branch and project files. For persistent domain terms, put them in a .cheetahclaws/voice_keyterms.txt file (one term per line) — this is checked automatically on each recording.

Q: Can I use voice input in Chinese / Japanese / other languages?

Yes. Set the language before recording:

/voice lang zh    # Mandarin Chinese
/voice lang ja    # Japanese
/voice lang auto  # reset to auto-detect (default)

Whisper supports 99 languages. auto detection works well but explicit codes improve accuracy for short utterances.

Citation

If you find the repository useful, please cite the study

@article{cheetahclaws2026,
  title={CheetahClaws: An Extensible, Python-Native Agent System for Autonomous Multi-Model Workflows},
  author={CheetahClaws Team},
  journal={github},
  year={2026}
}

Name		Name	Last commit message	Last commit date
Latest commit History 613 Commits
.github/workflows		.github/workflows
agent_templates		agent_templates
bridges		bridges
cc_daemon		cc_daemon
cc_kernel		cc_kernel
cc_mcp		cc_mcp
checkpoint		checkpoint
commands		commands
demos		demos
docs		docs
examples		examples
memory		memory
modular		modular
monitor		monitor
multi_agent		multi_agent
plugin		plugin
prompts		prompts
research		research
scripts		scripts
skill		skill
task		task
tests		tests
tools		tools
ui		ui
video		video
voice		voice
web		web
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
agent.py		agent.py
agent_runner.py		agent_runner.py
auxiliary.py		auxiliary.py
bootstrap.py		bootstrap.py
cc_config.py		cc_config.py
cheetahclaws.py		cheetahclaws.py
circuit_breaker.py		circuit_breaker.py
cloudsave.py		cloudsave.py
compaction.py		compaction.py
context.py		context.py
demo.py		demo.py
docker-compose.yml		docker-compose.yml
error_classifier.py		error_classifier.py
health.py		health.py
jobs.py		jobs.py
logging_utils.py		logging_utils.py
providers.py		providers.py
pyproject.toml		pyproject.toml
quota.py		quota.py
requirements.txt		requirements.txt
runtime.py		runtime.py
session_store.py		session_store.py
skills.py		skills.py
subagent.py		subagent.py
tmux_tools.py		tmux_tools.py
tool_registry.py		tool_registry.py

Folders and files

Latest commit

History

Repository files navigation

CheetahClaws (Nano Claude Code) : A Fast, Easy-to-Use, Production-Ready, Python-Native Personal AI Assistant for Any Model, Inspired by OpenClaw and Claude Code, Built to Work for You Autonomously 24/7

Quick Install

🔥🔥🔥 News (Pacific Time)

CheetahClaws

Content

Demos

Interactive terminal recordings (animated SVG — plays inline, no click needed)

Why CheetahClaws

At a glance

Where Claude Code wins

Where CheetahClaws wins

CheetahClaws vs OpenClaw

At a glance

Where OpenClaw wins

Where CheetahClaws wins

When to choose which

Key design differences

Who should use CheetahClaws

Features

Supported Models

Closed-Source (API)

Open-Source (Local via Ollama)

Installation

Quick Install (one command)

Alternative: install with pip

Optional extras

Alternative: install with uv

Alternative: run directly from source (no install)

Usage: Closed-Source API Models

Anthropic Claude

OpenAI GPT

Google Gemini

Kimi (Moonshot AI)

Qwen (Alibaba DashScope)

Zhipu GLM

DeepSeek

MiniMax

Usage: Open-Source Models (Local)

Option A — Ollama (Recommended)

Option B — LM Studio

Option C — vLLM / Self-Hosted OpenAI-Compatible Server

Using vLLM with the Web UI

Model Name Format

Trading Agent

Multi-agent analysis

Backtesting

SSJ integration

Supported markets

Web UI

Install and start

Chat UI (/chat)

PTY Terminal (/)

API shape

Observability

Docker / Home Server

Documentation

Quick Reference

Contributing

FAQ

Citation

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Alternative: install with `pip`

Alternative: install with `uv`

Chat UI (`/chat`)

PTY Terminal (`/`)

Packages