CheetahClaws: The Python-Native Agent OS Remix

What CheetahClaws is trying to be

The repo describes CheetahClaws as a fast, production-ready, Python-native personal AI assistant for any model. That is already a broader framing than "coding CLI." The top-level entrypoint exposes slash commands for MCP, plugins, memory, tasks, web mode, background agents, bridges, trading, research labs, subscriptions, TTS, voice, and daemon control. It is openly inspired by Claude Code and OpenClaw, but it is not satisfied with being a minimal clone.

Architecturally, the project feels like two systems growing into one another. The original REPL path is still there: a big user-facing CLI, direct Python tool functions, bridge integrations, and a central tool registry. On top of that sits a newer kernel and daemon layer with per-agent capabilities, JSON-RPC, SSE events, subprocess runners, and stricter built-in tools. CheetahClaws is interesting precisely because it has not chosen one side and deleted the other.

The core runtime: session-scoped context instead of global state

The most important stabilizing abstraction is RuntimeContext. Each REPL session, bridge conversation, or daemon-originated interaction gets a session-specific context object that holds callbacks, bridge state, web state, plan-mode fields, proactive polling state, and the live AgentState. That is a practical answer to a classic Python-agent problem: once a CLI grows bridges, background threads, and multiple clients, module globals become a race.

Provider strategy: almost everything, from Claude to local Ollama

Provider breadth is one of the repo's main differentiators. The top-level provider registry maps named providers to API base URLs, model lists, context limits, and token-cost metadata. It supports Anthropic, OpenAI, Gemini, Kimi, Qwen, Zhipu, DeepSeek, MiniMax, Ollama, LM Studio, custom OpenAI-compatible endpoints, and a LiteLLM adapter for awkward enterprise/provider auth paths.

This matters because CheetahClaws is trying to be an alternative not just to one vendor's coding tool, but to the assumption that a coding harness must be bound to a single provider. Model strings can be auto-detected by family name or forced with explicit prefixes such as ollama/qwen2.5-coder or custom/my-model.

The tool system: plugin registry on top, capability kernel beneath

There are really two tool stories in CheetahClaws. The first is the user-facing plugin registry in tool_registry.py: each tool has a name, JSON schema, Python callable, read-only flag, and concurrent-safety flag. Read-only tools are cached per session, and write-like tools invalidate that cache automatically.

The second is the kernel path under cc_kernel/, where tools are registered with explicit filesystem grants and dispatched through a capability check. That layer introduces a more formal execution model: agent PID, tool grant, path grant, handler dispatch, structured error slugs, and pure-ish tool responses over IPC.

ToolDef(
  name="Read",
  schema=...,
  func=_read_with_overflow_check,
  read_only=True,
  concurrent_safe=True
)

if not kernel.cap.check_tool(pid, tool.name):
    return permission_denied
if not kernel.cap.check_fs(pid, path, mode):
    return fs_denied
result = tool.handler(args, ctx)

File editing: pragmatic, mixed, and more transparent than elegant

CheetahClaws does not force every mutation through one sacred edit protocol. The legacy tools/fs.py path provides numbered reads, whole-file writes, exact-string edits with optional replace_all, CRLF normalization, and immediate unified-diff feedback. Notebook editing lives in its own tool and directly rewrites Jupyter JSON. The kernel layer adds separate Read, Write, and Diff tools with capability checks and stricter path handling.

That mixed approach is less aesthetically pure than a single SEARCH/REPLACE doctrine, but it is very practical. A user gets straightforward whole-file overwrites, exact edit retries, notebook cell mutation, path-based diffing, and shell escape hatches — all with multiple safety layers rather than one universal parser.

Security boundaries: strong patches on top of a trusted-operator model

The security documentation is unusually candid about its starting assumption: one trusted operator on one host. Inside that boundary the defaults favor usability. Once the repo crosses into remote bridges, daemon mode, plugins, or multi-user web deployments, the hardening turns on: bash hard denylist, credential-path denylist, CSRF for the web UI, owner-bound terminal sessions, plugin kill switches, and MCP environment sanitization.

The interesting architectural point is that CheetahClaws is not pretending these are hypothetical concerns. The repo has already accumulated the scars that create hardening features: bridge command abuse, token leakage risk, web auth, plugin trust, path escape, and daemon multi-tenancy.

Daemon, kernel, and web mode: where it turns into an agent service

The daemon layer is where CheetahClaws stops looking like "just a terminal app." The server exposes /rpc, /events, /healthz, and /readyz, keeps shared daemon state, runs authenticated JSON-RPC methods, and streams asynchronous notifications over SSE. The permissions store even has its own janitor thread. That is service architecture, not incidental glue.

Web mode runs the chat UI in a background thread from the REPL path, while the daemon can supervise runner subprocesses and bridge methods in a more controlled environment. This split means the project can act as a personal CLI, a long-lived background service, or a remotely accessed agent endpoint depending on which layer you turn on.

Autonomy, subagents, and memory: the repo's platform ambitions

CheetahClaws includes several forms of delegation and long-lived work. Built-in subagent definitions include general-purpose, coder, reviewer, researcher, and tester personas. User and project-level agent definitions can be loaded from Markdown. Autonomous runners execute task templates over multiple iterations, auto-approve permissions in autonomous mode, and persist per-iteration summaries under ~/.cheetahclaws/agents/.

Memory is split cleanly: session history goes to SQLite with FTS5 search, while long-term memory consolidation extracts a capped number of durable user/project facts from longer sessions. That is a practical compromise. Instead of pretending every message is semantic memory, the repo keeps a searchable transcript store and a much smaller, AI-curated memory layer on top.

How CheetahClaws compares to nearby agents in this repo set

Design tradeoffs

Further reading