Claude Code Deployment and Usage: A Complete Hands-On Guide

With AI-powered development tools proliferating rapidly, Anthropic's Claude Code has quickly emerged as one of the most talked-about command-line programming assistants in the developer community. It stands out thanks to its deep understanding of entire codebases and genuine agent-level operational capabilities. Unlike code completion tools such as GitHub Copilot, Claude Code isn't designed to be a chat companion — it's purpose-built to execute high-privilege, context-aware engineering tasks directly within your local codebase. This guide walks you through everything from installation and configuration to advanced usage, covering multiple model integration options so you can get the most powerful coding assistance at the lowest possible cost.

1. Understanding Claude Code: What It Really Is

Before diving in, let's establish one key concept.

1.1 It's an Agent, Not a Chatbot

Claude Code is fundamentally a CLI Agent. Its core capabilities include:

• Reading entire project directories directly: No manual code pasting required — it traverses your project structure autonomously
• Understanding real code architecture: Analyzes file dependencies, module relationships, and call chains
• Executing multi-file modifications: Refactor across files or batch-generate code with a single instruction
• OS-level operations: Executes shell commands, runs tests, and manages Git

1.2 How It Compares to Other Tools

To understand Claude Code's positioning, it helps to compare it with these categories of tools:

• Code completion tools (Copilot, Codeium): Suggest code snippets in real-time as you type, focused on single-line or single-function completion
• Conversational assistants (ChatGPT, Claude Web): Provide programming advice via web chat, requiring you to manually copy code
• Agent tools (Claude Code, Cursor Agent, Codex CLI): Autonomously understand projects, plan tasks, execute modifications, and run verification

Claude Code falls into the third category — it thinks and acts proactively. You describe the goal, and it handles breaking down the steps and executing them.

2. Environment Setup and Installation

2.1 Prerequisites

Before installing, make sure you have:

• Operating system: Windows 10/11 (64-bit), macOS 10.14+, Ubuntu 18.04+, or other mainstream Linux distributions
• Memory: 4 GB or more recommended
• Terminal: Built-in Terminal on macOS/Linux, PowerShell or WSL on Windows
• Network: Installation requires internet access (subsequent usage can route through domestic model services if needed)
• Account: A Claude Pro/Max/Team/Enterprise subscription, an API key, or a third-party model service account

2.2 Platform-Specific Installation

The official npm installation method has been deprecated in favor of Native installation.

macOS / Linux / WSL (recommended):

# One-click install script

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell (run as Administrator):

# Run in PowerShell (not CMD)

irm https://claude.ai/install.ps1 | iex

Windows CMD:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Common pitfall: If you see The token '&&' is not a valid statement separator, you're using CMD syntax inside PowerShell. If you see 'irm' is not recognized, you're using PowerShell syntax inside CMD. Here's how to tell them apart: the PowerShell prompt is PS C:\>, while the CMD prompt is C:\> (no "PS").

macOS Homebrew installation (alternative):

# Stable release (typically about a week behind, skips versions with major regressions)

brew install --cask claude-code

# Latest release (updated as soon as it's published)

brew install --cask claude-code@latest

Windows WinGet installation (alternative):

winget install Anthropic.ClaudeCode

Native vs. WinGet installation differences: The Native installer supports automatic updates but requires manual folder deletion to uninstall. WinGet doesn't auto-update but lets you upgrade via winget upgrade, and uninstalling is cleaner (winget uninstall).

Linux package manager installation:

Also available via apt (Debian/Ubuntu), dnf (Fedora), apk (Alpine), and more — see the official documentation for details.

2.3 npm Installation (Fallback Option)

If none of the above methods work for you, the npm installation still works:

# Install Node.js (using Ubuntu as an example)

sudo apt update

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo bash -

sudo apt-get install -y nodejs

# If your Node.js version is too low, upgrade using the n module

sudo npm install -g n

sudo n stable

# Optional: configure a domestic mirror to speed things up

