English | 中文 | 한국어 | 日本語 | Français | Deutsch | Español | Português

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

• June 6, 2026 (latest, v3.5.82): macOS install reliably puts cheetahclaws on PATH, and local Ollama models that emit tool calls as text now actually execute them (two fixes from issue #131). (1) Install/PATH on macOS: the installer sources the dedicated venv it creates, which made the post-install command -v cheetahclaws check succeed inside the script's own shell — so it reported "on PATH" and skipped the entire rc-file step, leaving ~/.zshrc untouched and the binary unreachable in new terminals. It now symlinks only the cheetahclaws entry point into ~/.local/bin (pipx-style, so the venv's python/pip don't shadow yours), creates ~/.zshrc / .bash_profile if missing, and appends ~/.local/bin to PATH there — without trusting the venv-polluted command -v (scripts/install.sh). (2) Ollama tool calls: stream_ollama only read Ollama's structured message.tool_calls field, while the cloud path already recovers calls a model emits as text, so Qwen-coder / Gemma / Mistral over Ollama produced "tool-calling-style chat" that streamed as plain text and never ran — the model seemed to "just keep talking." stream_ollama now mirrors the cloud path's interceptor: it buffers from the first <tool_call> / <|tool_call|> / [TOOL_CALLS] marker (so raw markup never reaches the user) and parses it into real tool calls at end-of-stream (providers.py). Details: docs/guides/usage.md · docs/guides/faq.md · docs/news.md.
• June 5, 2026 (v3.5.82): User-controllable token/cost budgets — /budget 5ドル / /budget 200k / /budget daily 20ドル cap spend per session or per day, enforced before each model call; on hit the session auto-saves and you're shown how to /resume or raise the cap and continue (warns at ≥80%/95%; --budget sets it at startup). Details: docs/guides/features.md · docs/news.md.
• June 5, 2026: Adaptive Markdown streaming — live output stays correct on every device by auto-selecting a per-device tier (live in-place redraw on capable terminals incl. modern SSH emulators, append-only commit for SSH/Apple Terminal/pipes/CJK text so frames never duplicate, plain fallback); also ships a visual /context usage grid and a 1M context window for deepseek-v4-flash. Details: docs/guides/features.md · docs/news.md.
• June 4, 2026 (v3.05.81): Claude-Code-style quiet output hides per-tool execution and shows one summary line per turn (on by default), with a live spinner timer + token estimate and a ✻ Worked for... footer; /verbose overrides, toggle with /quiet. Details: docs/guides/features.md · docs/news.md.
• June 4, 2026: Context-window override — /config context_window=<N> sets the context length that drives the prompt %, /context, the compaction trigger, and the output cap consistently (distinct from max_tokens; read live, no restart). Details: docs/guides/reference.md · docs/news.md.
• June 4, 2026: Rich Live streaming keeps long responses live via a bounded tail window — redrawing only the most recent screenful and committing the full output when done, fixing duplicate/stale frames (builds on PR #133). Details: docs/guides/features.md · docs/news.md.
• May 31, 2026: QQ bot bridge — /qq connects cheetahclaws to QQ groups + C2C private chats via the official qq-botpy SDK (PR #121). Details: docs/guides/bridges.md · docs/news.md.
• May 12, 2026: Security hardening sweep — env-var bot tokens, web CSRF cookie, terminal session owner-binding, and plugin/MCP/filesystem sandboxing (two CRITICAL + HIGH rounds, 2347 tests green). Details: docs/guides/security.md · docs/news.md.
• May 12, 2026: Daemon foundation roadmap — all nine F-1...F-9 items landed: subprocess agent runners, on-crash restart policy, daemonized Telegram/Slack/WeChat bridges, and budget guardrails. Details: docs/news.md.

For more news, see here.

CheetahClaws: A Fast and Easy-to-Use Python native Agent Harness Infrastructure, 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.

• Why CheetahClaws
• CheetahClaws vs OpenClaw
• Features
• Supported Models
• Installation
• Usage: Closed-Source API Models
• Usage: Open-Source Models (Local)
• Model Name Format
• Trading Agent
• Web UI
• Documentation (guides for all features)
• Contributing · FAQ · Citation

More animated demos (code review, /research, /brainstorm, /lab, Telegram/WeChat/Slack bridges) live in docs/media/.

Claude Code is a powerful, production-grade AI coding assistant — but its source is a compiled ~12 MB TypeScript/Node bundle (~1,300 files, ~283K lines), 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 ~90K lines of readable Python — keeping what you need, dropping what you don't, and adding multi-provider + local-model support. Full comparison: docs/guides/comparison.md.

Where Claude Code wins: richer React/Ink UI, more built-in tools, enterprise features (MDM, team permission sync, OAuth/keychain), AI-driven memory extraction, single-binary production reliability.

Where CheetahClaws wins: any-model switching (--model//model, no recompile) incl. full local/offline support; a readable agent loop in one file (agent.py, ~740 lines); zero build; runtime tool registration + MCP + git plugins + Markdown skills; task dependency graph (blocks/blocked_by); two-layer context compression; offline voice; cloud session sync; bridges to Telegram/WeChat/Slack/QQ.

Who it's for: developers who want a local/non-Anthropic coding assistant, researchers studying how agentic assistants work, and teams who need a hackable baseline — without a Node.js build chain.

OpenClaw is another popular open-source assistant (TypeScript/Node). The two have different primary goals — OpenClaw is a personal life-assistant across messaging channels; CheetahClaws is a developer/coding tool.

Full comparison — both sides' wins + key design differences (agent loop, tool registration, context compression, memory): docs/guides/comparison.md.

Full feature reference — every row above with complete detail (context-compression layers, auto-fanout, 15 themes, the full Trading/Research/Agents writeups, ...): docs/guides/features.md.

litellm/ adapter: routes to 100+ providers behind one SDK — mainly for upstreams with awkward auth (Bedrock SigV4, Azure deployment routing, Vertex service-account JWTs). For plain OpenAI-shaped endpoints, prefer the zero-dependency custom/ adapter. Install with pip install ".[litellm]". See recipes.md.

Tool calling needs a function-calling model — recommended: qwen2.5-coder, llama3.3, mistral, phi4. Models that emit tool calls as text (<tool_call>...</tool_call>, [TOOL_CALLS]...) instead of Ollama's structured field are auto-recovered, so they execute tools out of the box rather than just chatting about it. Reasoning models (deepseek-r1, qwen3, gemma4) stream native <think> blocks; enable with /verbose + /thinking.

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) (Python 3.10+). First run guides you through provider + API-key setup; re-run anytime with cheetahclaws --setup.

Windows: native Windows is not supported — use WSL2. Android/Termux: pkg install python git && pip install cheetahclaws.

git clone https://github.com/SafeRL-Lab/cheetahclaws.git
cd cheetahclaws
pip install . # then: cheetahclaws
git pull && pip install --force-reinstall . # to update

pip install ".[voice]" # voice input (sounddevice + faster-whisper)
pip install ".[vision]" # clipboard image capture (Pillow)
pip install ".[autosuggest]"# typing-time slash autosuggest (prompt_toolkit)
pip install ".[browser]" # headless browser (playwright); then: playwright install chromium
pip install ".[files]" # PDF + Excel reading (pymupdf, openpyxl)
pip install ".[ocr]" # image OCR (pytesseract)
pip install ".[trading]" # trading agent (yfinance, rank-bm25)
pip install ".[qq]" # QQ bot bridge (qq-botpy)
pip install ".[litellm]" # AWS Bedrock / Azure / Vertex auth via litellm
pip install ".[all]" # everything above

git clone https://github.com/SafeRL-Lab/cheetahclaws.git && cd cheetahclaws
uv tool install ".[all]" # minimal: uv tool install .
uv tool install ".[all]" --reinstall # update · uv tool uninstall cheetahclaws

git clone https://github.com/SafeRL-Lab/cheetahclaws.git && cd cheetahclaws
pip install -r requirements.txt
python cheetahclaws.py # changes take effect immediately

Every cloud provider follows the same pattern — export its API key (see the Supported Models table for the env-var name), then select a model:

export ANTHROPIC_API_KEY=sk-ant-... # or OPENAI_API_KEY / GEMINI_API_KEY / DEEPSEEK_API_KEY / ...
cheetahclaws # default model
cheetahclaws --model gpt-4o # pick any model
cheetahclaws --model deepseek-chat --thinking --verbose

Provider get-key pages: Anthropic · OpenAI · Gemini · Kimi · Qwen · Zhipu · DeepSeek · MiniMax.

AWS Bedrock / Azure / Vertex use the litellm/<provider>/<model> form (pip install ".[litellm]") — full env-var recipes in recipes.md.

Full per-provider guide — every provider's get-key page + example model commands, plus Bedrock/Azure/Vertex env-var recipes: docs/guides/usage.md.

curl -fsSL https://ollama.com/install.sh | sh # install
ollama pull qwen2.5-coder # pull a tool-calling model
ollama serve # http://localhost:11434 (auto-starts on macOS)
cheetahclaws --model ollama/qwen2.5-coder # run (use `ollama list` to see local models)

Download LM Studio, grab a GGUF model, start its Local Server (port 1234), then:

cheetahclaws --model lmstudio/<model-name>

python -m vllm.entrypoints.openai.api_server \
 --model Qwen/Qwen2.5-Coder-32B-Instruct --port 8000 \
 --enable-auto-tool-choice --tool-call-parser hermes
export CUSTOM_BASE_URL=http://localhost:8000/v1
export CUSTOM_API_KEY=token-abc123 # any non-empty string if the server has no auth
cheetahclaws --model custom/Qwen2.5-Coder-32B-Instruct

The name after custom/ must match the server's --served-model-name. For the Web UI, --web --model custom/<name> persists the model before the server starts. Remote server? Point CUSTOM_BASE_URL at its IP.

Full local-model guide — Ollama step-by-step, LM Studio, vLLM + Web UI: docs/guides/usage.md.

🎁 Atlas Cloud is a full-modal AI inference platform with an OpenAI-compatible API — DeepSeek, Qwen, GLM, Kimi, MiniMax and more behind one endpoint. It plugs into the zero-dependency custom/ adapter:

export CUSTOM_BASE_URL=https://api.atlascloud.ai/v1
export CUSTOM_API_KEY=your_atlascloud_api_key
cheetahclaws --model custom/deepseek-ai/deepseek-v4-pro

deepseek-ai/deepseek-v4-pro is a reasoning model; any other Atlas chat model id works the same way.

Three equivalent forms are accepted:

cheetahclaws --model gpt-4o # 1. auto-detect by prefix
cheetahclaws --model ollama/qwen2.5-coder # 2. provider/model
cheetahclaws --model kimi:moonshot-v1-32k # 3. provider:model

Auto-detection by prefix: claude-→anthropic · gpt-/o1/o3→openai · gemini-→gemini · moonshot-/kimi-→kimi · qwen/qwq-→qwen · glm-→zhipu · deepseek-→deepseek · MiniMax-/abab→minimax · llama/mistral/phi/gemma/mixtral/codellama→ollama.

A built-in AI trading analysis + backtesting module (pip install "cheetahclaws[trading]").

/trading analyze NVDA # 5-phase pipeline: data → Bull/Bear debate → Judge → Risk panel → PM decision
/trading backtest AAPL dual_ma # backtest a strategy (or let AI pick); Sharpe/Sortino/Calmar/drawdown/win-rate

4 strategies (dual_ma, rsi_mean_reversion, bollinger_breakout, macd_crossover), BM25 memory of past situations, US/HK/A-share + crypto markets with no-API-key data fallbacks. Guided sub-menu via /ssj → Trading.

Full guide: docs/guides/trading.md

A production-ready browser interface — real user accounts (bcrypt + JWT), SQLite-backed history, ops endpoints — served by Python stdlib + ten vanilla-JS modules (no Node.js / React / build step).

pip install 'cheetahclaws[web]'
cheetahclaws --web # auto-picks a free port (tries 8080)
cheetahclaws --web --port 9000 --host 0.0.0.0 # bind explicitly / open to LAN
cheetahclaws --web --no-auth # skip login (localhost dev only)

Open http://localhost:<port>/chat — first account becomes admin. Includes streaming chat (WS) + SSE slash commands, persistent sessions with folders/search/Markdown export, tool cards, inline permission approval, settings panel, light/dark/system theme, and /health + /metrics endpoints. A full xterm.js PTY terminal lives at / (100% CLI parity).

Full guide: docs/guides/web-ui.md · Docker / home server: docs/guides/docker.md

Detailed guides live in docs/guides/ to keep this README focused:

cheetahclaws [OPTIONS] [PROMPT]
 -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
 --show-tools Show each tool call instead of a per-turn summary
 (alias: --no-quiet; compact summary is the default)
 --thinking Enable Extended Thinking (Claude only)
 --web Start web server (Chat UI + PTY terminal in browser)
 --port / --host Web server port / host (default 8080 / 127.0.0.1)
 --no-auth Disable web password (local use only)
 --version / -h Print version / show help

cheetahclaws # interactive REPL, default model
cheetahclaws -m ollama/deepseek-r1:32b # pick a model
cheetahclaws -p "Write a Python fibonacci function" # non-interactive
cheetahclaws --accept-all -p "Init a pyproject.toml" # CI / automation
cheetahclaws --web --port 8008 --no-auth # browser chat + terminal

See the Reference Guide for all 50+ slash commands, tools, and config options.

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

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 template.

A few common questions — the full FAQ is in docs/guides/faq.md.

Q: How do I add an MCP server?

/mcp add git uvx mcp-server-git # or create .mcp.json in your project, then /mcp reload

Q: Tool calls don't work with my local Ollama model (it just keeps describing what it would do instead of doing it). CheetahClaws now auto-recovers tool calls that local models emit as text (<tool_call>...</tool_call>, [TOOL_CALLS]...) instead of in Ollama's structured field, so most function-calling models execute tools out of the box. For best reliability use a tool-calling model — qwen2.5-coder, llama3.3, mistral, or phi4. Small models are also weaker at agentic tool use than cloud models, so expect them to need clearer, more concrete prompts.

Q: After installing on macOS, cheetahclaws: command not found and no ~/.zshrc was created. Reload your shell first: source ~/.zshrc (zsh) or source ~/.bash_profile (bash). The installer creates ~/.zshrc if missing, symlinks the binary into ~/.local/bin, and adds it to PATH. If you installed an older version, either re-run the installer or add this line yourself: echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc.

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? Run /cost (shows input/output tokens + estimated USD).

Q: Can I use multiple API keys in one session? Yes — set all keys upfront (env or /config), then switch models freely; each call uses the active provider's key.

Q: How do I set a default model across projects? Add keys to ~/.bashrc/~/.zshrc and set { "model": "claude-sonnet-4-6" } in ~/.cheetahclaws/config.json.

Q: Can I pipe input to cheetahclaws?

cat error.log | cheetahclaws -p "What is causing this error?"

Q: How do I set up voice input? pip install sounddevice faster-whisper numpy, then /voice in the REPL (downloads a ~150 MB Whisper model on first use). See the full FAQ for languages + keyterm tuning.

If you find the repository useful, please cite the study

@article{gu2026model,
 title={From Model Scaling to System Scaling: Scaling the Harness in Agentic AI},
 author={Gu, Shangding},
 journal={arXiv preprint arXiv:2605.26112},
 year={2026}
}
@article{cheetahclaws2026,
 title={CheetahClaws: Agent Harness Infrastructure for Long-Horizon, Multi-Model, and Tool-Using AI Systems},
 author={CheetahClaws Team},
 journal={github},
 year={2026}
}

chauncygu KevRojo mxh1999 seetvn bmaltais RheagalFire yamaceay tsint albertcheng LostAion lucaszhu-hue skint007 thekbbohara