Backend request: CheetahClaws (SafeRL-Lab/nano-claude-code, Apache-2.0) as a runner backend

[master5d]

Problem

CheetahClaws (SafeRL-Lab/nano-claude-code, Apache-2.0, PyPI cheetahclaws 3.5.87) is a Python clean-room reimplementation of the Claude Code agent loop with a multi-provider model layer (any OpenAI-compatible endpoint via custom/<model>), Markdown skills, MCP in the .mcp.json shape, and session autosave. We run it as one of eight sandboxed kernels in our lab and it is our chosen foundation for the harness layer, but it cannot be a HarnessRouter backend today: the backend list is fixed (codex, claude, hermes, dsh, opencode, aider, kimi, openhands, qwen, cline, pi, gemini, omp, goose, systemone) and a custom harness is a configuration over a built-in backend. So none of the five verification scenarios, nor the custom-harness dimension, can be measured for it.

Proposal

Add cheetahclaws as a runner backend, the way pi was added as one registry entry (runner/server.py, "registry-driven"). What the CLI offers, measured on our instance (podman box, model through an OpenAI-compatible gateway):

• headless turn: cheetahclaws --accept-all -p --model custom/<model> "<prompt>" (stdin closed; --accept-all = no permission prompts; -p prints the final answer to stdout, tool cards go to stderr with ANSI);
• model/provider: CUSTOM_BASE_URL (or custom_base_url in ~/.cheetahclaws/config.json) + CUSTOM_API_KEY; provider prefix custom/ maps to any OpenAI Chat Completions endpoint; no Responses-API path needed;
• skills: ~/.cheetahclaws/skills/<name>/SKILL.md (also skill.md; project-level .cheetahclaws/skills/ takes priority) — --- frontmatter name/description in the Claude Code shape loads unchanged; the agent exposes SkillList and Skill tools;
• MCP: ~/.cheetahclaws/mcp.json or <cwd>/.mcp.json in the Claude Code mcpServers format (stdio/SSE/HTTP); tools appear as mcp__<server>__<tool>;
• instructions: AGENTS.md/CLAUDE.md in the workspace are read;
• session record: ~/.cheetahclaws/sessions/mr_sessions/session_latest.json — {"_version", "session_id", "saved_at", "messages", "turn_count", …}, messages in the OpenAI shape with tool calls as {"id", "name", "input": {...}} and tool results by tool_call_id; this is enough for the turn record (assistant text, tool calls, produced files come from the workspace);
• workspace hygiene: the CLI writes its task tracker to <cwd>/.cheetahclaws/tasks.json — a driver should relocate or ignore it (we exclude it from the produced-files diff).

Limitations to design around: no JSON event stream on stdout (unlike pi -p --mode json), so live events would come from parsing the session file after the turn or from stderr tool cards; the process exits 0 even when the model endpoint is unreachable (the error is printed), so the driver has to read the session/outcome rather than the exit code; on long sessions the model may finish the turn with a tool call printed as text, which the CLI accepts as the final answer.

Compatibility

Additive: one backend entry plus a driver; no protocol change. The .harness/ skills relocation rule from docs/harness-verification.md maps to .cheetahclaws/skills (project-level, highest priority).

Alternatives

• Keep measuring it outside HarnessRouter (what we do now) — loses the five-scenario comparability with the other backends.
• Run it behind a custom Responses server as systemone does — heavier than a driver and hides the harness identity.

We can provide a driver PR following the "Adding a harness" checklist if the entry is welcome; opening the issue first per CONTRIBUTING.

[richard-epsilla]

Thank you for this: the facts are measured on a real instance, the limitations are named before anyone finds them in review, and the shape (one backend, one driver, additive) is right. The entry is welcome; please open the PR against the "Adding a harness" checklist in docs/harness-verification.md. Eight points from reading the proposal against what the runner actually needs, so the PR lands in one round.

1. It is a driver, not a registry entry. pi could be one registry line because pi -p --mode json streams events. CheetahClaws has no event stream on stdout, so this backend follows the DeepSeek and Aider shape: a runner/cheetahclaws_driver.py that runs the CLI and emits claude-shaped stream-json lines to the runner (__hr_init first, __hr_result last, server.py unaware of the wire), plus a normaliser. The registry entry then points at the driver.

2. The live stream is not optional. The console renders a turn as it runs and the streaming chapter measures progressiveness (S-09), so a driver that reads session_latest.json only after the turn produces a silent turn and a stream that arrives all at once. Two acceptable sources, in order: tail the autosaved session file while the turn runs, if autosave writes after every message (please measure how often it writes, that decides it); or an upstream --output-format stream-json flag, which a Claude Code reimplementation is well placed to add and which would make this backend a registry line after all. Parsing ANSI tool cards off stderr is a fallback for the cards only, never the primary source.

3. Provider failure. Exit 0 with the error printed means checklist item 6 applies in full: pin the exact text the CLI prints for an unreachable endpoint, a bad key and a 429, with a test, and report the turn as failed carrying that sentence. A turn that ends "completed" with empty text on a dead endpoint is the one outcome the suite cannot tell from a real answer.

4. Credentials go through the relay. CUSTOM_BASE_URL and CUSTOM_API_KEY are exactly what the loopback relay fronts: the driver hands the CLI the relay address and a placeholder key and the sandbox never holds the key, as every backend does. Declare the providers as measured: custom/<model> over Chat Completions means the OpenAI-chat providers (openai-api, custom in chat format, openrouter, tokenrouter, vercel); list _CUSTOM_FORMAT_BACKENDS accordingly and leave out any format the CLI does not speak.

5. Served model and usage. Rule 2 of the matrix needs the served model on the turn record and the benchmark needs fresh, cached and output tokens. If the session file carries neither, say so and let the relay's taps supply them off the wire, as kimi and aider do; the PR should state which of the two it is.

6. Resume. session_latest.json is one file. With $HOME redirected into the session's workspace (the runner does this for every CLI, so the session travels in the checkpoint) "latest" is the session's own, but the PR should say whether the CLI has a resume flag, and pin _resume_lost (checklist item 5) for a follow-up whose session is gone.

7. Hygiene and honesty. .cheetahclaws/tasks.json goes in CHECKPOINT_EXCLUDE and _PRODUCED_EXCLUDE_PREFIX; the skills relocation to project-level .cheetahclaws/skills/ is right. For tool_enforcement, say hard only if the CLI can withhold a tool (a flag or config the driver sets); otherwise the instruction-doc tier, which is what most CLIs get. Name which of AGENTS.md and CLAUDE.md wins when both exist.

8. Install and measure. A pinned install on the volume like aider's (its own venv, the version proven by import), a NOTICE line for the Apache-2.0 package, and in the PR: the runner tests with a recorded session file, the conformance suite and a support-matrix column against a live instance, with the notes saying which version ran on what. A benchmark column (scripts/benchmark) is welcome too.

Send the PR when you have it and I will review it on that basis.