Run Claude Code for free with a mock model server

Claude Code separates into two halves: the CLI running on your own machine and the model running on Anthropic's servers. Billing applies only to the model's work of reading requests and producing answers, so swapping just that half for a small server that returns scripted responses leaves the CLI's real behavior intact while removing the cost. Requests are sent as HTTP calls to the Messages API, and the mock only needs to implement the /v1/messages endpoint, since answers come back as replies to those requests rather than as separate calls.

The write-up uses the setup to inspect what the CLI actually transmits. A request captured during a run includes a system prompt the CLI adds, tool definitions, and the prior conversation. As an example, the author adds a UserPromptSubmit hook and finds its output delivered inside the CLI's added preamble, under a heading that reads 'UserPromptSubmit hook success:'. The same method was used previously to check how /compact replaces a conversation with a summary, how MCP server descriptions and skills reach the model, and how MCP tools are moved to the background after 120 seconds.

Beyond inspection, the piece shows the mock can simulate failures. Returning HTTP 529 responses a set number of times lets you observe how the CLI retries, with the number of retries controlled by CLAUDE_CODE_MAX_RETRIES. The author also runs this pattern at a larger scale for their own macOS app tanacode, driving the real CLI with the mock every day in GitHub Actions to catch breakage when Claude Code updates.