sudo npm config set registry https://mirrors.cloud.tencent.com/npm/

# Install Claude Code globally

sudo npm install -g @anthropic-ai/claude-code

# Verify installation

claude --version

2.4 Uninstallation

Uninstalling the Native installation (Windows PowerShell):

Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force

Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force

Uninstalling via WinGet:

winget uninstall Anthropic.ClaudeCode

3. First-Time Login and Setup

3.1 Starting an Interactive Session

cd /path/to/your/project

claude

The first time you run it, you'll be prompted to log in. You can also use the /login command within a session to manually log in or switch accounts.

3.2 Supported Account Types

• Claude subscription (Pro, Max, Team, Enterprise) — recommended; provides direct access to official Claude models
• Claude Console (API prepaid credits) — automatically creates a "Claude Code" workspace on first login for cost tracking
• Cloud providers (Amazon Bedrock, Google Vertex AI, Microsoft Foundry) — enterprise-grade solutions

3.3 Handling Regional Restrictions

If you see a regional restriction prompt after launching (common for users in mainland China), you'll need to modify a configuration file:

Locate ~/.claude.json (on Windows, the path is C:\Users\[Username]\.claude.json) and add or update the following field:

{

  "hasCompletedOnboarding": true

}

This skips the onboarding flow and lets you use the tool normally.

4. Configuring Third-Party Model Services (Key Section)

Since Claude's official service can be difficult to access from within China and token costs can add up quickly, integrating a domestic model service is the most cost-effective approach. Below are two mainstream options.

4.1 Option 1: cc-switch Graphical Tool

cc-switch is a cross-platform desktop application for managing and switching the backend models used by tools like Claude Code, Codex, and Gemini CLI. It supports multiple domestic and international model providers.

Installation:

Visit the GitHub repository at https://github.com/farion1231/cc-switch and download the installer for your platform from the Releases page.

Configuration:

1. Create an API Key: Using ModelScope as an example, go to https://modelscope.cn//, link your Alibaba Cloud account, and create a token on the "Access Control" page
2. Add a provider: Select a preset provider in cc-switch and enter your API Key
3. Specify the model name: Look up the exact model identifier from the provider's model library page

Recommended domestic models:

• Coding model: Qwen/Qwen3-Coder-480B-A35B-Instruct — the largest-parameter coding model available on ModelScope
• Reasoning model: Qwen/Qwen3-235B-A22B-Thinking-2507 — ideal for complex logical reasoning tasks
• General-purpose models: qwen3.5-plus, glm-4.7, kimi-k2.5, and others

4.2 Option 2: Alibaba Cloud Bailian Coding Plan (Recommended)

The Alibaba Cloud Bailian Coding Plan provides an Anthropic-compatible API protocol, making integration extremely straightforward. New users can get started for as low as ¥7.9/month.

Setup:

1. Visit the Bailian console: https://bailian.console.aliyun.com/cn-beijing/?tab=model#/efm/coding_plan
2. Choose a plan and purchase (the Lite tier is ¥7.9/month with 18,000 requests; Pro is ¥39.9/month with 90,000 requests)
3. Generate a dedicated API Key on the Coding Plan page

Integration Configuration:

Edit the configuration file at ~/.claude-code/setting.json (Linux/macOS) or the equivalent path on Windows:

{

  "env": {

    "ANTHROPIC_AUTH_TOKEN": "your-api-key",

    "ANTHROPIC_BASE_URL": "https://coding.dashscope.aliyuncs.com/apps/anthropic",

    "API_TIMEOUT_MS": "3000000",

    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"

  }

}

Also make sure ~/.claude.json contains:

{

  "hasCompletedOnboarding": true

}

Switching Models:

Once connected, you can switch models directly within the Claude Code prompt by typing /model followed by the model name:

/model qwen3.5-plus

/model glm-4.7

/model kimi-k2.5

