CheetahClaws: a Python agent harness for long-horizon, multi-model tool use

What CheetahClaws actually solves for agent builders

Running an agent over many turns is not one problem, it is several stacked ones. The model has to be swappable without rewriting the tool layer. Tools have to be described to the model without blowing the context window. The session has to survive a crash. And every action that touches the filesystem or runs a shell command has to be gated in a way a human can actually review.

CheetahClaws positions itself as a harness rather than a framework. The pyproject.toml describes it as "Agent Harness Infrastructure for Long-Horizon, Multi-Model, and Tool-Using AI Systems", and the repository layout backs that up: a cheetahclaws/ package, a desktop/ Electron wrapper, demos/, examples/, and a docs/ tree with per-language READMEs. The intended user is someone who already has a model key or a local Ollama instance and wants a working agent loop, not someone building an agent runtime from primitives.

The multi-model claim is concrete rather than aspirational. The news entries describe OpenRouter becoming a first-class provider with `/model openrouter/<vendor>/<model>`, a key read from `OPENROUTER_API_KEY` or set through `/config openrouter_api_key=sk-or-...`, and an `@<provider>[/<quantization>]` suffix that pins which upstream serves the request. That suffix is sent as OpenRouter's `provider` request-body object, so the model field stays a real catalog ID. Four routing fixes shipped alongside it, including one where the provider was re-derived from an already-stripped model string and leaked DeepSeek-only request fields into OpenRouter calls. That is a useful detail: the project treats provider routing as a correctness problem, not just a string prefix.

The harness loop: REPL, tool profiles and session state

The core interaction is a REPL. `cheetahclaws` with no arguments starts a chat session, and slash commands configure it at runtime. `/model` opens a Tab-completion picker that covers provider/model pairs and a two-level LiteLLM tree. `/config` sets keys and behaviour switches such as `input_suggest=false` and `tool_profile=standard`.

The tool surface is the part with the most design thought in it. `tool_profile` selects how many tool schemas are sent each turn. The four documented values are `full` (the default, nothing hidden), `standard` (described as compact coding), `research`, and `orchestration`. The stated purpose is cutting prompt tokens on small-context models. This is a real trade-off and the documentation is honest about it: the default hides nothing, so anyone optimizing for a small local model has to opt in and accept that some tools become invisible to the model.

Session durability is handled at two levels. Sessions autosave every turn using an atomic write plus fsync, so a crash or power loss mid-conversation stays recoverable through `/resume`. A louder daily and history save happens once on exit. That split is sensible: the frequent path is cheap and silent, the expensive path is rare.

There is also a next-prompt ghost text feature, which is unusual enough to mention. After each reply, the auxiliary model drafts the line you would most likely type next and shows it dimmed at the prompt. Tab or the right arrow accepts it, typing overrides it, and Enter alone never submits it. Drafting runs on a background thread and stays silent on failure, so a missing key or model simply produces no ghost text. It is off with `/config input_suggest=false` or `CHEETAH_SUGGEST=0`.

Installing CheetahClaws and running a first session

The README gives a two-line quick start. The package is on PyPI and requires Python 3.10 or newer according to pyproject.toml.

pip install cheetahclaws

Then launch the REPL. The README uses deepseek-v4-flash as its example model.

cheetahclaws        # start chatting!

You should land at an interactive prompt where slash commands work. If you want to switch providers mid-session, the news entry for OpenRouter gives the exact form, including the optional upstream pin.

/model openrouter/deepseek/deepseek-v4-flash
/model openrouter/deepseek/deepseek-v4-flash@gmicloud/fp8

The key comes from the environment or from a config command, not from the model string.

/config openrouter_api_key=sk-or-...

The README lists several alternatives to pip: a one-line install script, install from source, a uv install, running directly from source with no install, and a Docker image. For a headless deployment, docker-compose.yml describes a home-server stack where the Web UI and a Telegram bridge run in one container and talk to Ollama on the Docker host. The documented quick start is to copy `.env.example` to `.env`, create `./workspace` and `./data`, run `docker compose up -d --build`, then open `http://<host-ip>:8080/chat`. The compose file maps `${WEB_PORT:-8080}:8080` and mounts `./data` at `/home/cheetah/.cheetahclaws` so config and sessions survive container restarts. The Dockerfile pre-creates both directories and chowns them to the non-root `cheetah` user, because otherwise first run dies with a PermissionError creating sessions. If you prefer a window over a terminal, the README points at a desktop build under `desktop/` that wraps the chat UI in Electron.

Permission prompts are the feature to scrutinize

The August 16, 2026 release notes are the most important thing to read before trusting this harness with a real repository. In `auto` mode, prompts are now reserved for actions that can change your files, run arbitrary code, or reach outside the session. Auto-approved now includes every registry-marked read-only tool (18 more than before, covering diagnostics, task and memory queries, and document readers), read-only shell pipelines, session-state tools, and creating a new file inside the workspace.

