{"id":48459383,"url":"https://github.com/saferl-lab/cheetahclaws","last_synced_at":"2026-04-08T02:00:57.598Z","repository":{"id":348547092,"uuid":"1198604352","full_name":"SafeRL-Lab/cheetahclaws","owner":"SafeRL-Lab","description":"CheetahClaws (Nano Claude Code): A Fast, Easy-to-Use, Python-Native Personal AI Assistant for Any Model, Inspired by OpenClaw and Claude Code, Built to Work for You Autonomously 24/7.","archived":false,"fork":false,"pushed_at":"2026-04-07T22:22:57.000Z","size":8230,"stargazers_count":438,"open_issues_count":4,"forks_count":174,"subscribers_count":6,"default_branch":"main","last_synced_at":"2026-04-08T00:02:45.894Z","etag":null,"topics":["agentic-ai","claude","claude-code","memory","openclaw","python","skills"],"latest_commit_sha":null,"homepage":"https://deepwiki.com/SafeRL-Lab/cheetahclaws","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SafeRL-Lab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-01T15:23:36.000Z","updated_at":"2026-04-07T23:10:57.000Z","dependencies_parsed_at":"2026-04-07T04:03:17.929Z","dependency_job_id":null,"html_url":"https://github.com/SafeRL-Lab/cheetahclaws","commit_stats":null,"previous_names":["saferl-lab/nano-claude-code","saferl-lab/clawnest","saferl-lab/clawspring"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/SafeRL-Lab/cheetahclaws","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SafeRL-Lab%2Fcheetahclaws","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SafeRL-Lab%2Fcheetahclaws/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SafeRL-Lab%2Fcheetahclaws/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SafeRL-Lab%2Fcheetahclaws/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SafeRL-Lab","download_url":"https://codeload.github.com/SafeRL-Lab/cheetahclaws/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SafeRL-Lab%2Fcheetahclaws/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31536473,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"online","status_checked_at":"2026-04-08T02:00:06.127Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","claude","claude-code","memory","openclaw","python","skills"],"created_at":"2026-04-07T01:02:40.746Z","updated_at":"2026-04-08T02:00:57.587Z","avatar_url":"https://github.com/SafeRL-Lab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"English | [中文](https://github.com/SafeRL-Lab/clawspring/blob/main/docs/README.CN.MD) | [Français](https://github.com/SafeRL-Lab/clawspring/blob/main/docs/README.FR.MD) | [한국어](https://github.com/SafeRL-Lab/clawspring/blob/main/docs/README.KO.MD) | [日本語](https://github.com/SafeRL-Lab/clawspring/blob/main/docs/README.JP.MD) | [Deutsch](https://github.com/SafeRL-Lab/clawspring/blob/main/docs/README.DE.MD) | [Português](https://github.com/SafeRL-Lab/clawspring/blob/main/docs/README.ES.MD)\n\n\u003cbr\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"[https://github.com/SafeRL-Lab/Robust-Gymnasium](https://github.com/SafeRL-Lab/clawspring)\"\u003e\n    \u003cimg src=\"https://github.com/SafeRL-Lab/clawspring/blob/main/docs/logo-5.png\" alt=\"Logo\" width=\"280\"\u003e \n  \u003c/a\u003e\n\n  \n\u003ch2 align=\"center\" style=\"font-size: 30px;\"\u003e\u003cstrong\u003e\u003cem\u003eCheetahClaws (Nano Claude Code)\u003c/em\u003e\u003c/strong\u003e: A Fast, Easy-to-Use, Python-Native Personal AI Assistant for Any Model, Inspired by OpenClaw and Claude Code, Built to Work for You Autonomously 24/7\u003c/h2\u003e\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/chauncygu/collection-claude-code-source-code\"\u003eThe newest source of Claude Code\u003c/a\u003e\n    ·\n    \u003ca href=\"https://github.com/SafeRL-Lab/clawspring/issues\"\u003eIssue\u003c/a\u003e\n  ·\n    \u003ca href=\"https://deepwiki.com/SafeRL-Lab/clawspring\"\u003eBrief Intro\u003c/a\u003e\n  \n  \u003c/p\u003e\n\u003c/div\u003e\n\n \u003cdiv align=center\u003e\n \u003cimg src=\"https://github.com/SafeRL-Lab/clawspring/blob/main/docs/demo.gif\" width=\"850\"/\u003e \n \u003c/div\u003e\n\u003cdiv align=center\u003e\n\u003ccenter style=\"color:#000000;text-decoration:underline\"\u003eTask Excution\u003c/center\u003e\n \u003c/div\u003e\n \n \n---\n\n  \u003cdiv align=center\u003e\n \u003cimg src=\"https://github.com/SafeRL-Lab/clawspring/blob/main/docs/brainstorm_demo.gif\" width=\"850\"/\u003e \n \u003c/div\u003e\n\u003cdiv align=center\u003e\n\u003ccenter style=\"color:#000000;text-decoration:underline\"\u003eBrainstorm Mode: Multi-Agent Brainstorm\u003c/center\u003e\n \u003c/div\u003e\n\n\n\n---\n\n  \u003cdiv align=center\u003e\n \u003cimg src=\"https://github.com/SafeRL-Lab/clawspring/blob/main/docs/proactive_demo.gif\" width=\"850\"/\u003e \n \u003c/div\u003e\n\u003cdiv align=center\u003e\n\u003ccenter style=\"color:#000000;text-decoration:underline\"\u003eProactive Mode: Autonomous Agent\u003c/center\u003e\n \u003c/div\u003e\n\n---\n\n  \u003cdiv align=center\u003e\n \u003cimg src=\"https://github.com/SafeRL-Lab/clawspring/blob/main/docs/ssj_demo.gif\" width=\"850\"/\u003e \n \u003c/div\u003e\n\u003cdiv align=center\u003e\n\u003ccenter style=\"color:#000000;text-decoration:underline\"\u003eSSJ Developer Mode: Power Menu Workflow\u003c/center\u003e\n \u003c/div\u003e\n\n---\n\n  \u003cdiv align=center\u003e\n \u003cimg src=\"https://github.com/SafeRL-Lab/clawspring/blob/main/docs/telegram_demo.gif\" width=\"850\"/\u003e \n \u003c/div\u003e\n\u003cdiv align=center\u003e\n\u003ccenter style=\"color:#000000;text-decoration:underline\"\u003eTelegram Bridge: Control cheetahclaws from Your Phone\u003c/center\u003e\n \u003c/div\u003e\n\n---\n\n\n \n## 🔥🔥🔥 News (Pacific Time)\n\n\n- Apr 06, 2026 (**v3.05.52**): **Checkpoint system, plan mode, compact, and utility commands, support MiniMax Models** \n  - **Checkpoint system** (`checkpoint/` package): auto-snapshots conversation state and file changes after every turn. `/checkpoint` lists all snapshots; `/checkpoint \u003cid\u003e` rewinds both files and conversation history to any previous state; `/checkpoint clear` removes all snapshots for the session. `/rewind` is an alias. 100-snapshot sliding window; initial snapshot captured at session start. Throttling: skips when nothing changed. File backups use copy-on-write; snapshots capture post-edit state.\n  - **Plan mode**: `/plan \u003cdesc\u003e` enters a read-only analysis mode — Claude may only read the codebase and write to a dedicated plan file (`.nano_claude/plans/\u003csession_id\u003e.md`). All other writes are silently blocked with a helpful message. `/plan` shows the current plan; `/plan done` exits plan mode and restores original permissions; `/plan status` reports whether plan mode is active. Two new agent tools — `EnterPlanMode` and `ExitPlanMode` — let Claude autonomously enter and exit plan mode for complex multi-file tasks; both are auto-approved in all permission modes.\n  - **`/compact [focus]`**: manually trigger conversation compaction at any time. An optional focus string guides the LLM summarizer on what context to preserve. Auto-compact and manual compact both restore plan file context after compaction.\n  - **Utility commands**: `/init` creates a `CLAUDE.md` template in the current directory; `/export [filename]` exports the conversation as Markdown (default) or JSON; `/copy` copies the last assistant response to the clipboard (Windows/macOS/Linux); `/status` shows version, model, provider, permissions, session ID, token usage, and context %; `/doctor` diagnoses installation health (Python version, git, API key + live connectivity test, optional deps, CLAUDE.md presence, checkpoint disk usage, permission mode).\n\n- Apr 06, 2026 (**v3.05.51**): **Project renamed from Nano Claude Code to CheetahClaws**\n  - The project has been rebranded from **Nano Claude Code** to **CheetahClaws** — a more distinctive name that captures the spirit of the tool: a sharp, agile coding assistant. The `Cl` in CheetahClaws is a subtle nod to Claude.\n  - CLI command: `nano_claude` → `cheetahclaws`\n  - PyPI package: `nano-claude-code` → `cheetahclaws`\n  - Config directory: `~/.nano_claude/` → `~/.clawnest/` → `~/.cheetahclaws/`\n  - Main entry point: `nano_claude.py` → `cheetahclaws.py`\n  - All documentation, GitHub URLs, and internal references updated accordingly.\n  - Added **CheetahClaws vs OpenClaw** comparison section to README.\n\n- 00.29 PM, Apr 06, 2026 (**v3.05.5**): **SSJ Developer Mode, Telegram Bridge, Worker Command, and UX improvements** \n  - **`/ssj` — SSJ Developer Mode**: Interactive power menu with 10 workflow options: Brainstorm, TODO viewer, Worker, Expert Debate, Propose Improvements, Code Review, README generator, Commit helper, Git Diff Scan, and Idea-to-Tasks Promotion. Menu stays open between actions and supports `/command` passthrough (e.g. `/exit` works from inside SSJ).\n  - **`/worker` command**: Auto-implements pending tasks from `brainstorm_outputs/todo_list.txt` one by one. Supports selecting specific tasks with comma-separated numbers (e.g. `1,4,6`), a custom todo file path (`--path /other/todo.md`), and a worker count limit (`--workers 3`). If you accidentally pass a brainstorm `.md` output file, Worker detects it and offers to redirect to `todo_list.txt` — or to generate it first from the brainstorm file and then run Worker automatically. Each task gets a dedicated prompt that reads code, implements the change, and marks it done.\n  - **`/telegram` — Telegram Bot Bridge**: Receives messages via Telegram Bot API and routes them through the model, sending responses back to the chat. Auto-starts on launch if configured. Only responds to the authorized `chat_id`. Supports slash command passthrough (`/cost`, `/model`, etc.), shows a typing indicator while the model processes, and can be stopped remotely by sending `/stop` in Telegram.\n  - **Brainstorm → TODO pipeline**: After brainstorm synthesis, automatically generates `brainstorm_outputs/todo_list.txt` with prioritized checkbox tasks. TODO viewer (SSJ option 2) shows only pending tasks as numbered (completed tasks shown with ✓ without a number).\n  - **Expert Debate improvements**: SSJ option 4 now prompts for the number of debate agents (default 2, minimum 2); rounds are auto-calculated as `(agents × 2 − 1)`. The debate result is saved to the same directory as the debated file (`\u003cstem\u003e_debate_HHMMSS.md`). An animated per-round per-expert spinner (`⚔️ Round 2/3 — Expert 1 thinking...`) keeps the terminal lively throughout the debate.\n  - **Brainstorm spinner**: Animated spinner with random phrases while brainstorm agents are thinking.\n  - **Force quit**: 3× Ctrl+C within 2 seconds triggers `os._exit(1)` — kills the process immediately regardless of blocking I/O.\n  - **Interactive Ollama Model Picker** — when a request fails with 404 (model not found), cheetahclaws queries the local Ollama API (`/api/tags`) and presents a numbered model selector to switch models and retry without restarting. Cancelling aborts gracefully without crashing the REPL.\n  - **Windows file handling** — `_read`, `_write`, and `_edit` in `tools.py` now force UTF-8 encoding and `newline=\"\"`. `_edit` detects pure-CRLF files (every `\\n` is part of `\\r\\n`) and restores line endings after edit; mixed-line-ending files are left as-is to avoid corruption.\n  - **/brainstorm command** — `/brainstorm [topic]` runs a multi-persona AI debate. The model first generates N expert personas tailored to the topic (geopolitics → analysts \u0026 diplomats; software → architects \u0026 engineers; etc.). Agent count is chosen interactively at runtime (2–100, default 5). Results are saved to `brainstorm_outputs/` and synthesized by the main agent. \n  - **Rich Live SSH fix** — Rich's in-place Live streaming is now automatically disabled in SSH sessions (`SSH_CLIENT`/`SSH_TTY` detected) where ANSI cursor-up breaks and causes repeated output lines. Override with `/config rich_live=true/false`.\n  - **`threading.RLock`** — replaced `threading.Lock` with `RLock` to support re-entrant calls from brainstorm synthesis and Ollama retry paths.\n\n- 05:39 PM, Apr 05, 2026 (**v3.05.4**): **Reasoning, Rendering, and Packaging Improvements, Enhanced Memory System, Native vision support for local Ollama models, Bracketed Paste Mode, Rich Tab Completion**\n  - **Bracketed Paste Mode** — replaced the old timing-based multi-line paste detection with the standard terminal Bracketed Paste Mode protocol. Pasted text of any length (code blocks, long prompts, multi-paragraph instructions) is now collected as a single turn with zero latency and no blank-line artifacts. Falls back to a 60 ms timing window for terminals that don't support BPM. Bracketed paste mode is cleanly disabled on REPL exit.\n  - **Rich Tab Completion with descriptions** — pressing Tab after `/` now shows every command with a one-line description and a hint of its subcommands. Typing `/plugin ` then Tab lists all subcommands (`install`, `uninstall`, `enable`, …). Auto-completes to the unique match when only one command matches the prefix. Subcommands supported for `/mcp`, `/plugin`, `/tasks`, `/cloudsave`, `/voice`, `/permissions`, `/proactive`, and `/memory`.\n  - **Model name bug fix** — `--model ollama/qwen3.5:35b` no longer gets corrupted to `ollama/qwen3.5/35b`. The startup colon-to-slash conversion now only fires when the left side of `:` is a known provider name and no `/` is already present, preserving Ollama's `model:tag` format.\n  - **Native vision support for local Ollama models** (`llava`, `gemma4`, `llama3.2-vision`): new `/image [prompt]` command captures the current clipboard image, encodes it to Base64, and attaches it to the next prompt. Install Pillow with `pip install cheetahclaws[vision]`; Linux users also need `xclip` (`sudo apt install xclip`).\n  - **Enhanced Memory System** — added `confidence` / `source` / `last_used_at` / `conflict_group` metadata to every memory entry; conflict detection on `MemorySave` warns before overwriting; `MemorySearch` re-ranks results by `confidence × recency` (30-day decay) and updates `last_used_at` on hits; new `/memory consolidate` command runs a lightweight AI analysis of the current session and auto-saves up to 3 long-term insights (user preferences, feedback corrections, project decisions) at 0.8 confidence — never overwrites higher-confidence user memories.\n  - **Post-merge fixes** — removed a debug `debug_payload.json` file write that was firing on every OpenAI-compatible API call (left over from PR #11 development). Also fixed ANSI dim color not being reset after the thinking block ends, which caused subsequent text to appear dim in non-Rich terminals. Bumped `pyproject.toml` version to `3.05.4`, and moved `sounddevice` to the optional `voice` extra (`pip install cheetahclaws[voice]`).\n  - **Native Ollama reasoning + terminal rendering fix** — local reasoning models (`deepseek-r1`, `qwen3`, `gemma4`) now stream their `\u003cthink\u003e` blocks to the terminal. Ollama exposes thoughts in `msg[\"thinking\"]`, but cheetahclaws was previously dropping them; this is now fixed by yielding `ThinkingChunk` from the Ollama adapter. Also fixed a Windows CMD/PowerShell rendering issue where token-by-token ANSI dim resets caused thoughts to print vertically, and corrected `flush_response()` so it runs once at the end instead of on every thinking token. Enable with `/verbose` and `/thinking`.\n  - **uv support** — added `pyproject.toml`; install with `uv tool install .` to make the `cheetahclaws` command available globally from anywhere in an isolated environment, without manual PATH setup.\n- 00:41 PM, Apr 05, 2026: **v3.05.3 add structured session history** — Structured session history: on every exit, sessions are saved to `daily/YYYY-MM-DD/` (capped at `session_daily_limit`, default 5 per day) and appended to a master `history.json` (capped at `session_history_limit`, default 100). Each session file now includes `session_id` and `saved_at` metadata. `/load` groups sessions by date with time, ID, and turn-count display; supports multi-select (`1,2,3`) to merge sessions and `H` to load the full history with token-count confirmation. Both limits are configurable via `/config`.\n- 00:41 PM, Apr 05, 2026: **v3.05.3 fix session** — Structured session history: on every exit, sessions are saved to `daily/YYYY-MM-DD/` (capped at `session_daily_limit`, default 5 per day) and appended to a master `history.json` (capped at `session_history_limit`, default 100). Each session file now includes `session_id` and `saved_at` metadata. `/load` groups sessions by date with time, ID, and turn-count display; supports multi-select (`1,2,3`) to merge sessions and `H` to load the full history with token-count confirmation. Both limits are configurable via `/config`.\n- 09:34 AM, Apr 05, 2026: **v3.05.3** — Added GitHub Gist cloud sync: `/cloudsave setup \u003ctoken\u003e` to configure, `/cloudsave` to upload the current session to a private Gist, `/cloudsave auto on` to sync automatically on `/exit`, `/cloudsave list` to browse cloud sessions, and `/cloudsave load \u003cid\u003e` to restore from the cloud. Uses stdlib `urllib` — no new dependencies. Also added version number (e.g., `v3.05.2`) in the startup banner: The startup banner now displays the current version number (v3.05.2) in green, making it easy to identify which version is running at a glance.\n- 08:58 AM, Apr 05, 2026: **v3.05.2** — Introduced `/proactive [duration]` command: a background daemon thread watches for user inactivity and automatically wakes the agent up after the specified interval (e.g. `/proactive 5m`), enabling continuous monitoring loops without user intervention. `/proactive` with no args now shows current status; `/proactive off` disables it explicitly. Proactive polling state is stored in `config` (no module-level globals). Watcher exceptions are logged via `traceback` instead of silently swallowed. Also fixed duplicated output in Rich-enabled terminals by buffering text during streaming and rendering Markdown once via `rich.live.Live` — updates happen in-place for a true streaming Markdown experience. \n- 10:51 PM, Apr 04, 2026: **v3.05_fix04** — Fixed a crash on `/model` and config save commands caused by the newly introduced `_run_query_callback` being serialized to JSON; also added `SleepTimer` usage    \n  guidance to the system prompt so the agent knows when to invoke background timers proactively.\n- 10:28 PM, Apr 04, 2026: **v3.05_fix03** — Added a native `SleepTimer` tool that lets the agent schedule background timers and autonomously wake itself up after a delay — no user prompt required. Paired with a `threading.Lock` to prevent output collisions when background and foreground calls overlap. Also includes cross-platform fixes: Windows ANSI color support, CRLF-aware Edit tool matching, an interactive numbered menu for `/load`, native Ollama streaming via `/api/chat`, and auto-capping `max_tokens` per provider to prevent API errors. \n- 08:31 PM, Apr 04, 2026: **v3.05_fix** — Autosave + `/resume`: session is automatically saved to `mr_sessions/session_latest.json` on `/exit`, `/quit`, `Ctrl+C`, and `Ctrl+D`. Run `/resume` to restore the last session instantly, or `/resume \u003cfile\u003e` to load a specific file from `mr_sessions/`, and better support for api and local Ollama models (specifically gemma4), along with Windows compatibility enhancements, session management UX improvements, and cross-platform reliability fixes for the Edit tool.\n- 00:41 AM, Apr 04, 2026: **v3.05** — Voice input (`voice/` package): `sounddevice` → `arecord` → SoX recording backends, `faster-whisper` → `openai-whisper` → OpenAI API STT backends. Smart keyterm extraction from git branch + project name + recent files passed as Whisper `initial_prompt` for coding-domain accuracy. `/voice`, `/voice status`, `/voice lang \u003ccode\u003e` REPL commands. Works fully offline with no API key. 29 new tests (**~11.6K** lines of Python).\n- 10:29 PM, Apr 03, 2026: **v3.04** — Expanded tool coverage: `NotebookEdit` (edit Jupyter `.ipynb` cells — replace/insert/delete with full JSON round-trip) and `GetDiagnostics` (LSP-style diagnostics via pyright/mypy/flake8/tsc/shellcheck). Also fixed a pre-existing schema-index bug in `_register_builtins` by switching to name-based lookup (**~10.5K** lines of Python).\n- 06:00 PM, Apr 03, 2026: **v3.03** — Task management system (`task/` package): `TaskCreate` / `TaskUpdate` / `TaskGet` / `TaskList` tools with sequential IDs, dependency edges (blocks/blocked_by), metadata, persistence to `.cheetahclaws/tasks.json`, thread-safe store, `/tasks` REPL command, 37 new tests (**~9500** lines of Python).\n- 02:50 PM, Apr 03, 2026: **v3.02** — Plugin system (`plugin/` package): install/uninstall/enable/disable/update via `/plugin` CLI, recommendation engine (keyword+tag matching), multi-scope (user/project), git-based marketplace. `AskUserQuestion` tool: interactive mid-task user prompts with numbered options and free-text input (**~8500** lines of Python).\n- 10:00 AM, Apr 03, 2026: **v3.01** — MCP (Model Context Protocol) support: `mcp/` package, stdio + SSE + HTTP transports, auto tool discovery, `/mcp` command, 34 new tests (**~7000** lines of Python).\n- 12:20 PM, Apr 02, 2026: **v3.0** — Multi-agent packages (`multi_agent/`), memory package (`memory/`), skill package (`skill/`) with built-in skills, argument substitution, fork/inline execution, AI memory search, git worktree isolation, agent type definitions (**~5000** lines of Python), see [update](https://github.com/SafeRL-Lab/clawspring/blob/main/docs/update_readme_v3.0.md).\n- 10:00 AM, Apr 02, 2026: **v2.0** — Context compression, memory, sub-agents, skills, diff view, tool plugin system (**~3400** lines of Python Code).\n- 01:47 PM, Apr 01, 2026: Support VLLM inference (**~2000** lines of Python Code).\n- 11:30 AM, Apr 01, 2026: Support more **closed-source** models and **open-source models**: Claude, GPT, Gemini, Kimi, Qwen, Zhipu, DeepSeek, and local open-source models via Ollama or any OpenAI-compatible endpoint. (**~1700** lines of Python Code).\n- 09:50 AM, Apr 01, 2026: Support more **closed-source** models: Claude, GPT, Gemini. (**~1300** lines of Python Code).\n- 08:23 AM, Apr 01, 2026: Release the initial version of CheetahClaws (**~900 lines** of Python Code).\n\n---\n\n# CheetahClaws\n\nCheetahClaws: **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.\n\n---\n\n## Content\n  * [Why CheetahClaws](#why-cheetahclaws)\n  * [CheetahClaws vs OpenClaw](#cheetahclaws-vs-openclaw)\n  * [Features](#features)\n  * [Supported Models](#supported-models)\n  * [Installation](#installation)\n  * [Usage: Closed-Source API Models](#usage--closed-source-api-models)\n  * [Usage: Open-Source Models (Local)](#usage--open-source-models--local-)\n  * [Model Name Format](#model-name-format)\n  * [CLI Reference](#cli-reference)\n  * [Slash Commands (REPL)](#slash-commands--repl-)\n  * [Configuring API Keys](#configuring-api-keys)\n  * [Permission System](#permission-system)\n  * [Built-in Tools](#built-in-tools)\n  * [Memory](#memory)\n  * [Skills](#skills)\n  * [Sub-Agents](#sub-agents)\n  * [MCP (Model Context Protocol)](#mcp-model-context-protocol)\n  * [Plugin System](#plugin-system)\n  * [AskUserQuestion Tool](#askuserquestion-tool)\n  * [Task Management](#task-management)\n  * [Voice Input](#voice-input)\n  * [Brainstorm](#brainstorm)\n  * [SSJ Developer Mode](#ssj-developer-mode)\n  * [Telegram Bridge](#telegram-bridge)\n  * [Proactive Background Monitoring](#proactive-background-monitoring)\n  * [Checkpoint System](#checkpoint-system)\n  * [Plan Mode](#plan-mode)\n  * [Context Compression](#context-compression)\n  * [Diff View](#diff-view)\n  * [CLAUDE.md Support](#claudemd-support)\n  * [Session Management](#session-management)\n  * [Cloud Sync (GitHub Gist)](#cloud-sync-github-gist)\n  * [Project Structure](#project-structure)\n  * [FAQ](#faq)\n\n\n\n\n## Why CheetahClaws\n\nClaude 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.\n\n**CheetahClaws** reimplements the same core loop in ~10K 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](https://github.com/SafeRL-Lab/clawspring/blob/main/docs/comparison_claude_code_vs_nano_v3.03_en.md) and [Chinese version](https://github.com/SafeRL-Lab/clawspring/blob/main/docs/comparison_claude_code_vs_nano_v3.03_cn.md)\n\n### At a glance\n\n| Dimension | Claude Code (TypeScript) | CheetahClaws (Python) |\n|-----------|--------------------------|---------------------------|\n| Language | TypeScript + React/Ink | Python 3.8+ |\n| Source files | ~1,332 TS/TSX files | 51 Python files |\n| Lines of code | ~283K | ~12K |\n| Built-in tools | 44+ | 27 |\n| Slash commands | 88 | 36 |\n| Voice input | Proprietary Anthropic WebSocket (OAuth required) | Local Whisper / OpenAI API — works offline, no subscription |\n| Model providers | Anthropic only | 8+ (Anthropic · OpenAI · Gemini · Kimi · Qwen · DeepSeek · MiniMax · Ollama · …) |\n| Local models | No | Yes — Ollama, LM Studio, vLLM, any OpenAI-compatible endpoint |\n| Build step required | Yes (Bun + esbuild) | No — run directly with `python cheetahclaws.py` (or install to use `cheetahclaws`) |\n| Runtime extensibility | Closed (compile-time) | Open — `register_tool()` at runtime, Markdown skills, git plugins |\n| Task dependency graph | No | Yes — `blocks` / `blocked_by` edges in `task/` package |\n\n### Where Claude Code wins\n\n- **UI quality** — React/Ink component tree with streaming rendering, fine-grained diff visualization, and dialog systems.\n- **Tool breadth** — 44 tools including `RemoteTrigger`, `EnterWorktree`, and more UI-integrated tools.\n- **Enterprise features** — MDM-managed config, team permission sync, OAuth, keychain storage, GrowthBook feature flags.\n- **AI-driven memory extraction** — `extractMemories` service proactively extracts knowledge from conversations without explicit tool calls.\n- **Production reliability** — single distributable `cli.js`, comprehensive test coverage, version-locked releases.\n\n### Where CheetahClaws wins\n\n- **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.\n- **Local model support** — run entirely offline with Ollama, LM Studio, or any vLLM-hosted model.\n- **Readable source** — the full agent loop is 174 lines (`agent.py`). Any Python developer can read, fork, and extend it in minutes.\n- **Zero build** — `pip install -r requirements.txt` and you're running. Changes take effect immediately.\n- **Dynamic extensibility** — register new tools at runtime with `register_tool(ToolDef(...))`, install skill packs from git URLs, or wire in any MCP server.\n- **Task dependency graph** — `TaskCreate` / `TaskUpdate` support `blocks` / `blocked_by` edges for structured multi-step planning (not available in Claude Code).\n- **Two-layer context compression** — rule-based snip + AI summarization, configurable via `preserve_last_n_turns`.\n- **Notebook editing** — `NotebookEdit` directly manipulates `.ipynb` JSON (replace/insert/delete cells) with no kernel required.\n- **Diagnostics without LSP server** — `GetDiagnostics` chains pyright → mypy → flake8 → py_compile for Python and tsc/shellcheck for other languages, with zero configuration.\n- **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.\n- **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 \u003cid\u003e`.\n- **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.\n- **Telegram Bot Bridge** — `/telegram \u003ctoken\u003e \u003cchat_id\u003e` 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.\n- **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`).\n- **Force quit** — 3× Ctrl+C within 2 seconds triggers immediate `os._exit(1)`, unblocking any frozen I/O.\n- **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.\n- **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.\n- **Native Ollama reasoning** — Local reasoning models (deepseek-r1, qwen3, gemma4) stream their `\u003cthink\u003e` tokens directly to the terminal via `ThinkingChunk` events; enable with `/verbose` and `/thinking`.\n- **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.\n- **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.\n- **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.\n- **Checkpoint \u0026 rewind** — `/checkpoint` lists all auto-snapshots of conversation + file state; `/checkpoint \u003cid\u003e` rewinds both files and history to any earlier point in the session.\n- **Plan mode** — `/plan \u003cdesc\u003e` (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.\n\n---\n\n## CheetahClaws vs OpenClaw\n\n[OpenClaw](https://github.com/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.\n\n### At a glance\n\n| Dimension | OpenClaw (TypeScript) | CheetahClaws (Python) |\n|-----------|----------------------|---------------------|\n| Language | TypeScript + Node.js | Python 3.8+ |\n| Source files | ~10,349 TS/JS files | 51 Python files |\n| Lines of code | ~245K | ~12K |\n| Primary focus | Personal life assistant across messaging channels | AI **coding** assistant / developer tool |\n| Architecture | Always-on Gateway daemon + companion apps | Zero-install terminal REPL |\n| Messaging channels | 20+ (WhatsApp · Telegram · Slack · Discord · Signal · iMessage · Matrix · WeChat · …) | Terminal + optional Telegram bridge |\n| Model providers | Multiple (cloud-first) | 7+ including full local support (Ollama · vLLM · LM Studio · …) |\n| Local / offline models | Limited | Full — Ollama, vLLM, any OpenAI-compatible endpoint |\n| Voice | Wake word · PTT · Talk Mode (macOS/iOS/Android) | Offline Whisper STT (local, no API key) |\n| Code editing tools | Browser control, Canvas workspace | Read · Write · Edit · Bash · Glob · Grep · NotebookEdit · GetDiagnostics |\n| Build step required | Yes (`pnpm install` + daemon setup) | No — `pip install` and run |\n| Mobile companion | macOS menu bar + iOS/Android apps | — |\n| Live Canvas / UI | Yes (A2UI agent-driven visual workspace) | — |\n| MCP support | — | Yes (stdio/SSE/HTTP) |\n| Runtime extensibility | Skills platform (bundled/managed/workspace) | `register_tool()` at runtime, MCP, git plugins, Markdown skills |\n| Hackability | Large codebase (245K lines), harder to modify | ~12K lines — full agent loop visible in one file |\n\n### Where OpenClaw wins\n\n- **Omni-channel inbox** — connects to 20+ messaging platforms (WhatsApp, Signal, iMessage, Discord, Teams, Matrix, WeChat…); users interact from wherever they already are.\n- **Always-on daemon** — Gateway runs as a background service (launchd/systemd); no terminal required for day-to-day use.\n- **Mobile-first** — macOS menu bar, iOS Voice Wake / Talk Mode, Android camera/screen recording — feels like a native app, not a CLI tool.\n- **Live Canvas** — agent-driven visual workspace rendered in the browser; supports A2UI push/eval/snapshot.\n- **Browser automation** — dedicated Chrome/Chromium profile with snapshot, actions, and upload tools.\n- **Production reliability** — versioned npm releases, comprehensive CI, onboarding wizard, `openclaw doctor` diagnostics.\n\n### Where CheetahClaws wins\n\n- **Coding toolset** — Read/Write/Edit/Bash/Glob/Grep/NotebookEdit/GetDiagnostics are purpose-built for software development; CheetahClaws understands diffs, file trees, and code structure.\n- **True local model support** — full Ollama/vLLM/LM Studio integration with streaming, tool-calling, and vision — no cloud required.\n- **8+ model providers** — switch between Claude, GPT-4o, Gemini, DeepSeek, Qwen, MiniMax, and local models with a single `--model` flag.\n- **Hackable in minutes** — 12K lines of readable Python; the entire agent loop is in `agent.py`; extend with `register_tool()` at runtime without rebuilding.\n- **Zero setup** — `pip install cheetahclaws` and run `cheetahclaws`; no daemon, no pairing, no onboarding wizard.\n- **MCP support** — connect any MCP server (stdio/SSE/HTTP); tools auto-registered.\n- **SSJ Developer Mode** — `/ssj` power menu chains Brainstorm → TODO → Worker → Debate in a persistent interactive session; automates entire dev workflows.\n- **Offline voice** — `/voice` transcribes locally with `faster-whisper`; no subscription, no OAuth, works without internet.\n- **Session cloud sync** — `/cloudsave` backs up full conversations to private GitHub Gists with zero extra dependencies.\n\n### When to choose which\n\n| If you want… | Use |\n|---|---|\n| A personal assistant you can message on WhatsApp/Signal/Discord | **OpenClaw** |\n| An AI coding assistant in your terminal | **CheetahClaws** |\n| Full offline / local model support | **CheetahClaws** |\n| A mobile-friendly always-on experience | **OpenClaw** |\n| To read and modify the source in an afternoon | **CheetahClaws** |\n| Browser automation and a visual Canvas | **OpenClaw** |\n| Multi-provider LLM switching without rebuilding | **CheetahClaws** |\n\n---\n\n### Key design differences\n\n**Agent loop** — CheetahClaws uses a Python generator that `yield`s typed events (`TextChunk`, `ToolStart`, `ToolEnd`, `TurnDone`). The entire loop is visible in one file, making it easy to add hooks, custom renderers, or logging.\n\n**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.\n\n**Context compression**\n\n| | Claude Code | CheetahClaws |\n|-|-------------|-----------------|\n| Trigger | Exact token count | `len / 3.5` estimate, fires at 70 % |\n| Layer 1 | — | Snip: truncate old tool outputs (no API cost) |\n| Layer 2 | AI summarization | AI summarization of older turns |\n| Control | System-managed | `preserve_last_n_turns` parameter |\n\n**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.\n\n### Who should use CheetahClaws\n\n- Developers who want to **use a local or non-Anthropic model** as their coding assistant.\n- Researchers studying **how agentic coding assistants work** — the entire system fits in one screen.\n- Teams who need a **hackable baseline** to add proprietary tools, custom permission policies, or specialised agent types.\n- Anyone who wants Claude Code-style productivity **without a Node.js build chain**.\n\n---\n\n## Features\n\n| Feature | Details |\n|---|---|\n| Multi-provider | Anthropic · OpenAI · Gemini · Kimi · Qwen · Zhipu · DeepSeek · MiniMax · Ollama · LM Studio · Custom endpoint |\n| Interactive REPL | readline history, Tab-complete slash commands with descriptions + subcommand hints; Bracketed Paste Mode for reliable multi-line paste |\n| Agent loop | Streaming API + automatic tool-use loop |\n| 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)* |\n| MCP integration | Connect any MCP server (stdio/SSE/HTTP), tools auto-registered and callable by Claude |\n| Plugin system | Install/uninstall/enable/disable/update plugins from git URLs or local paths; multi-scope (user/project); recommendation engine |\n| AskUserQuestion | Claude can pause and ask the user a clarifying question mid-task, with optional numbered choices |\n| Task management | TaskCreate/Update/Get/List tools; sequential IDs; dependency edges; metadata; persisted to `.cheetahclaws/tasks.json`; `/tasks` REPL command |\n| Diff view | Git-style red/green diff display for Edit and Write |\n| Context compression | Auto-compact long conversations to stay within model limits |\n| 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 |\n| Multi-agent | Spawn typed sub-agents (coder/reviewer/researcher/…), git worktree isolation, background mode |\n| Skills | Built-in `/commit` · `/review` + custom markdown skills with argument substitution and fork/inline execution |\n| Plugin tools | Register custom tools via `tool_registry.py` |\n| Permission system | `auto` / `accept-all` / `manual` / `plan` modes |\n| Checkpoints | Auto-snapshot conversation + file state after each turn; `/checkpoint` to list, `/checkpoint \u003cid\u003e` to rewind; `/rewind` alias; 100-snapshot sliding window |\n| Plan mode | `/plan \u003cdesc\u003e` enters read-only analysis mode; Claude writes only to the plan file; `EnterPlanMode` / `ExitPlanMode` agent tools for autonomous planning |\n| 36 slash commands | `/model` · `/config` · `/save` · `/cost` · `/memory` · `/skills` · `/agents` · `/voice` · `/proactive` · `/checkpoint` · `/plan` · `/compact` · `/status` · `/doctor` · … |\n| Voice input | Record → transcribe → auto-submit. Backends: `sounddevice` / `arecord` / SoX + `faster-whisper` / `openai-whisper` / OpenAI API. Works fully offline. |\n| 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`. |\n| SSJ Developer Mode | `/ssj` opens a persistent interactive power menu with 10 shortcuts: Brainstorm, TODO viewer, Worker, Expert Debate, Propose, Review, Readme, Commit, Scan, Promote. Stays open between actions; `/command` passthrough supported. Debate shows animated per-round spinner and saves result next to the debated file. |\n| 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. |\n| Telegram bridge | `/telegram \u003ctoken\u003e \u003cchat_id\u003e` starts a bot bridge: receive messages from Telegram, run the model, and reply — all from your phone. Typing indicator, slash command passthrough, and auto-start on launch if configured. |\n| Vision input | `/image [prompt]` captures the clipboard image and sends it to a local vision model (Ollama `llava`, `gemma4`, `llama3.2-vision`). Requires `pip install cheetahclaws[vision]`; Linux also needs `xclip`. |\n| Proactive monitoring | `/proactive [duration]` starts a background sentinel daemon; agent wakes automatically after inactivity, enabling continuous monitoring loops without user prompts |\n| Force quit | 3× Ctrl+C within 2 seconds triggers `os._exit(1)` — kills the process immediately regardless of blocking I/O |\n| 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`. |\n| Context injection | Auto-loads `CLAUDE.md`, git status, cwd, persistent memory |\n| 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 |\n| Cloud sync | `/cloudsave` syncs sessions to private GitHub Gists; auto-sync on exit; load from cloud by Gist ID. No new dependencies (stdlib `urllib`). |\n| Extended Thinking | Toggle on/off for Claude models; native `\u003cthink\u003e` block streaming for local Ollama reasoning models (deepseek-r1, qwen3, gemma4) |\n| Cost tracking | Token usage + estimated USD cost |\n| Non-interactive mode | `--print` flag for scripting / CI |\n\n---\n\n## Supported Models\n\n### Closed-Source (API)\n\n| Provider | Model | Context | Strengths | API Key Env |\n|---|---|---|---|---|\n| **Anthropic** | `claude-opus-4-6` | 200k | Most capable, best for complex reasoning | `ANTHROPIC_API_KEY` |\n| **Anthropic** | `claude-sonnet-4-6` | 200k | Balanced speed \u0026 quality | `ANTHROPIC_API_KEY` |\n| **Anthropic** | `claude-haiku-4-5-20251001` | 200k | Fast, cost-efficient | `ANTHROPIC_API_KEY` |\n| **OpenAI** | `gpt-4o` | 128k | Strong multimodal \u0026 coding | `OPENAI_API_KEY` |\n| **OpenAI** | `gpt-4o-mini` | 128k | Fast, cheap | `OPENAI_API_KEY` |\n| **OpenAI** | `o3-mini` | 200k | Strong reasoning | `OPENAI_API_KEY` |\n| **OpenAI** | `o1` | 200k | Advanced reasoning | `OPENAI_API_KEY` |\n| **Google** | `gemini-2.5-pro-preview-03-25` | 1M | Long context, multimodal | `GEMINI_API_KEY` |\n| **Google** | `gemini-2.0-flash` | 1M | Fast, large context | `GEMINI_API_KEY` |\n| **Google** | `gemini-1.5-pro` | 2M | Largest context window | `GEMINI_API_KEY` |\n| **Moonshot (Kimi)** | `moonshot-v1-8k` | 8k | Chinese \u0026 English | `MOONSHOT_API_KEY` |\n| **Moonshot (Kimi)** | `moonshot-v1-32k` | 32k | Chinese \u0026 English | `MOONSHOT_API_KEY` |\n| **Moonshot (Kimi)** | `moonshot-v1-128k` | 128k | Long context | `MOONSHOT_API_KEY` |\n| **Alibaba (Qwen)** | `qwen-max` | 32k | Best Qwen quality | `DASHSCOPE_API_KEY` |\n| **Alibaba (Qwen)** | `qwen-plus` | 128k | Balanced | `DASHSCOPE_API_KEY` |\n| **Alibaba (Qwen)** | `qwen-turbo` | 1M | Fast, cheap | `DASHSCOPE_API_KEY` |\n| **Alibaba (Qwen)** | `qwq-32b` | 32k | Strong reasoning | `DASHSCOPE_API_KEY` |\n| **Zhipu (GLM)** | `glm-4-plus` | 128k | Best GLM quality | `ZHIPU_API_KEY` |\n| **Zhipu (GLM)** | `glm-4` | 128k | General purpose | `ZHIPU_API_KEY` |\n| **Zhipu (GLM)** | `glm-4-flash` | 128k | Free tier available | `ZHIPU_API_KEY` |\n| **DeepSeek** | `deepseek-chat` | 64k | Strong coding | `DEEPSEEK_API_KEY` |\n| **DeepSeek** | `deepseek-reasoner` | 64k | Chain-of-thought reasoning | `DEEPSEEK_API_KEY` |\n| **MiniMax** | `MiniMax-Text-01` | 1M | Long context, strong reasoning | `MINIMAX_API_KEY` |\n| **MiniMax** | `MiniMax-VL-01` | 1M | Vision + language | `MINIMAX_API_KEY` |\n| **MiniMax** | `abab6.5s-chat` | 256k | Fast, cost-efficient | `MINIMAX_API_KEY` |\n| **MiniMax** | `abab6.5-chat` | 256k | Balanced quality | `MINIMAX_API_KEY` |\n\n### Open-Source (Local via Ollama)\n\n| Model | Size | Strengths | Pull Command |\n|---|---|---|---|\n| `llama3.3` | 70B | General purpose, strong reasoning | `ollama pull llama3.3` |\n| `llama3.2` | 3B / 11B | Lightweight | `ollama pull llama3.2` |\n| `qwen2.5-coder` | 7B / 32B | **Best for coding tasks** | `ollama pull qwen2.5-coder` |\n| `qwen2.5` | 7B / 72B | Chinese \u0026 English | `ollama pull qwen2.5` |\n| `deepseek-r1` | 7B–70B | Reasoning, math | `ollama pull deepseek-r1` |\n| `deepseek-coder-v2` | 16B | Coding | `ollama pull deepseek-coder-v2` |\n| `mistral` | 7B | Fast, efficient | `ollama pull mistral` |\n| `mixtral` | 8x7B | Strong MoE model | `ollama pull mixtral` |\n| `phi4` | 14B | Microsoft, strong reasoning | `ollama pull phi4` |\n| `gemma3` | 4B / 12B / 27B | Google open model | `ollama pull gemma3` |\n| `codellama` | 7B / 34B | Code generation | `ollama pull codellama` |\n| `llava` | 7B / 13B | **Vision** — image understanding | `ollama pull llava` |\n| `llama3.2-vision` | 11B | **Vision** — multimodal reasoning | `ollama pull llama3.2-vision` |\n\n\u003e **Note:** Tool calling requires a model that supports function calling. Recommended local models: `qwen2.5-coder`, `llama3.3`, `mistral`, `phi4`.\n\n\u003e **Reasoning models:** `deepseek-r1`, `qwen3`, and `gemma4` stream native `\u003cthink\u003e` 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.\n\n---\n\n## Installation\n\n### Recommended: install as a global command with `uv`\n\n[uv](https://docs.astral.sh/uv/) installs `cheetahclaws` into an isolated environment and puts it on your PATH so you can run it from anywhere:\n\n```bash\n# Install uv (if not already installed)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Clone and install\ngit clone https://github.com/SafeRL-Lab/clawspring\ncd cheetahclaws\nuv tool install .\n```\n\nAfter that, `cheetahclaws` is available as a global command:\n\n```bash\ncheetahclaws                        # start REPL\ncheetahclaws --model gpt-4o         # choose a model\ncheetahclaws -p \"explain this\"      # non-interactive\n```\n\nTo update after pulling new code:\n\n```bash\nuv tool install . --reinstall\n```\n\nTo uninstall:\n\n```bash\nuv tool uninstall cheetahclaws\n```\n\n### Alternative: run directly from the repo\n\n```bash\ngit clone https://github.com/SafeRL-Lab/clawspring\ncd cheetahclaws\n\npip install -r requirements.txt\n# or manually (sounddevice is optional — only needed for /voice):\npip install anthropic openai httpx rich\npip install sounddevice  # optional: voice input\n\npython cheetahclaws.py\n```\n\n---\n\n## Usage: Closed-Source API Models\n\n### Anthropic Claude\n\nGet your API key at [console.anthropic.com](https://console.anthropic.com).\n\n```bash\nexport ANTHROPIC_API_KEY=sk-ant-api03-...\n\n# Default model (claude-opus-4-6)\ncheetahclaws\n\n# Choose a specific model\ncheetahclaws --model claude-sonnet-4-6\ncheetahclaws --model claude-haiku-4-5-20251001\n\n# Enable Extended Thinking\ncheetahclaws --model claude-opus-4-6 --thinking --verbose\n```\n\n### OpenAI GPT\n\nGet your API key at [platform.openai.com](https://platform.openai.com).\n\n```bash\nexport OPENAI_API_KEY=sk-...\n\ncheetahclaws --model gpt-4o\ncheetahclaws --model gpt-4o-mini\ncheetahclaws --model gpt-4.1-mini\ncheetahclaws --model o3-mini\n```\n\n### Google Gemini\n\nGet your API key at [aistudio.google.com](https://aistudio.google.com).\n\n```bash\nexport GEMINI_API_KEY=AIza...\n\ncheetahclaws --model gemini/gemini-2.0-flash\ncheetahclaws --model gemini/gemini-1.5-pro\ncheetahclaws --model gemini/gemini-2.5-pro-preview-03-25\n```\n\n### Kimi (Moonshot AI)\n\nGet your API key at [platform.moonshot.cn](https://platform.moonshot.cn).\n\n```bash\nexport MOONSHOT_API_KEY=sk-...\n\ncheetahclaws --model kimi/moonshot-v1-32k\ncheetahclaws --model kimi/moonshot-v1-128k\n```\n\n### Qwen (Alibaba DashScope)\n\nGet your API key at [dashscope.aliyun.com](https://dashscope.aliyun.com).\n\n```bash\nexport DASHSCOPE_API_KEY=sk-...\n\ncheetahclaws --model qwen/Qwen3.5-Plus\ncheetahclaws --model qwen/Qwen3-MAX\ncheetahclaws --model qwen/Qwen3.5-Flash\n```\n\n### Zhipu GLM\n\nGet your API key at [open.bigmodel.cn](https://open.bigmodel.cn).\n\n```bash\nexport ZHIPU_API_KEY=...\n\ncheetahclaws --model zhipu/glm-4-plus\ncheetahclaws --model zhipu/glm-4-flash   # free tier\n```\n\n### DeepSeek\n\nGet your API key at [platform.deepseek.com](https://platform.deepseek.com).\n\n```bash\nexport DEEPSEEK_API_KEY=sk-...\n\ncheetahclaws --model deepseek/deepseek-chat\ncheetahclaws --model deepseek/deepseek-reasoner\n```\n\n### MiniMax\n\nGet your API key at [platform.minimaxi.chat](https://platform.minimaxi.chat).\n\n```bash\nexport MINIMAX_API_KEY=...\n\ncheetahclaws --model minimax/MiniMax-Text-01\ncheetahclaws --model minimax/MiniMax-VL-01\ncheetahclaws --model minimax/abab6.5s-chat\n```\n\n---\n\n## Usage: Open-Source Models (Local)\n\n### Option A — Ollama (Recommended)\n\nOllama runs models locally with zero configuration. No API key required.\n\n**Step 1: Install Ollama**\n\n```bash\n# macOS / Linux\ncurl -fsSL https://ollama.com/install.sh | sh\n\n# Or download from https://ollama.com/download\n```\n\n**Step 2: Pull a model**\n\n```bash\n# Best for coding (recommended)\nollama pull qwen2.5-coder          # 4.7 GB (7B)\nollama pull qwen2.5-coder:32b      # 19 GB (32B)\n\n# General purpose\nollama pull llama3.3               # 42 GB (70B)\nollama pull llama3.2               # 2.0 GB (3B)\n\n# Reasoning\nollama pull deepseek-r1            # 4.7 GB (7B)\nollama pull deepseek-r1:32b        # 19 GB (32B)\n\n# Other\nollama pull phi4                   # 9.1 GB (14B)\nollama pull mistral                # 4.1 GB (7B)\n```\n\n**Step 3: Start Ollama server** (runs automatically on macOS; on Linux run manually)\n\n```bash\nollama serve     # starts on http://localhost:11434\n```\n\n**Step 4: Run cheetahclaws**\n\n```bash\ncheetahclaws --model ollama/qwen2.5-coder\ncheetahclaws --model ollama/llama3.3\ncheetahclaws --model ollama/deepseek-r1\n```\n\nOr\n\n```bash\npython cheetahclaws.py --model ollama/qwen2.5-coder\npython cheetahclaws.py --model ollama/llama3.3\npython cheetahclaws.py --model ollama/deepseek-r1\npython cheetahclaws.py --model ollama/qwen3.5:35b\n```\n\n**List your locally available models:**\n\n```bash\nollama list\n```\n\nThen use any model from the list:\n\n```bash\ncheetahclaws --model ollama/\u003cmodel-name\u003e\n```\n\n---\n\n### Option B — LM Studio\n\nLM Studio provides a GUI to download and run models, with a built-in OpenAI-compatible server.\n\n**Step 1:** Download [LM Studio](https://lmstudio.ai) and install it.\n\n**Step 2:** Search and download a model inside LM Studio (GGUF format).\n\n**Step 3:** Go to **Local Server** tab → click **Start Server** (default port: 1234).\n\n**Step 4:**\n\n```bash\ncheetahclaws --model lmstudio/\u003cmodel-name\u003e\n# e.g.:\ncheetahclaws --model lmstudio/phi-4-GGUF\ncheetahclaws --model lmstudio/qwen2.5-coder-7b\n```\n\nThe model name should match what LM Studio shows in the server status bar.\n\n---\n\n### Option C — vLLM / Self-Hosted OpenAI-Compatible Server\n\nFor self-hosted inference servers (vLLM, TGI, llama.cpp server, etc.) that expose an OpenAI-compatible API:\n\nQuick Start for option C:\nStep 1: Start vllm:\n ```\nCUDA_VISIBLE_DEVICES=7 python -m vllm.entrypoints.openai.api_server \\\n      --model Qwen/Qwen2.5-Coder-7B-Instruct \\\n      --host 0.0.0.0 \\\n      --port 8000 \\\n      --enable-auto-tool-choice \\\n      --tool-call-parser hermes\n```\n\n\n Step 2: Start cheetahclaws：\n```\n  export CUSTOM_BASE_URL=http://localhost:8000/v1\n  export CUSTOM_API_KEY=none\n  cheetahclaws --model custom/Qwen/Qwen2.5-Coder-7B-Instruct\n```\n\n\n```bash\n# Example: vLLM serving Qwen2.5-Coder-32B\npython -m vllm.entrypoints.openai.api_server \\\n    --model Qwen/Qwen2.5-Coder-32B-Instruct \\\n    --port 8000\n\n# Then run cheetahclaws pointing to your server:\ncheetahclaws\n```\n\nInside the REPL:\n\n```\n/config custom_base_url=http://localhost:8000/v1\n/config custom_api_key=token-abc123    # skip if no auth\n/model custom/Qwen2.5-Coder-32B-Instruct\n```\n\nOr set via environment:\n\n```bash\nexport CUSTOM_BASE_URL=http://localhost:8000/v1\nexport CUSTOM_API_KEY=token-abc123\n\ncheetahclaws --model custom/Qwen2.5-Coder-32B-Instruct\n```\n\nFor a remote GPU server:\n\n```bash\n/config custom_base_url=http://192.168.1.100:8000/v1\n/model custom/your-model-name\n```\n\n---\n\n## Model Name Format\n\nThree equivalent formats are supported:\n\n```bash\n# 1. Auto-detect by prefix (works for well-known models)\ncheetahclaws --model gpt-4o\ncheetahclaws --model gemini-2.0-flash\ncheetahclaws --model deepseek-chat\n\n# 2. Explicit provider prefix with slash\ncheetahclaws --model ollama/qwen2.5-coder\ncheetahclaws --model kimi/moonshot-v1-128k\n\n# 3. Explicit provider prefix with colon (also works)\ncheetahclaws --model kimi:moonshot-v1-32k\ncheetahclaws --model qwen:qwen-max\n```\n\n**Auto-detection rules:**\n\n| Model prefix | Detected provider |\n|---|---|\n| `claude-` | anthropic |\n| `gpt-`, `o1`, `o3` | openai |\n| `gemini-` | gemini |\n| `moonshot-`, `kimi-` | kimi |\n| `qwen`, `qwq-` | qwen |\n| `glm-` | zhipu |\n| `deepseek-` | deepseek |\n| `MiniMax-`, `minimax-`, `abab` | minimax |\n| `llama`, `mistral`, `phi`, `gemma`, `mixtral`, `codellama` | ollama |\n\n---\n\n## CLI Reference\n\n```\ncheetahclaws [OPTIONS] [PROMPT]\n# or: python cheetahclaws.py [OPTIONS] [PROMPT]\n\nOptions:\n  -p, --print          Non-interactive: run prompt and exit\n  -m, --model MODEL    Override model (e.g. gpt-4o, ollama/llama3.3)\n  --accept-all         Auto-approve all operations (no permission prompts)\n  --verbose            Show thinking blocks and per-turn token counts\n  --thinking           Enable Extended Thinking (Claude only)\n  --version            Print version and exit\n  -h, --help           Show help\n```\n\n**Examples:**\n\n```bash\n# Interactive REPL with default model\ncheetahclaws\n\n# Switch model at startup\ncheetahclaws --model gpt-4o\ncheetahclaws -m ollama/deepseek-r1:32b\n\n# Non-interactive / scripting\ncheetahclaws --print \"Write a Python fibonacci function\"\ncheetahclaws -p \"Explain the Rust borrow checker in 3 sentences\" -m gemini/gemini-2.0-flash\n\n# CI / automation (no permission prompts)\ncheetahclaws --accept-all --print \"Initialize a Python project with pyproject.toml\"\n\n# Debug mode (see tokens + thinking)\ncheetahclaws --thinking --verbose\n```\n\n---\n\n## Slash Commands (REPL)\n\nType `/` and press **Tab** to see all commands with descriptions. Continue typing to filter, then Tab again to auto-complete. After a command name, press **Tab** again to see its subcommands (e.g. `/plugin ` → `install`, `uninstall`, `enable`, …).\n\n| Command | Description |\n|---|---|\n| `/help` | Show all commands |\n| `/clear` | Clear conversation history |\n| `/model` | Show current model + list all available models |\n| `/model \u003cname\u003e` | Switch model (takes effect immediately) |\n| `/config` | Show all current config values |\n| `/config key=value` | Set a config value (persisted to disk) |\n| `/save` | Save session (auto-named by timestamp) |\n| `/save \u003cfilename\u003e` | Save session to named file |\n| `/load` | Interactive list grouped by date; enter number, `1,2,3` to merge, or `H` for full history |\n| `/load \u003cfilename\u003e` | Load a saved session by filename |\n| `/resume` | Restore the last auto-saved session (`mr_sessions/session_latest.json`) |\n| `/resume \u003cfilename\u003e` | Load a specific file from `mr_sessions/` (or absolute path) |\n| `/history` | Print full conversation history |\n| `/context` | Show message count and token estimate |\n| `/cost` | Show token usage and estimated USD cost |\n| `/verbose` | Toggle verbose mode (tokens + thinking) |\n| `/thinking` | Toggle Extended Thinking (Claude only) |\n| `/permissions` | Show current permission mode |\n| `/permissions \u003cmode\u003e` | Set permission mode: `auto` / `accept-all` / `manual` |\n| `/cwd` | Show current working directory |\n| `/cwd \u003cpath\u003e` | Change working directory |\n| `/memory` | List all persistent memories |\n| `/memory \u003cquery\u003e` | Search memories by keyword (ranked by confidence × recency) |\n| `/memory consolidate` | AI-extract up to 3 long-term insights from the current session |\n| `/skills` | List available skills |\n| `/agents` | Show sub-agent task status |\n| `/mcp` | List configured MCP servers and their tools |\n| `/mcp reload` | Reconnect all MCP servers and refresh tools |\n| `/mcp reload \u003cname\u003e` | Reconnect a single MCP server |\n| `/mcp add \u003cname\u003e \u003ccmd\u003e [args]` | Add a stdio MCP server to user config |\n| `/mcp remove \u003cname\u003e` | Remove a server from user config |\n| `/voice` | Record voice, transcribe with Whisper, auto-submit as prompt |\n| `/image [prompt]` | Capture clipboard image and send to vision model with optional prompt |\n| `/voice status` | Show recording and STT backend availability |\n| `/voice lang \u003ccode\u003e` | Set STT language (e.g. `zh`, `en`, `ja`; `auto` to detect) |\n| `/proactive` | Show current proactive polling status (ON/OFF and interval) |\n| `/proactive \u003cduration\u003e` | Enable background sentinel polling (e.g. `5m`, `30s`, `1h`) |\n| `/proactive off` | Disable background polling |\n| `/cloudsave setup \u003ctoken\u003e` | Configure GitHub Personal Access Token for Gist sync |\n| `/cloudsave` | Upload current session to a private GitHub Gist |\n| `/cloudsave push [desc]` | Upload with an optional description |\n| `/cloudsave auto on\\|off` | Toggle auto-upload on `/exit` |\n| `/cloudsave list` | List your cheetahclaws Gists |\n| `/cloudsave load \u003cgist_id\u003e` | Download and restore a session from Gist |\n| `/brainstorm` | Run a multi-persona AI brainstorm; prompts for agent count (2–100, default 5) |\n| `/brainstorm \u003ctopic\u003e` | Focus the brainstorm on a specific topic; prompts for agent count |\n| `/ssj` | Open SSJ Developer Mode — interactive power menu with 10 workflow shortcuts |\n| `/worker` | Auto-implement all pending tasks from `brainstorm_outputs/todo_list.txt` |\n| `/worker \u003cn,m,…\u003e` | Implement specific pending tasks by number (e.g. `/worker 1,4,6`) |\n| `/worker --path \u003cfile\u003e` | Use a custom todo file path instead of the default |\n| `/worker --workers \u003cn\u003e` | Limit the batch to N tasks per run (e.g. `/worker --workers 3`) |\n| `/telegram \u003ctoken\u003e \u003cchat_id\u003e` | Configure and start the Telegram bot bridge |\n| `/telegram` | Start the bridge using previously saved token + chat_id |\n| `/telegram stop` | Stop the Telegram bridge |\n| `/telegram status` | Show whether the bridge is running and the configured chat_id |\n| `/checkpoint` | List all checkpoints (snapshots) for the current session |\n| `/checkpoint \u003cid\u003e` | Rewind to checkpoint — restore files and conversation to that snapshot |\n| `/checkpoint clear` | Delete all checkpoints for the current session |\n| `/rewind` | Alias for `/checkpoint` |\n| `/plan \u003cdescription\u003e` | Enter plan mode: read-only analysis, writes only to the plan file |\n| `/plan` | Show current plan file contents |\n| `/plan done` | Exit plan mode and restore original permissions |\n| `/plan status` | Show whether plan mode is active |\n| `/compact` | Manually compact the conversation (same as auto-compact but user-triggered) |\n| `/compact \u003cfocus\u003e` | Compact with focus instructions (e.g. `/compact keep the auth refactor context`) |\n| `/init` | Create a `CLAUDE.md` template in the current working directory |\n| `/export` | Export the conversation as a Markdown file to `.nano_claude/exports/` |\n| `/export \u003cfilename\u003e` | Export as Markdown or JSON (detected by `.json` extension) |\n| `/copy` | Copy the last assistant response to the clipboard |\n| `/status` | Show version, model, provider, permissions, session ID, token usage, and context % |\n| `/doctor` | Diagnose installation health: Python, git, API key, optional deps, CLAUDE.md, checkpoint disk usage |\n| `/exit` / `/quit` | Exit |\n\n**Switching models inside a session:**\n\n```\n[myproject] ❯ /model\n  Current model: claude-opus-4-6  (provider: anthropic)\n\n  Available models by provider:\n    anthropic     claude-opus-4-6, claude-sonnet-4-6, ...\n    openai        gpt-4o, gpt-4o-mini, o3-mini, ...\n    ollama        llama3.3, llama3.2, phi4, mistral, ...\n    ...\n\n[myproject] ❯ /model gpt-4o\n  Model set to gpt-4o  (provider: openai)\n\n[myproject] ❯ /model ollama/qwen2.5-coder\n  Model set to ollama/qwen2.5-coder  (provider: ollama)\n```\n\n---\n\n## Configuring API Keys\n\n### Method 1: Environment Variables (recommended)\n\n```bash\n# Add to ~/.bashrc or ~/.zshrc\nexport ANTHROPIC_API_KEY=sk-ant-...\nexport OPENAI_API_KEY=sk-...\nexport GEMINI_API_KEY=AIza...\nexport MOONSHOT_API_KEY=sk-...       # Kimi\nexport DASHSCOPE_API_KEY=sk-...      # Qwen\nexport ZHIPU_API_KEY=...             # Zhipu GLM\nexport DEEPSEEK_API_KEY=sk-...       # DeepSeek\nexport MINIMAX_API_KEY=...           # MiniMax\n```\n\n### Method 2: Set Inside the REPL (persisted)\n\n```\n/config anthropic_api_key=sk-ant-...\n/config openai_api_key=sk-...\n/config gemini_api_key=AIza...\n/config kimi_api_key=sk-...\n/config qwen_api_key=sk-...\n/config zhipu_api_key=...\n/config deepseek_api_key=sk-...\n/config minimax_api_key=...\n```\n\nKeys are saved to `~/.cheetahclaws/config.json` and loaded automatically on next launch.\n\n### Method 3: Edit the Config File Directly\n\n```json\n// ~/.cheetahclaws/config.json\n{\n  \"model\": \"qwen/qwen-max\",\n  \"max_tokens\": 8192,\n  \"permission_mode\": \"auto\",\n  \"verbose\": false,\n  \"thinking\": false,\n  \"qwen_api_key\": \"sk-...\",\n  \"kimi_api_key\": \"sk-...\",\n  \"deepseek_api_key\": \"sk-...\",\n  \"minimax_api_key\": \"...\"\n}\n```\n\n---\n\n## Permission System\n\n| Mode | Behavior |\n|---|---|\n| `auto` (default) | Read-only operations always allowed. Prompts before Bash commands and file writes. |\n| `accept-all` | Never prompts. All operations proceed automatically. |\n| `manual` | Prompts before every single operation, including reads. |\n| `plan` | Read-only analysis mode. Only the plan file (`.nano_claude/plans/`) is writable. Entered via `/plan \u003cdesc\u003e` or the `EnterPlanMode` tool. |\n\n**When prompted:**\n\n```\n  Allow: Run: git commit -am \"fix bug\"  [y/N/a(ccept-all)]\n```\n\n- `y` — approve this one action\n- `n` or Enter — deny\n- `a` — approve and switch to `accept-all` for the rest of the session\n\n**Commands always auto-approved in `auto` mode:**\n`ls`, `cat`, `head`, `tail`, `wc`, `pwd`, `echo`, `git status`, `git log`, `git diff`, `git show`, `find`, `grep`, `rg`, `python`, `node`, `pip show`, `npm list`, and other read-only shell commands.\n\n---\n\n## Built-in Tools\n\n### Core Tools\n\n| Tool | Description | Key Parameters |\n|---|---|---|\n| `Read` | Read file with line numbers | `file_path`, `limit`, `offset` |\n| `Write` | Create or overwrite file (shows diff) | `file_path`, `content` |\n| `Edit` | Exact string replacement (shows diff) | `file_path`, `old_string`, `new_string`, `replace_all` |\n| `Bash` | Execute shell command | `command`, `timeout` (default 30s) |\n| `Glob` | Find files by glob pattern | `pattern` (e.g. `**/*.py`), `path` |\n| `Grep` | Regex search in files (uses ripgrep if available) | `pattern`, `path`, `glob`, `output_mode` |\n| `WebFetch` | Fetch and extract text from URL | `url`, `prompt` |\n| `WebSearch` | Search the web via DuckDuckGo | `query` |\n\n### Notebook \u0026 Diagnostics Tools\n\n| Tool | Description | Key Parameters |\n|---|---|---|\n| `NotebookEdit` | Edit a Jupyter notebook (`.ipynb`) cell | `notebook_path`, `new_source`, `cell_id`, `cell_type`, `edit_mode` (`replace`/`insert`/`delete`) |\n| `GetDiagnostics` | Get LSP-style diagnostics for a source file (pyright/mypy/flake8 for Python; tsc/eslint for JS/TS; shellcheck for shell) | `file_path`, `language` (optional override) |\n\n### Memory Tools\n\n| Tool | Description | Key Parameters |\n|---|---|---|\n| `MemorySave` | Save or update a persistent memory | `name`, `type`, `description`, `content`, `scope` |\n| `MemoryDelete` | Delete a memory by name | `name`, `scope` |\n| `MemorySearch` | Search memories by keyword (or AI ranking) | `query`, `scope`, `use_ai`, `max_results` |\n| `MemoryList` | List all memories with age and metadata | `scope` |\n\n### Sub-Agent Tools\n\n| Tool | Description | Key Parameters |\n|---|---|---|\n| `Agent` | Spawn a sub-agent for a task | `prompt`, `subagent_type`, `isolation`, `name`, `model`, `wait` |\n| `SendMessage` | Send a message to a named background agent | `name`, `message` |\n| `CheckAgentResult` | Check status/result of a background agent | `task_id` |\n| `ListAgentTasks` | List all active and finished agent tasks | — |\n| `ListAgentTypes` | List available agent type definitions | — |\n\n### Background \u0026 Autonomy Tools\n\n| Tool | Description | Key Parameters |\n|---|---|---|\n| `SleepTimer` | Schedule a silent background timer; injects an automated wake-up prompt when it fires so the agent can resume monitoring or deferred tasks | `seconds` |\n\n### Skill Tools\n\n| Tool | Description | Key Parameters |\n|---|---|---|\n| `Skill` | Invoke a skill by name from within the conversation | `name`, `args` |\n| `SkillList` | List all available skills with triggers and metadata | — |\n\n### MCP Tools\n\nMCP tools are discovered automatically from configured servers and registered under the name `mcp__\u003cserver\u003e__\u003ctool\u003e`. Claude can use them exactly like built-in tools.\n\n| Example tool name | Where it comes from |\n|---|---|\n| `mcp__git__git_status` | `git` server, `git_status` tool |\n| `mcp__filesystem__read_file` | `filesystem` server, `read_file` tool |\n| `mcp__myserver__my_action` | custom server you configured |\n\n\u003e **Adding custom tools:** See [Architecture Guide](docs/architecture.md#tool-registry) for how to register your own tools.\n\n---\n\n## Memory\n\nThe model can remember things across conversations using the built-in memory system.\n\n### Storage\n\nMemories are stored as individual markdown files in two scopes:\n\n| Scope | Path | Visibility |\n|---|---|---|\n| **User** (default) | `~/.cheetahclaws/memory/` | Shared across all projects |\n| **Project** | `.cheetahclaws/memory/` in cwd | Local to the current repo |\n\nA `MEMORY.md` index (≤ 200 lines / 25 KB) is auto-rebuilt on every save or delete and injected into the system prompt so the model always has an overview of what's been remembered.\n\n### Memory types\n\n| Type | Use for |\n|---|---|\n| `user` | Your role, preferences, background |\n| `feedback` | How you want the model to behave (corrections AND confirmations) |\n| `project` | Ongoing work, deadlines, decisions not in git history |\n| `reference` | Links to external systems (Linear, Grafana, Slack, etc.) |\n\n### Memory file format\n\nEach memory is a markdown file with YAML frontmatter:\n\n```markdown\n---\nname: coding_style\ndescription: Python formatting preferences\ntype: feedback\ncreated: 2026-04-02\nconfidence: 0.95\nsource: user\nlast_used_at: 2026-04-05\nconflict_group: coding_style\n---\nPrefer 4-space indentation and full type hints in all Python code.\n**Why:** user explicitly stated this preference.\n**How to apply:** apply to every Python file written or edited.\n```\n\n**Metadata fields** (new — auto-managed):\n\n| Field | Default | Description |\n|---|---|---|\n| `confidence` | `1.0` | Reliability score 0–1. Explicit user statements = 1.0; inferred preferences ≈ 0.8; auto-consolidated ≈ 0.8 |\n| `source` | `user` | Origin: `user` / `model` / `tool` / `consolidator` |\n| `last_used_at` | — | Updated automatically each time this memory is returned by MemorySearch |\n| `conflict_group` | — | Groups related memories (e.g. `writing_style`) for conflict tracking |\n\n### Conflict detection\n\nWhen `MemorySave` is called with a name that already exists but different content, the system reports the conflict before overwriting:\n\n```\nMemory saved: 'writing_style' [feedback/user]\n⚠ Replaced conflicting memory (was user-sourced, 100% confidence, written 2026-04-01).\n  Old content: Prefer formal, academic style...\n```\n\n### Ranked retrieval\n\n`MemorySearch` ranks results by **confidence × recency** (30-day exponential decay) rather than plain keyword order. Memories that haven't been used recently fade in priority. Each search hit also updates `last_used_at` so frequently-accessed memories stay prominent.\n\n```\nYou: /memory python\n  [feedback/user] coding_style [conf:95% src:user]\n    Python formatting preferences\n    Prefer 4-space indentation and full type hints...\n```\n\n### `/memory consolidate` — auto-extract long-term insights\n\nAfter a meaningful session, run:\n\n```\n[myproject] ❯ /memory consolidate\n  Analyzing session for long-term memories…\n  ✓ Consolidated 2 memory/memories: user_prefers_direct_answers, avoid_trailing_summaries\n```\n\nThe command sends a condensed session transcript to the model and asks it to identify up to **3** insights worth keeping long-term (user preferences, feedback corrections, project decisions). Extracted memories are saved with `confidence: 0.80` and `source: consolidator` — they **never overwrite** an existing memory that already has higher confidence.\n\nGood times to run `/memory consolidate`:\n- After correcting the model's behavior several times in a row\n- After a session where you shared project background or decisions\n- After completing a task with clear planning choices\n\n### Example interaction\n\n```\nYou: Remember that I prefer 4-space indentation and type hints.\nAI: [calls MemorySave] Memory saved: 'coding_style' [feedback/user]\n\nYou: /memory\n  1 memory/memories:\n  [feedback  |user   ] coding_style.md\n    Python formatting preferences\n\nYou: /memory python\n  Found 1 relevant memory for 'python':\n  [feedback/user] coding_style\n    Prefer 4-space indentation and full type hints in all Python code.\n\nYou: /memory consolidate\n  ✓ Consolidated 1 memory: user_prefers_verbose_commit_messages\n```\n\n**Staleness warnings:** Memories older than 1 day show a `⚠ stale` caveat — claims about file:line citations or code state may be outdated; verify before acting.\n\n**AI-ranked search:** `MemorySearch(query=\"...\", use_ai=true)` uses the model to rank candidates by relevance before applying the confidence × recency re-ranking.\n\n---\n\n## Skills\n\nSkills are reusable prompt templates that give the model specialized capabilities. Two built-in skills ship out of the box — no setup required.\n\n**Built-in skills:**\n\n| Trigger | Description |\n|---|---|\n| `/commit` | Review staged changes and create a well-structured git commit |\n| `/review [PR]` | Review code or PR diff with structured feedback |\n\n**Quick start — custom skill:**\n\n```bash\nmkdir -p ~/.cheetahclaws/skills\n```\n\nCreate `~/.cheetahclaws/skills/deploy.md`:\n\n```markdown\n---\nname: deploy\ndescription: Deploy to an environment\ntriggers: [/deploy]\nallowed-tools: [Bash, Read]\nwhen_to_use: Use when the user wants to deploy a version to an environment.\nargument-hint: [env] [version]\narguments: [env, version]\ncontext: inline\n---\n\nDeploy $VERSION to the $ENV environment.\nFull args: $ARGUMENTS\n```\n\nNow use it:\n\n```\nYou: /deploy staging 2.1.0\nAI: [deploys version 2.1.0 to staging]\n```\n\n**Argument substitution:**\n- `$ARGUMENTS` — the full raw argument string\n- `$ARG_NAME` — positional substitution by named argument (first word → first name)\n- Missing args become empty strings\n\n**Execution modes:**\n- `context: inline` (default) — runs inside current conversation history\n- `context: fork` — runs as an isolated sub-agent with fresh history; supports `model` override\n\n**Priority** (highest wins): project-level \u003e user-level \u003e built-in\n\n**List skills:** `/skills` — shows triggers, argument hint, source, and `when_to_use`\n\n**Skill search paths:**\n\n```\n./.cheetahclaws/skills/     # project-level (overrides user-level)\n~/.cheetahclaws/skills/     # user-level\n```\n\n---\n\n## Sub-Agents\n\nThe model can spawn independent sub-agents to handle tasks in parallel.\n\n**Specialized agent types** — built-in:\n\n| Type | Optimized for |\n|---|---|\n| `general-purpose` | Research, exploration, multi-step tasks |\n| `coder` | Writing, reading, and modifying code |\n| `reviewer` | Security, correctness, and code quality analysis |\n| `researcher` | Web search and documentation lookup |\n| `tester` | Writing and running tests |\n\n**Basic usage:**\n```\nYou: Search this codebase for all TODO comments and summarize them.\nAI: [calls Agent(prompt=\"...\", subagent_type=\"researcher\")]\n    Sub-agent reads files, greps for TODOs...\n    Result: Found 12 TODOs across 5 files...\n```\n\n**Background mode** — spawn without waiting, collect result later:\n```\nAI: [calls Agent(prompt=\"run all tests\", name=\"test-runner\", wait=false)]\nAI: [continues other work...]\nAI: [calls CheckAgentResult / SendMessage to follow up]\n```\n\n**Git worktree isolation** — agents work on an isolated branch with no conflicts:\n```\nAgent(prompt=\"refactor auth module\", isolation=\"worktree\")\n```\nThe worktree is auto-cleaned up if no changes were made; otherwise the branch name is reported.\n\n**Custom agent types** — create `~/.cheetahclaws/agents/myagent.md`:\n```markdown\n---\nname: myagent\ndescription: Specialized for X\nmodel: claude-haiku-4-5-20251001\ntools: [Read, Grep, Bash]\n---\nExtra system prompt for this agent type.\n```\n\n**List running agents:** `/agents`\n\nSub-agents have independent conversation history, share the file system, and are limited to 3 levels of nesting.\n\n---\n\n## MCP (Model Context Protocol)\n\nMCP lets you connect any external tool server — local subprocess or remote HTTP — and Claude can use its tools automatically. This is the same protocol Claude Code uses to extend its capabilities.\n\n### Supported transports\n\n| Transport | Config `type` | Description |\n|---|---|---|\n| **stdio** | `\"stdio\"` | Spawn a local subprocess (most common) |\n| **SSE** | `\"sse\"` | HTTP Server-Sent Events stream |\n| **HTTP** | `\"http\"` | Streamable HTTP POST (newer servers) |\n\n### Configuration\n\nPlace a `.mcp.json` file in your project directory **or** edit `~/.cheetahclaws/mcp.json` for user-wide servers.\n\n```json\n{\n  \"mcpServers\": {\n    \"git\": {\n      \"type\": \"stdio\",\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-server-git\"]\n    },\n    \"filesystem\": {\n      \"type\": \"stdio\",\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-server-filesystem\", \"/tmp\"]\n    },\n    \"my-remote\": {\n      \"type\": \"sse\",\n      \"url\": \"http://localhost:8080/sse\",\n      \"headers\": {\"Authorization\": \"Bearer my-token\"}\n    }\n  }\n}\n```\n\nConfig priority: `.mcp.json` (project) overrides `~/.cheetahclaws/mcp.json` (user) by server name.\n\n### Quick start\n\n```bash\n# Install a popular MCP server\npip install uv        # uv includes uvx\nuvx mcp-server-git --help   # verify it works\n\n# Add to user config via REPL\n/mcp add git uvx mcp-server-git\n\n# Or create .mcp.json in your project dir, then:\n/mcp reload\n```\n\n### REPL commands\n\n```\n/mcp                          # list servers + their tools + connection status\n/mcp reload                   # reconnect all servers, refresh tool list\n/mcp reload git               # reconnect a single server\n/mcp add myserver uvx mcp-server-x   # add stdio server\n/mcp remove myserver          # remove from user config\n```\n\n### How Claude uses MCP tools\n\nOnce connected, Claude can call MCP tools directly:\n\n```\nYou: What files changed in the last git commit?\nAI: [calls mcp__git__git_diff_staged()]\n    → shows diff output from the git MCP server\n```\n\nTool names follow the pattern `mcp__\u003cserver_name\u003e__\u003ctool_name\u003e`. All characters\nthat are not alphanumeric or `_` are automatically replaced with `_`.\n\n### Popular MCP servers\n\n| Server | Install | Provides |\n|---|---|---|\n| `mcp-server-git` | `uvx mcp-server-git` | git operations (status, diff, log, commit) |\n| `mcp-server-filesystem` | `uvx mcp-server-filesystem \u003cpath\u003e` | file read/write/list |\n| `mcp-server-fetch` | `uvx mcp-server-fetch` | HTTP fetch tool |\n| `mcp-server-postgres` | `uvx mcp-server-postgres \u003cconn-str\u003e` | PostgreSQL queries |\n| `mcp-server-sqlite` | `uvx mcp-server-sqlite --db-path x.db` | SQLite queries |\n| `mcp-server-brave-search` | `uvx mcp-server-brave-search` | Brave web search |\n\n\u003e Browse the full registry at [modelcontextprotocol.io/servers](https://modelcontextprotocol.io/servers)\n\n---\n\n## Plugin System\n\nThe `plugin/` package lets you extend cheetahclaws with additional tools, skills, and MCP servers from git repositories or local directories.\n\n### Install a plugin\n\n```bash\n/plugin install my-plugin@https://github.com/user/my-plugin\n/plugin install local-plugin@/path/to/local/plugin\n```\n\n### Manage plugins\n\n```bash\n/plugin                   # list installed plugins\n/plugin enable my-plugin  # enable a disabled plugin\n/plugin disable my-plugin # disable without uninstalling\n/plugin disable-all       # disable all plugins\n/plugin update my-plugin  # pull latest from git\n/plugin uninstall my-plugin\n/plugin info my-plugin    # show manifest details\n```\n\n### Plugin recommendation engine\n\n```bash\n/plugin recommend                    # auto-detect from project files\n/plugin recommend \"docker database\"  # recommend by keyword context\n```\n\nThe engine matches your context against a curated marketplace (git-tools, python-linter, docker-tools, sql-tools, test-runner, diagram-tools, aws-tools, web-scraper) using tag and keyword scoring.\n\n### Plugin manifest (plugin.json)\n\n```json\n{\n  \"name\": \"my-plugin\",\n  \"version\": \"0.1.0\",\n  \"description\": \"Does something useful\",\n  \"author\": \"you\",\n  \"tags\": [\"git\", \"python\"],\n  \"tools\": [\"tools\"],        // Python module(s) that export TOOL_DEFS\n  \"skills\": [\"skills/my.md\"],\n  \"mcp_servers\": {},\n  \"dependencies\": [\"httpx\"]  // pip packages\n}\n```\n\nAlternatively use YAML frontmatter in `PLUGIN.md`.\n\n### Scopes\n\n| Scope | Location | Config |\n|-------|----------|--------|\n| user (default) | `~/.cheetahclaws/plugins/` | `~/.cheetahclaws/plugins.json` |\n| project | `.cheetahclaws/plugins/` | `.cheetahclaws/plugins.json` |\n\nUse `--project` flag: `/plugin install name@url --project`\n\n---\n\n## AskUserQuestion Tool\n\nClaude can pause mid-task and interactively ask you a question before proceeding.\n\n**Example invocation by Claude:**\n```json\n{\n  \"tool\": \"AskUserQuestion\",\n  \"question\": \"Which database should I use?\",\n  \"options\": [\n    {\"label\": \"SQLite\", \"description\": \"Simple, file-based\"},\n    {\"label\": \"PostgreSQL\", \"description\": \"Full-featured, requires server\"}\n  ],\n  \"allow_freetext\": true\n}\n```\n\n**What you see in the terminal:**\n```\n❓ Question from assistant:\n   Which database should I use?\n\n  [1] SQLite — Simple, file-based\n  [2] PostgreSQL — Full-featured, requires server\n  [0] Type a custom answer\n\nYour choice (number or text):\n```\n\n- Select by number or type free text directly\n- Claude receives your answer and continues the task\n- 5-minute timeout (returns \"(no answer — timeout)\" if unanswered)\n\n---\n\n## Task Management\n\nThe `task/` package gives Claude (and you) a structured task list for tracking multi-step work within a session.\n\n### Tools available to Claude\n\n| Tool | Parameters | What it does |\n|------|-----------|--------------|\n| `TaskCreate` | `subject`, `description`, `active_form?`, `metadata?` | Create a task; returns `#id created: subject` |\n| `TaskUpdate` | `task_id`, `subject?`, `description?`, `status?`, `owner?`, `add_blocks?`, `add_blocked_by?`, `metadata?` | Update any field; `status='deleted'` removes the task |\n| `TaskGet` | `task_id` | Return full details of one task |\n| `TaskList` | _(none)_ | List all tasks with status icons and pending blockers |\n\n**Valid statuses:** `pending` → `in_progress` → `completed` / `cancelled` / `deleted`\n\n### Dependency edges\n\n```\nTaskUpdate(task_id=\"3\", add_blocked_by=[\"1\",\"2\"])\n# Task 3 is now blocked by tasks 1 and 2.\n# Reverse edges are set automatically: tasks 1 and 2 get task 3 in their \"blocks\" list.\n```\n\nCompleted tasks are treated as resolved — `TaskList` hides their blocking effect on dependents.\n\n### Persistence\n\nTasks are saved to `.cheetahclaws/tasks.json` in the current working directory after every mutation and reloaded on first access.\n\n### REPL commands\n\n```\n/tasks                    list all tasks\n/tasks create \u003csubject\u003e   quick-create a task\n/tasks start \u003cid\u003e         mark in_progress\n/tasks done \u003cid\u003e          mark completed\n/tasks cancel \u003cid\u003e        mark cancelled\n/tasks delete \u003cid\u003e        remove a task\n/tasks get \u003cid\u003e           show full details\n/tasks clear              delete all tasks\n```\n\n### Typical Claude workflow\n\n```\nUser: implement the login feature\n\nClaude:\n  TaskCreate(subject=\"Design auth schema\", description=\"JWT vs session\")  → #1\n  TaskCreate(subject=\"Write login endpoint\", description=\"POST /auth/login\") → #2\n  TaskCreate(subject=\"Write tests\", description=\"Unit + integration\") → #3\n  TaskUpdate(task_id=\"2\", add_blocked_by=[\"1\"])\n  TaskUpdate(task_id=\"3\", add_blocked_by=[\"2\"])\n\n  TaskUpdate(task_id=\"1\", status=\"in_progress\", active_form=\"Designing schema\")\n  ... (does the work) ...\n  TaskUpdate(task_id=\"1\", status=\"completed\")\n  TaskList()  → task 2 is now unblocked\n  ...\n```\n\n---\n\n## Voice Input\n\nCheetahClaws v3.05 adds a fully offline voice-to-prompt pipeline. Speak your request — it is transcribed and submitted as if you had typed it.\n\n### Quick start\n\n```bash\n# 1. Install a recording backend (choose one)\npip install sounddevice        # recommended: cross-platform, no extra binary\n# sudo apt install alsa-utils  # Linux arecord fallback\n# sudo apt install sox         # SoX rec fallback\n\n# 2. Install a local STT backend (recommended — works offline, no API key)\npip install faster-whisper numpy\n\n# 3. Start CheetahClaws and speak\ncheetahclaws\n[myproject] ❯ /voice\n  🎙  Listening… (speak now, auto-stops on silence, Ctrl+C to cancel)\n  🎙  ████\n✓  Transcribed: \"fix the authentication bug in user.py\"\n[auto-submitting…]\n```\n\n### STT backends (tried in order)\n\n| Backend | Install | Notes |\n|---|---|---|\n| `faster-whisper` | `pip install faster-whisper` | **Recommended** — local, offline, fastest, GPU optional |\n| `openai-whisper` | `pip install openai-whisper` | Local, offline, original OpenAI model |\n| OpenAI Whisper API | set `OPENAI_API_KEY` | Cloud, requires internet + API key |\n\nOverride the Whisper model size with `NANO_CLAUDE_WHISPER_MODEL` (default: `base`):\n\n```bash\nexport NANO_CLAUDE_WHISPER_MODEL=small   # better accuracy, slower\nexport NANO_CLAUDE_WHISPER_MODEL=tiny    # fastest, lightest\n```\n\n### Recording backends (tried in order)\n\n| Backend | Install | Notes |\n|---|---|---|\n| `sounddevice` | `pip install sounddevice` | **Recommended** — cross-platform, Python-native |\n| `arecord` | `sudo apt install alsa-utils` | Linux ALSA, no pip needed |\n| `sox rec` | `sudo apt install sox` / `brew install sox` | Built-in silence detection |\n\n### Keyterm boosting\n\nBefore each recording, CheetahClaws extracts coding vocabulary from:\n- **Git branch** (e.g. `feat/voice-input` → \"feat\", \"voice\", \"input\")\n- **Project root name** (e.g. \"cheetahclaws\")\n- **Recent source file stems** (e.g. `authentication_handler.py` → \"authentication\", \"handler\")\n- **Global coding terms**: `MCP`, `grep`, `TypeScript`, `OAuth`, `regex`, `gRPC`, …\n\nThese are passed as Whisper's `initial_prompt` so the STT engine prefers correct spellings of coding terms.\n\n### Commands\n\n| Command | Description |\n|---|---|\n| `/voice` | Record voice and auto-submit the transcript as your next prompt |\n| `/voice status` | Show which recording and STT backends are available |\n| `/voice lang \u003ccode\u003e` | Set transcription language (`en`, `zh`, `ja`, `de`, `fr`, … default: `auto`) |\n\n### How it compares to Claude Code\n\n| | Claude Code | CheetahClaws v3.05 |\n|---|---|---|\n| STT service | Anthropic private WebSocket (`voice_stream`) | `faster-whisper` / `openai-whisper` / OpenAI API |\n| Requires Anthropic OAuth | Yes | **No** |\n| Works offline | No | **Yes** (with local Whisper) |\n| Keyterm hints | Deepgram `keyterms` param | Whisper `initial_prompt` (git + files + vocab) |\n| Language support | Server-allowlisted codes | Any language Whisper supports |\n\n---\n\n## Brainstorm\n\n`/brainstorm` runs a structured multi-persona AI debate over your project, then synthesizes all perspectives into an actionable plan.\n\n### How it works\n\n1. **Context snapshot** — reads `README.md`, `CLAUDE.md`, and root file listing from the current working directory.\n2. **Agent count** — you are prompted to choose how many agents (2–100, default 5). Press Enter to use the default.\n3. **Dynamic persona generation** — the model generates N expert roles tailored to your topic. Software topics get architects and engineers; geopolitics gets analysts, diplomats, and economists; business gets strategists and market experts. Falls back to built-in tech personas if generation fails.\n4. **Agents debate sequentially**, each building on the previous responses.\n5. **Output saved** to `brainstorm_outputs/brainstorm_YYYYMMDD_HHMMSS.md` in the current directory.\n6. **Synthesis** — the main agent reads the saved file and produces a prioritized Master Plan.\n\n**Example personas by topic:**\n\n| Topic | Example Generated Personas |\n|---|---|\n| Software architecture | 🏗️ Architect · 💡 Product Innovator · 🛡️ Security Engineer · 🔧 Code Quality Lead · ⚡ Performance Specialist |\n| US-Iran geopolitics | 🌍 Geopolitical Analyst · ⚖️ International Law Expert · 💰 Energy Economist · 🎖️ Military Strategist · 🕊️ Conflict Mediator |\n| Business strategy | 📈 Market Strategist · 💼 Operations Lead · 🔍 Competitive Intelligence · 💡 Innovation Director · 📊 Financial Analyst |\n\n### Usage\n\n```\n[myproject] ❯ /brainstorm\n  How many agents? (2-100, default 5) \u003e 5\n\n[myproject] ❯ /brainstorm improve plugin architecture\n  How many agents? (2-100, default 5) \u003e 3\n\n[myproject] ❯ /brainstorm US-Iran geopolitics\n  How many agents? (2-100, default 5) \u003e 7\n```\n\n### Example output\n\n```\n[myproject] ❯ /brainstorm medical research funding\n  How many agents? (2-100, default 5) \u003e 3\nGenerating 3 topic-appropriate expert personas...\nStarting 3-Agent Brainstorming Session on: medical research funding\nGenerating diverse perspectives...\n🩺 Clinical Trials Director is thinking...\n  └─ Perspective captured.\n⚖️ Medical Ethics Committee Member is thinking...\n  └─ Perspective captured.\n💰 Health Economics Policy Analyst is thinking...\n  └─ Perspective captured.\n✓  Brainstorming complete! Results saved to brainstorm_outputs/brainstorm_20260405_224117.md\n\n   ── Analysis from Main Agent ──\n[synthesized Master Plan streams here…]\n```\n\n### Notes\n\n- Brainstorm uses the **currently selected model** (`/model` to check). A capable model (Claude Sonnet/Opus, GPT-4o, or a large local model) gives the best results.\n- With many agents (20+) the session can take several minutes depending on model speed.\n- Install `faker` (`pip install faker`) for randomized persona names; falls back to built-in names otherwise.\n- Output files accumulate in `brainstorm_outputs/` — already added to `.gitignore` by v3.05.5.\n- If output looks garbled in SSH (repeated lines), run `/config rich_live=false` to disable Rich Live streaming.\n\n---\n\n## SSJ Developer Mode\n\n`/ssj` opens a persistent interactive power menu — a single entry point for the most common development workflows, so you never have to remember command names.\n\n\u003cdiv align=center\u003e\n\u003cimg src=\"https://github.com/SafeRL-Lab/clawspring/blob/main/docs/ssj_demo.gif\" width=\"850\"/\u003e\n\u003c/div\u003e\n\n### Menu options\n\n| # | Name | What it does |\n|---|------|--------------|\n| 1 | 💡 Brainstorm | Multi-persona AI debate → Master Plan → auto-generates `brainstorm_outputs/todo_list.txt` |\n| 2 | 📋 Show TODO | View `brainstorm_outputs/todo_list.txt` with ✓/○ indicators and pending task numbers |\n| 3 | 👷 Worker | Auto-implement pending tasks (all, or select by number) |\n| 4 | 🧠 Debate | Pick a file and choose agent count — expert panel debates design round-by-round; result saved next to the file |\n| 5 | ✨ Propose | Pick a file — AI proposes specific improvements with code |\n| 6 | 🔎 Review | Pick a file — structured code review with 1–10 ratings per dimension |\n| 7 | 📘 Readme | Pick a file — auto-generate a professional README for it |\n| 8 | 💬 Commit | Analyse git diff and suggest a conventional commit message |\n| 9 | 🧪 Scan | Summarise all staged/unstaged changes and suggest next steps |\n| 10 | 📝 Promote | Read the latest brainstorm output → convert ideas to `todo_list.txt` tasks |\n| 0 | 🚪 Exit | Return to the main REPL |\n\n### Usage\n\n```\n[myproject] ❯ /ssj\n\n╭─ SSJ Developer Mode ⚡ ─────────────────────────\n│\n│   1.  💡  Brainstorm — Multi-persona AI debate\n│   2.  📋  Show TODO  — View todo_list.txt\n│   3.  👷  Worker     — Auto-implement pending tasks\n│   4.  🧠  Debate     — Expert debate on a file\n│   5.  ✨  Propose    — AI improvement for a file\n│   6.  🔎  Review     — Quick file analysis\n│   7.  📘  Readme     — Auto-generate README.md\n│   8.  💬  Commit     — AI-suggested commit message\n│   9.  🧪  Scan       — Analyze git diff\n│  10.  📝  Promote    — Idea to tasks\n│   0.  🚪  Exit SSJ Mode\n│\n╰──────────────────────────────────────────────\n\n  ⚡ SSJ » 1\n  Topic (Enter for general): cheetahclaws plugin system\n\n  # → Brainstorm spins up, saves to brainstorm_outputs/, generates todo_list.txt\n  # → Menu re-opens automatically after each action\n\n  ⚡ SSJ » 2\n  # → Shows numbered pending tasks from brainstorm_outputs/todo_list.txt\n\n  ⚡ SSJ » 3\n  Task # (Enter for all, or e.g. 1,4,6): 2\n  # → Worker implements task #2 and marks it done\n```\n\n### Slash command passthrough\n\nAny `/command` typed at the `⚡ SSJ »` prompt is passed through to the REPL:\n\n```\n  ⚡ SSJ » /model gpt-4o\n  # → switches model, then re-opens SSJ menu\n\n  ⚡ SSJ » /exit\n  # → exits cheetahclaws immediately\n```\n\n### Worker command\n\n`/worker` (also accessible as SSJ option 3) reads `brainstorm_outputs/todo_list.txt` and auto-implements each pending task:\n\n```\n[myproject] ❯ /worker\n  ✓ Worker starting — 3 task(s) to implement\n    1. ○ Add animated brainstorm spinner\n    2. ○ Implement Telegram typing indicator\n    3. ○ Write SSJ demo GIF for README\n\n  ── Worker (1/3): Add animated brainstorm spinner ──\n  [model reads code, implements the change, marks task done]\n\n[myproject] ❯ /worker 2,3\n  # Implement only tasks 2 and 3\n\n[myproject] ❯ /worker --path docs/tasks.md\n  # Use a custom todo file\n\n[myproject] ❯ /worker --workers 2\n  # Process only the first 2 pending tasks this run\n```\n\n**Smart path detection** — if you pass a brainstorm output file (`.md`) by mistake, Worker detects it and offers to redirect to the matching `todo_list.txt` in the same folder. If that file does not yet exist, it offers to generate `todo_list.txt` from the brainstorm output first (SSJ Promote), then run Worker automatically.\n\n### Debate command\n\nSSJ option 4 runs a structured multi-round expert debate on any file:\n\n```\n  ⚡ SSJ » 4\n\n  Files in brainstorm_outputs/:\n    1. brainstorm_20260406_143022.md\n    2. cheetahclaws.py\n\n  File to debate #: 2\n  Number of debate agents (Enter for 2): 3\n  ℹ Debate result will be saved to: cheetahclaws_debate_143055.md\n\n⚔️  Assembling expert panel...\n  Expert 1: 🏗️ Architecture Lead — focus: system design \u0026 modularity\n  Expert 2: 🔐 Security Engineer — focus: attack surface \u0026 input validation\n  Expert 3: ⚡ Performance Specialist — focus: latency \u0026 memory usage\n\n⚔️  Round 1/5 — Expert 1 thinking...\n  [Architecture Lead gives opening argument...]\n\n💬  Round 1/5 — Expert 2 formulating...\n  [Security Engineer responds...]\n  ...\n\n📜  Drafting final consensus...\n  [model writes consensus + saves transcript]\n✓ Debate complete. Saved to cheetahclaws_debate_143055.md\n```\n\n- Agent count is configurable (minimum 2, default 2). Rounds are set to `agents × 2 − 1` for a full open-close structure.\n- An animated spinner shows the current round and expert (`⚔️ Round 2/3 — Expert 1 thinking...`), stopping the moment that expert starts outputting.\n- The full debate transcript and ranked consensus are saved to `\u003cfilename\u003e_debate_HHMMSS.md` **in the same directory as the debated file**.\n\n---\n\n## Telegram Bridge\n\n`/telegram` turns cheetahclaws into a Telegram bot — receive messages from your phone, run the model with full tool access, and reply automatically.\n\n\u003cdiv align=center\u003e\n\u003cimg src=\"https://github.com/SafeRL-Lab/clawspring/blob/main/docs/telegram_demo.gif\" width=\"850\"/\u003e\n\u003c/div\u003e\n\n### Setup (one-time)\n\n1. Open [@BotFather](https://t.me/BotFather) in Telegram → `/newbot` → copy the token.\n2. Send any message to your new bot, then open `https://api.telegram.org/bot\u003cTOKEN\u003e/getUpdates` and note your `chat.id`.\n3. Configure cheetahclaws:\n\n```\n[myproject] ❯ /telegram \u003cyour_bot_token\u003e \u003cyour_chat_id\u003e\n  ✓ Telegram config saved.\n  ✓ Connected to @your_bot_name. Starting bridge...\n  ✓ Telegram bridge active. Chat ID: 123456789\n  ℹ Send messages to your bot — they'll be processed here.\n  ℹ Stop with /telegram stop or send /stop in Telegram.\n```\n\nToken and chat_id are saved to `~/.cheetahclaws/config.json`. On next launch the bridge **auto-starts** if configured — the startup banner shows `flags: [telegram]`.\n\n### How it works\n\n```\nPhone (Telegram)                  cheetahclaws terminal\n──────────────────                ──────────────────────────\n\"List Python files\"      →        📩 Telegram: List Python files\n                                  [typing indicator sent...]\n                                  ⚙ Glob(**/*.py) → 5 files\n                                  ⚙ response assembled\n                          ←       \"agent.py, tools.py, ...\"\n```\n\n- **Typing indicator** is sent every 4 seconds while the model processes, so the chat feels responsive.\n- **Unauthorized senders** receive `⛔ Unauthorized.` and their messages are dropped.\n- **Slash command passthrough**: send `/cost`, `/model gpt-4o`, `/clear`, etc. from Telegram and they execute in cheetahclaws.\n- **`/stop` or `/off`** sent from Telegram stops the bridge gracefully.\n\n### Commands\n\n| Command | Description |\n|---|---|\n| `/telegram \u003ctoken\u003e \u003cchat_id\u003e` | Configure token + chat_id, then start the bridge |\n| `/telegram` | Start the bridge using saved config |\n| `/telegram status` | Show running state and chat_id |\n| `/telegram stop` | Stop the bridge |\n\n### Auto-start\n\nIf both `telegram_token` and `telegram_chat_id` are set in `~/.cheetahclaws/config.json`, the bridge starts automatically on every cheetahclaws launch:\n\n```\n╭─ CheetahClaws ────────────────────────────────╮\n│  Model:       claude-opus-4-6\n│  Permissions: auto   flags: [telegram]\n│  Type /help for commands, Ctrl+C to cancel        │\n╰───────────────────────────────────────────────────╯\n✓ Telegram bridge started (auto). Bot: @your_bot_name\n```\n\n---\n\n## Proactive Background Monitoring\n\nCheetahClaws v3.05.2 adds a **sentinel daemon** that automatically wakes the agent after a configurable period of inactivity — no user prompt required. This enables use cases like continuous log monitoring, market script polling, or scheduled code checks.\n\n### Quick start\n\n```\n[myproject] ❯ /proactive 5m\nProactive background polling: ON  (triggering every 300s of inactivity)\n\n[myproject] ❯ keep monitoring the build log and alert me if errors appear\n\n╭─ Claude ● ─────────────────────────\n│ Understood. I'll check the build log each time I wake up.\n\n[Background Event Triggered]\n╭─ Claude ● ─────────────────────────\n│ ⚙ Bash(tail -50 build.log)\n│ ✓ → Build failed: ImportError in auth.py line 42\n│ **Action needed:** fix the import before the next CI run.\n```\n\n### Commands\n\n| Command | Description |\n|---|---|\n| `/proactive` | Show current status (ON/OFF and interval) |\n| `/proactive 5m` | Enable — trigger every 5 minutes of inactivity |\n| `/proactive 30s` | Enable — trigger every 30 seconds |\n| `/proactive 1h` | Enable — trigger every hour |\n| `/proactive off` | Disable sentinel polling |\n\nDuration suffix: `s` = seconds, `m` = minutes, `h` = hours. Plain integer = seconds.\n\n### How it works\n\n- A background daemon thread starts when the REPL launches (paused by default).\n- The daemon checks elapsed time since the last user or agent interaction every second.\n- When the inactivity threshold is reached, it calls the agent with a wake-up prompt.\n- The `threading.Lock` used by the main agent loop ensures wake-ups never interrupt an active session — they queue and fire after the current turn completes.\n- Watcher exceptions are logged via `traceback` so failures are visible and debuggable.\n\n### Complements SleepTimer\n\n| | `SleepTimer` | `/proactive` |\n|---|---|---|\n| Who initiates | The agent | The user |\n| Trigger | After a fixed delay from now | After N seconds of inactivity |\n| Use case | \"Check back in 10 minutes\" | \"Keep watching until I stop typing\" |\n\n---\n\n## Checkpoint System\n\nCheetahClaws automatically snapshots your conversation and any edited files after every turn, so you can always rewind to an earlier state.\n\n### How it works\n\n- **Auto-snapshot** — after each turn, the checkpoint system saves the current conversation messages, token counts, and a copy-on-write backup of every file that was written or edited that turn.\n- **100-snapshot sliding window** — older snapshots are automatically evicted when the limit is reached.\n- **Throttling** — if nothing changed (no new messages, no file edits) since the last snapshot, the snapshot is skipped.\n- **Initial snapshot** — captured at session start, so you can always rewind to a clean slate.\n- **Storage** — `~/.nano_claude/checkpoints/\u003csession_id\u003e/` (snapshots metadata + backup files).\n\n### Commands\n\n| Command | Description |\n|---|---|\n| `/checkpoint` | List all snapshots for the current session |\n| `/checkpoint \u003cid\u003e` | Rewind: restore files to their state at snapshot `\u003cid\u003e` and trim conversation to that point |\n| `/checkpoint clear` | Delete all snapshots for the current session |\n| `/rewind` | Alias for `/checkpoint` |\n\n### Example\n\n```\n[myproject] ❯ /checkpoint\n  Checkpoints (4 total):\n  #1  [turn 0] 14:02:11  \"(initial state)\"           0 files\n  #2  [turn 1] 14:03:45  \"Create app.py\"              1 file\n  #3  [turn 2] 14:05:12  \"Add error handling\"         1 file\n  #4  [turn 3] 14:06:30  \"Explain the code\"           1 file\n\n[myproject] ❯ /checkpoint 2\n  Rewound to checkpoint #2 (turn 1)\n  Restored: app.py\n  Conversation trimmed to 2 messages.\n```\n\n---\n\n## Plan Mode\n\nPlan mode is a structured workflow for tackling complex, multi-file tasks: Claude first analyses the codebase in a read-only phase and writes an explicit plan, then the user approves before implementation begins.\n\n### How it works\n\nIn plan mode:\n- **Only reads** are permitted (`Read`, `Glob`, `Grep`, `WebFetch`, `WebSearch`, safe `Bash` commands).\n- **Writes are blocked** everywhere **except** the dedicated plan file (`.nano_claude/plans/\u003csession_id\u003e.md`).\n- Blocked write attempts produce a helpful message rather than prompting the user.\n- The system prompt is augmented with plan mode instructions.\n- After compaction, the plan file context is automatically restored.\n\n### Slash command workflow\n\n```\n[myproject] ❯ /plan add WebSocket support\n  Plan mode activated.\n  Plan file: .nano_claude/plans/a3f9c1b2.md\n  Reads allowed. All other writes blocked (except plan file).\n\n[myproject] ❯ \u003cdescribe your task\u003e\n  [Claude reads files, builds understanding, writes plan to plan file]\n\n[myproject] ❯ /plan\n  # Plan: Add WebSocket support\n\n  ## Phase 1: Create ws_handler.py\n  ## Phase 2: Modify server.py to mount the handler\n  ## Phase 3: Add tests\n\n[myproject] ❯ /plan done\n  Plan mode exited. Permission mode restored to: auto\n  Review the plan above and start implementing when ready.\n\n[myproject] ❯ /plan status\n  Plan mode: INACTIVE  (permission mode: auto)\n```\n\n### Agent tool workflow (autonomous)\n\nClaude can autonomously enter and exit plan mode using the `EnterPlanMode` and `ExitPlanMode` tools — both are auto-approved in all permission modes:\n\n```\nUser: Refactor the authentication module\n\nClaude: [calls EnterPlanMode(task_description=\"Refactor auth module\")]\n  → reads auth.py, users.py, tests/test_auth.py ...\n  → writes plan to .nano_claude/plans/...\n  [calls ExitPlanMode()]\n  → \"Here is my plan. Please review and approve before I begin.\"\n\nUser: Looks good, go ahead.\nClaude: [implements the plan]\n```\n\n### Commands\n\n| Command | Description |\n|---|---|\n| `/plan \u003cdescription\u003e` | Enter plan mode with a task description |\n| `/plan` | Print the current plan file contents |\n| `/plan done` | Exit plan mode, restore previous permissions |\n| `/plan status` | Show whether plan mode is active |\n\n---\n\n## Context Compression\n\nLong conversations are automatically compressed to stay within the model's context window.\n\n**Two layers:**\n\n1. **Snip** — Old tool outputs (file reads, bash results) are truncated after a few turns. Fast, no API cost.\n2. **Auto-compact** — When token usage exceeds 70% of the context limit, older messages are summarized by the model into a concise recap.\n\nThis happens transparently. You don't need to do anything.\n\n**Manual compaction** — You can also trigger compaction at any time with `/compact`. An optional focus string tells the summarizer what context to prioritize:\n\n```\n[myproject] ❯ /compact\n  Compacted: ~12400 → ~3200 tokens (~9200 saved)\n\n[myproject] ❯ /compact keep the WebSocket implementation details\n  Compacted: ~11800 → ~3100 tokens (~8700 saved)\n```\n\nIf plan mode is active, the plan file context is automatically restored after any compaction.\n\n---\n\n## Diff View\n\nWhen the model edits or overwrites a file, you see a git-style diff:\n\n```diff\n  Changes applied to config.py:\n\n--- a/config.py\n+++ b/config.py\n@@ -12,7 +12,7 @@\n     \"model\": \"claude-opus-4-6\",\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaferl-lab%2Fcheetahclaws","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsaferl-lab%2Fcheetahclaws","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaferl-lab%2Fcheetahclaws/lists"}