Loading repository data…
Loading repository data…
SafeRL-Lab / repository
CheetahClaws: A Fast and Easy-to-Use Agent Harness Infrastructure for Long-Horizon, Multi-Model, and Tool-Using AI Systems
English | 中文 | 한국어 | 日本語 | Français | Deutsch | Español | Português
pip install cheetahclaws
Then just run:
cheetahclaws # start chatting!
Other install methods: one-line install script | install from source | uv install | run from source install | full install details | docker install
🖥️ Prefer a native app? A desktop build (Electron) wraps the full chat UI in a window — no terminal needed. See
desktop/.
prompt_toolkit is a core dependency (no [autosuggest] extra needed, so pip install / uv tool install both get it out of the box); /model gained a Tab-completion picker (provider/model + a two-level LiteLLM tree, PR #166); and sessions now autosave every turn (atomic write + fsync) so a crash or power-loss mid-conversation stays recoverable via /resume — the loud daily/history save still happens once on exit. Detailsdocker pull chauncygu/cheetahclaws) so you can run the Web UI without cloning; fixes a first-run PermissionError by pre-creating the .cheetahclaws/workspace dirs owned by the non-root user, makes the compose image overridable via CHEETAH_IMAGE, and adds scripts/docker-publish.sh (auto-reads the version, multi/single-arch). New docs sections: Pull from Docker Hub and Interactive setup / CLI mode. Details/workspace command manages isolated working directories under ~/.cheetahclaws/workspaces (list/switch/default/create/delete) (PR #162); startup auto-switching is opt-in via workspace_auto (off by default, so launching in a project directory is unchanged), and default is now a sticky key separate from last-used. Details/image now enriches the prompt with local OCR text so even non-vision models can act on clipboard screenshots (error dumps, code, tables); runs only when pytesseract/tesseract are installed and is fully opt-out via CHEETAHCLAWS_IMAGE_OCR=0. 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.
More animated demos (code review,
/research,/brainstorm,/lab, Telegram/WeChat/Slack bridges) live indocs/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.
| Dimension | Claude Code (TypeScript) | CheetahClaws (Python) |
|---|---|---|
| Language | TypeScript + React/Ink | Python 3.8+ |
| Source files / LoC | ~1,332 files / ~283K | ~315 files / ~90K (core; ~127K with tests) |
| Built-in tools / commands | 44+ / 88 | 27 / 50+ |
| Model providers | Anthropic only | 8+ (Anthropic · OpenAI · Gemini · Kimi · Qwen · DeepSeek · MiniMax · …) |
| Local models | No | Yes — Ollama, LM Studio, vLLM, any OpenAI-compatible endpoint |
| Build step | Yes (Bun + esbuild) | No — python cheetahclaws.py |
| Extensibility | Closed (compile-time) | Open — register_tool() at runtime, Markdown skills, git plugins, MCP |
| Voice input | Proprietary WebSocket (OAuth) | Local Whisper / OpenAI — works offline |
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.
| Dimension | OpenClaw (TypeScript) | CheetahClaws (Python) |
|---|---|---|
| Lines of code | ~245K (~10,349 files) | ~90K core (~315 files) |
| Primary focus | Personal assistant across channels | AI coding assistant / dev tool |
| Architecture | Always-on Gateway daemon + apps | Zero-install terminal REPL |
| Messaging channels | 20+ (WhatsApp · Signal · iMessage · Discord · Matrix · …) | Terminal + Telegram · WeChat · Slack · QQ bridges |
| Local / offline models | Limited | Full — Ollama · vLLM · LM Studio · any OpenAI-compatible |
| Code editing tools | Browser control, Canvas | Read · Write · Edit · Bash · Glob · Grep · NotebookEdit · GetDiagnostics |
| Mobile / Live Canvas | Yes (menu bar + iOS/Android, A2UI) | — |
| MCP support | — | Yes (stdio/SSE/HTTP) |
| Hackability | 245K lines, harder to modify | ~90K lines — agent loop in one file |
| If you want… | Use |
|---|---|
| A personal assistant on WhatsApp/Signal/Discord, mobile-first, browser automation + Canvas | OpenClaw |
| An AI coding assistant in your terminal, full offline/local models, multi-provider switching, source you can read in an afternoon | CheetahClaws |
Full comparison — both sides' wins + key design differences (agent loop, tool registration, context compression, memory): docs/guides/comparison.md.
| Feature | Details |
|---|---|
| Multi-provider | Anthropic · OpenAI · Gemini · Kimi · Qwen · Zhipu · DeepSeek · MiniMax · Ollama · LM Studio · Custom endpoint |
| Agent loop | Streaming API + automatic tool-use loop; the whole loop is in agent.py |
| 28 built-in tools | Read · Write · Edit · Bash · Glob · Grep · WebFetch · WebSearch · NotebookEdit · GetDiagnostics · Memory* · Agent/SendMessage · Skill · AskUserQuestion · Task* · SleepTimer · EnterPlanMode/ExitPlanMode · (MCP + plugin tools auto-added) |
| MCP integration | Connect any MCP server (stdio/SSE/HTTP); tools auto-registered — see extensions guide |
| Plugin system | Install/enable/update plugins from git URLs or local paths; multi-scope; recommendation engine |
| Task management | TaskCreate/Update/Get/List, sequential IDs, dependency edges, persisted to .cheetahclaws/tasks.json |
| Context compression | Four cooperating layers — dynamic max_tokens cap, per-model context-window registry, two-layer snip + AI summarize at 70%, and auto-fanout for oversized tool outputs. Details |
| Persistent memory | Dual-scope (user + project), 4 types, confidence/source metadata, conflict detection, recency-weighted search, /memory consolidate. Verification-anchored staleness — freshness tracks a last_verified date (not file mtime), so reading a memory can't fake-refresh it; only MemoryVerify resets the clock. Details |
| Multi-agent | Spawn typed sub-agents (coder/reviewer/researcher/…), git-worktree isolation, background mode |
| Permission system | auto / accept-edits / accept-all / manual / plan modes (accept-edits = auto-run edits, still ask for other Bash; hard denylist blocks host-destroying commands in every mode) |
| Checkpoints & plan mode | Auto-snapshot conversation + files each turn (/checkpoint, /rewind); /plan read-only analysis mode |
| Slash commands & themes |
50+ slash commands with Tab-complete; /theme offers 15 curated palettes |
| Brainstorm → Worker | /brainstorm runs an N-persona debate → todo_list.txt; /worker auto-implements the pending tasks |
| SSJ Developer Mode | /ssj — persistent power menu chaining Brainstorm, Worker, Review, Trading, Agent, Video/TTS, Monitor, etc. |
| Trading agent | `/ |