README suggestion: add a compatibility contract

[nathan-widjaja]

The 17x cheaper hook is doing its job — HN clearly found it. I think the next conversion blocker is trust, not awareness.

The README says the Claude Code tool loop, file edits, bash, git, subagents, and autonomous multi-step behavior stay intact while API calls route to DeepSeek/OpenRouter/compatible backends. That is the core promise, but I would make it a small compatibility contract before the install steps.

Example block:

Keep Claude Code's tool loop; swap only the model backend. What does not change: file editing, bash, git, subagents, and the autonomous loop. What changes: model behavior, provider limits, latency, credentials, and failure modes.

Then add two lines on when not to use it yet: sensitive repos, workflows that depend on exact Claude behavior, or teams that need a supported vendor path. The cost story stays sharp, but the project will feel safer to try.

[diva0078]

This suggestion makes sense. I’d add one more small section: a concrete compatibility checklist that people can run before trusting a non-Claude backend in a real coding session.

The checks I keep seeing expose real failures are:

1. one streaming response while the agent is editing files
2. one tool call with a nested JSON schema
3. one long-context request near the provider limit
4. one provider error / rate-limit case and how it maps back to Claude Code
5. one fallback test between Anthropic-style and OpenAI-compatible backends

For DeepSeek-style backends, which one has been the most fragile in your testing so far: auth/key setup, streaming semantics, tool call shape, or error/retry mapping?

I’m comparing gateway patterns for CN providers and this is the checklist I’m using to separate “works for a demo” from “safe enough for a real coding loop.”

[aattaran]

Strong suggestion — agreed that trust is the next conversion blocker after awareness. The "what doesn't change / what changes / when not to use" framing is exactly the right shape.

Will add as a follow-up commit to the README, placed before the install steps (where it'll do the most work). Tracking.