Supported models include: qwen3.5-plus, qwen3-max-2026-01-23, qwen3-coder-next, qwen3-coder-plus, glm-4.7, kimi-k2.5.

4.3 Comparing the Two Options

• cc-switch: Graphical interface, intuitive to use, supports more providers — ideal for users who frequently switch between models and tools
• Bailian Coding Plan: Simple configuration, request-based billing avoids token waste, Alibaba Cloud infrastructure ensures stability — ideal for cost-conscious users

5. Core Usage

5.1 Initialize Your Project (Highly Recommended)

When using Claude Code in a project for the first time, run the initialization command:

/init

Claude Code will read through your entire project and save its findings to a CLAUDE.md file in the project root. On subsequent tasks, it reads this file first to quickly get up to speed on your project context.

You can also manually edit CLAUDE.md to add project conventions, tech stack preferences, coding style guidelines, and other institutional knowledge. This is the single most impactful step for improving AI accuracy.

5.2 Understanding and Exploring a Codebase

# Project overview

What does this project do?

# Tech stack analysis

What technologies does this project use?

# Structure understanding

Explain the folder structure

# Locate entry point

Where is the main entry point?

5.3 Code Modifications and Feature Development

# Add a feature

Add a hello world function to the main file

# Fix a bug

There's a bug where users can submit an empty form — fix it

# Add validation

Add input validation to the user registration form

Claude Code will automatically locate the relevant files, understand the context, generate a modification plan, and execute the edits — only after receiving your approval.

5.4 Git Operations

# View changes

What files have I changed?

# Commit code

Commit my changes with a descriptive message

# Branch management

Create a new branch called feature/login

# View history

Show my last 5 commits

# Conflict resolution

Help me resolve merge conflicts

5.5 Other Common Workflows

Refactoring code:

Refactor the authentication module to use async/await instead of callbacks

Writing tests:

Write unit tests for the calculator function

Updating documentation:

Update the README with installation instructions

Code review:

Review my changes and suggest improvements

6. Advanced Tips and Best Practices

6.1 Switching Between Three Operating Modes

Use the Alt+M shortcut to cycle through these three modes:

• Normal mode: All code modifications require manual review (default; most secure)
• Auto Accept mode: AI modifications are applied without manual review (suitable for high-trust tasks)
• Plan mode: The AI doesn't make any code changes — it only outputs its thought process and execution plan (ideal for planning complex tasks)

Recommendation: Start with Plan mode to let the AI outline an approach, confirm the strategy, then switch to Normal mode to execute. Reserve Auto Accept for high-trust scenarios like batch modifications.

6.2 Controlling Reasoning Depth

You can control how deeply the model reasons by including keywords in your prompts:

think: Analyze the performance issues in this function

think hard: How can the time complexity of this algorithm be optimized

think harder: Refactor the entire payment module architecture

ultrathink: Design a message queue system that supports a million concurrent connections

The four levels (think → think hard → think harder → ultrathink) progressively increase the reasoning length — ideal for tackling difficult problems that require deep analysis.

6.3 Conversation Management

• /compact: Compresses previous conversation history, effectively reducing token consumption. Use this when a line of discussion wraps up
• /clear: Clears all conversation history and starts fresh. Keeping a clean context prevents the AI from being influenced by earlier, irrelevant exchanges
• /resume: Resumes a previous conversation

6.4 Ad-Hoc Command Execution

Prefix any input with ! to execute a shell command on the fly:

!ls -la

!npm test

!git status

The command output is automatically fed into the AI's conversation context — no need to open a separate terminal window.

6.5 Image Interaction

If the model you're using supports vision capabilities, you can drag images directly into the conversation window and then describe what you need. This is especially useful for analyzing UI screenshots, interpreting architecture diagrams, and debugging styling issues.

6.6 Connecting to VS Code

1. Install the Claude Code for VS Code extension
2. Enter the /ide command in the Claude Code terminal
3. Once connected, the AI's code modifications will be displayed as diffs in VS Code, making review much more intuitive