Still gated: overwrites, writes outside the workspace, `.git/hooks` and `.github/workflows` paths, interpreters and test or build runners, anything that deletes or uploads, and sub-agent spawns. The prompt gained an `s` option that approves one command or file for the session, and `/permissions clear` drops those grants.

The reason this matters is the shell check. It is now described as a real parser rather than a prefix match, which closed a hole where anything starting with `python `, `node ` or `find ` auto-ran. Pipelines such as `git log | head -20` and `ls -la | grep test` previously failed the old check because it rejected every pipe character. So the same release both widened what runs without asking and tightened what the check actually inspects. If you are evaluating this for a shared machine, read docs/news.md rather than the top-level README, which does not carry the current permission semantics.

Where CheetahClaws is the wrong tool

The documentation is thin in places that matter for production use. The README does not document rollback of a session, and it does not describe a migration path between the frequent releases. The release cadence is fast: v3.5.85 on 2026-07-11, then v3.5.86 and v3.5.87 both on 2026-08-17. Behaviour changes land inside patch-level versions, and the permission model itself changed in a patch release. If your integration depends on which actions are auto-approved, pin a version and read the changelog before upgrading.

There is also a coupling between the harness and the model that is easy to underestimate. Tool profiles exist because tool schemas consume prompt tokens. On a small-context local model, `full` may simply not fit, and `standard` changes what the model can see. The project gives you the switch but not a recommendation for any specific context size, so you have to measure it yourself.

Finally, the ghost-text feature spends an auxiliary model call on every turn. It is one-shot per prompt and silent on failure, which limits the damage, but it is still a background request you did not explicitly ask for unless you disable it. On a metered API that is a cost you should account for before enabling it by default.

The project is not archived, and the last push was on 2026-09-12, three days before this writing. That says the repository is being touched, not that any particular interface is stable.

Alternatives and how the approach differs

The obvious comparison is a general-purpose agent framework such as LangChain or a coding agent such as Claude Code. The difference is where configuration lives. Frameworks of the LangChain kind expect you to compose chains, tools and memory in Python code, which gives you control over every step and makes the harness your responsibility. CheetahClaws inverts that: the loop, the tool registry, the permission gate and the session store already exist, and you configure them through slash commands and a small set of config keys. That is faster to start and slower to change if your requirements diverge from the built-in loop.

Claude Code is the closer comparison in daily use, and the repository acknowledges the adjacency through its topics and the `!claude` bridge mentioned in requirements.txt, where pyte provides terminal-emulator rendering for the `!claude` and `!python` bridges. The practical difference is provider breadth. CheetahClaws routes through Anthropic, OpenAI, DeepSeek, Gemini, Ollama and OpenRouter from one interface, and the OpenRouter integration lets you pin an upstream provider per call. If you are already committed to a single vendor, that breadth buys you less than the permission model does.

Against a bare LiteLLM setup, CheetahClaws adds the parts LiteLLM deliberately leaves out: the tool registry, the permission prompts, session autosave and the REPL. LiteLLM is the routing layer; CheetahClaws is the thing that sits on top and decides when to ask you a question.

Licence, upgrades and what to verify first

The licence is Apache-2.0, declared in both pyproject.toml and the LICENSE file, with a separate NOTICE file at the repository root. For most internal use that is straightforward, but the NOTICE file is the part people skip, and it is the part that carries attribution requirements. This is not legal advice; if you are redistributing the harness inside a product, have someone read LICENSE and NOTICE together.

The upgrade cost is real. Three tagged releases between 2026-07-11 and 2026-08-17, with the permission semantics rewritten in the last one, means an upgrade is a code review, not a version bump. The practical approach is to pin the version in pyproject.toml or requirements.txt, read docs/news.md for the range you are crossing, and check whether any config key you rely on changed meaning. The `tool_profile` values and the `CHEETAH_SUGGEST` environment variable are the two switches most likely to affect behaviour silently.

Before adopting, verify three things: that your Python is 3.10 or newer, that the provider you configure actually serves the model ID you pass to `/model`, and that the auto-approved action list matches your risk tolerance. The last one is the only one the README will not tell you, because the README does not carry the current permission table.

Editorial conclusion

Adopt CheetahClaws if you want one terminal harness that can switch between cloud and local models without rewriting your tooling, and if you are willing to read the permission prompts rather than run accept-all. Skip it if you need a stable, slowly changing API surface: the release notes show three tagged releases between July and August 2026, with behaviour changes landing inside minor versions. Before committing, verify that your Python is 3.10 or newer, that the model you intend to use is reachable from the provider you configure, and that tool_profile=standard does not hide a tool your workflow depends on. The Apache-2.0 licence and the NOTICE file are the two things to read before you ship it inside a product.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. SAIL-Research-Lab/cheetahclaws on GitHub