# Zhipu AI (Z.AI) GLM Provider Guide - Claude Code

This guide explains how to integrate **GLM-5.1** from Zhipu AI as a specialized "Coding Plan Provider" in Claude Code. This allows you to use GLM's strong reasoning capabilities for the architectural and planning phase, while maintaining Claude (or another model) for the execution phase.

---

## 1. Architecture: The Planner-Executor Split

Claude Code uses a "Plan Mode" to design complex changes before executing them. This is internally managed by `permissionMode: 'plan'`.

By specialized the models:
- **Planner (GLM-5.1)**: Uses massive context and multi-step reasoning to design a robust implementation plan.
- **Executor (Claude 3.5 Sonnet)**: Follows the plan with precision to write and edit code.

---

## 2. Implementing the Z.AI Provider

### Hooking the Client
The Z.AI API is largely OpenAI-compatible. You can hook it into Claude Code's existing client initialization in [`services/api/client.ts`](file:///Users/vlad/Developer/vlad/claude-code/services/api/client.ts).

1.  **Add Provider Type**: Update `APIProvider` in `utils/model/providers.ts` to include `'z-ai'`.
2.  **Client Entry**:
    ```typescript
    if (isEnvTruthy(process.env.CLAUDE_CODE_USE_Z_AI)) {
      return new Anthropic({
        apiKey: process.env.Z_AI_API_KEY,
        baseURL: process.env.Z_AI_BASE_URL || 'https://open.bigmodel.cn/api/paas/v4/',
        ...ARGS,
      })
    }
    ```

---

## 3. Highjacking "Plan Mode"

To ensure GLM-5.1 is only used for planning, you need to modify the model selection logic in [`utils/model/model.ts`](file:///Users/vlad/Developer/vlad/claude-code/utils/model/model.ts).

Modify `getRuntimeMainLoopModel`:

```typescript
export function getRuntimeMainLoopModel(params: {
  permissionMode: PermissionMode
  mainLoopModel: string
  exceeds200kTokens?: boolean
}): ModelName {
  const { permissionMode, mainLoopModel } = params

  // Specialized Planning Provider: GLM-5.1
  if (permissionMode === 'plan' && isEnvTruthy(process.env.CLAUDE_CODE_USE_Z_AI)) {
    return 'glm-5.1' // Or your specific deployment ID
  }

  // Fallback to Sonnet/Opus for execution
  return mainLoopModel
}
```

---

## 4. Configuration

To use this setup, configure the following environment variables:

| Variable | Description |
| :--- | :--- |
| `CLAUDE_CODE_USE_Z_AI=true` | Enables the Z.AI provider logic. |
| `Z_AI_API_KEY` | Your Zhipu AI API Key. |
| `Z_AI_BASE_URL` | The endpoint for BigModel (e.g., `https://open.bigmodel.cn/api/paas/v4/`). |
| `Z_AI_BASE_URL` | The endpoint for BigModel (e.g., `https://open.bigmodel.cn/api/paas/v4/`). |
| `ANTHROPIC_MODEL` | (Optional) The model to use for execution (e.g., `claude-3-5-sonnet-latest`). |
| `CLAUDE_CODE_ADDITIONAL_PROTECTION` | (Optional) Enable strict header validation if required by your gateway. |

---

## 5. Optimization & Performance

### Tool-Calling
GLM-5.1 is highly proficient at the OpenAI-style tool-calling schema. Claude Code uses a similar structure, making the migration smooth. However, ensure that your `baseURL` correctly routes to the `/chat/completions` endpoint that supports these features.

### Long Context
GLM-5.1's large context window is a primary advantage for the "Plan Mode" phase, as it can ingest an entire multi-file project structure or complex documentation without truncation.

---

> [!TIP]
> This "hybrid" approach allows you to leverage GLM's cost-efficient and high-reasoning planning while keeping Claude's world-class code-generation for the final edits.

---

## See Also
- **[Authentication Guide](file:///Users/vlad/Developer/vlad/claude-code/docs/AUTH_GUIDE.md)**: Details on general environment variables and credential management.