6.7 Tips for Writing CLAUDE.md

CLAUDE.md is the central configuration file that governs Claude Code's behavior. Here's what it should ideally contain:

# Project Overview

This project is a Next.js-based e-commerce admin dashboard.

# Tech Stack

- Frontend: Next.js 14 + TypeScript + Tailwind CSS

- State management: Zustand

- API layer: tRPC

# Code Conventions

- Use functional components and Hooks

- File naming follows kebab-case

- API responses are uniformly wrapped in a Result type

- Error handling uses try-catch, not .catch()

# Directory Structure Conventions

- /src/components - Shared components

- /src/features - Business logic organized by feature module

- /src/lib - Utility functions and shared logic

# Testing Requirements

- All new features must include unit tests

- Use Vitest + Testing Library

7. Essential Command Reference

Here are the most important commands for day-to-day use:

Starting and managing sessions:

• claude — Start interactive mode
• claude "fix the build error" — Run a one-off task
• claude -p "explain this function" — Run a one-off query and exit
• claude -c — Continue the most recent conversation
• claude -r — Resume a previous conversation

In-session commands:

• /init — Initialize project and generate CLAUDE.md
• /compact — Compress conversation history to save tokens
• /clear — Clear conversation history
• /model <model-name> — Switch model
• /login — Switch account
• /ide — Connect to VS Code
• /help — Show help
• exit or Ctrl+D — Exit Claude Code

8. GUI Options

Claude Code is inherently a command-line tool, but the community has built open-source graphical interfaces for it:

• opcode (formerly Claudia): GitHub at https://github.com/winfunc/opcode — provides a GUI for macOS and Linux
• Claudia Global: GitHub at https://github.com/who10086/claudia-global — offers a Windows installer

These tools are great for users who prefer not to work in a terminal.

9. Troubleshooting Common Issues

9.1 Unable to Launch After Installation

• Check that your Node.js version is ≥ v18.0
• Verify that your network can reach the installation source
• Windows users: confirm you're using the correct terminal (PowerShell vs. CMD)

9.2 Regional Restriction Prompt

Edit ~/.claude.json and make sure it contains "hasCompletedOnboarding": true.

9.3 Model API Call Failures

• Verify your API Key is correct
• Check that ANTHROPIC_BASE_URL points to the right compatible endpoint
• Confirm the model name is spelled correctly
• Make sure API_TIMEOUT_MS is set high enough (3,000,000 recommended)

9.4 Token Consumption Too High

• Get in the habit of using /compact to compress conversations promptly
• Use /clear when starting a new task to avoid carrying irrelevant context
• Use lightweight models (like Haiku) for simple tasks; reserve Sonnet/Opus for complex ones
• Write a detailed CLAUDE.md to reduce token waste from AI guesswork

10. Summary and Recommendations

Key Takeaways

1. Installation: Prefer the Native installer (curl / irm), with Homebrew or WinGet as alternatives
2. Model integration: Users in China should strongly consider the Bailian Coding Plan or use domestic models via cc-switch to significantly reduce costs
3. Project initialization: Running /init to generate CLAUDE.md is the critical step for improving AI accuracy
4. Mode selection: Plan mode for strategizing → Normal mode for execution → Auto Accept for batch operations
5. Token management: Use /compact and /clear liberally, combined with reasoning depth control keywords

Suggested Learning Path

• Week 1: Complete installation, login, and first project initialization. Get comfortable with basic conversations and code modifications
• Week 2: Master the three operating modes, Git operations, and VS Code integration
• Week 3+: Dive into CLAUDE.md authoring, MCP server integration, and team collaboration workflows

Claude Code isn't just another chatbot — it's a programming agent that genuinely understands your project and can execute complex engineering tasks. Mastering its deployment and usage means gaining a senior coding partner available 24/7. Spend thirty minutes today installing and configuring it, try it out on a small project, and you'll discover that the boundaries of programming productivity have been completely redefined.