# Quick Start Guide

Welcome to CodeBuddy Code! This guide will help you get started in 5 minutes and experience a natural language-driven programming assistant.

## 🎯 Before You Begin

### System Requirements
- **Node.js**: Version 18.20 or higher
- **Operating System**: macOS, Linux, or Windows

### Verify Your Environment
```bash
# Check Node.js version
node --version  # Should display v18.0.0 or higher

# Check npm version
npm --version
```

## ⚡ Quick Installation

### npm Global Installation

```bash
npm install -g @tencent-ai/codebuddy-code
```

### Native Installer (Beta)

> ⚠️ **Beta Feature**: The native installer is currently in Beta. We recommend you try it to get a faster, standalone installation experience.

The native installer provides an independent CodeBuddy installation without requiring a Node.js environment.

**Download and Install:**

```bash
# macOS/Linux
curl -fsSL https://copilot.tencent.com/cli/install.sh | bash
```

```powershell
# Windows
irm https://copilot.tencent.com/cli/install.ps1 | iex
```

**Advantages:**
- ✅ No Node.js dependency required
- ✅ Faster installation and startup

### Verify Installation
```bash
codebuddy --version
```

## 🔐 Login Authentication

When using CodeBuddy Code for the first time, you need to complete login authentication. After startup, you will see the login method selection screen:

```
Select login method:
› Log in via Chinese Site
  Log in via International Site
  Log in via Enterprise Domain
  Log in via iOA (Tencent only)
```

### Login Methods

| Login Method | Use Case | Description |
|--------------|----------|-------------|
| **Chinese Site** | Users in China | Authenticate via Tencent Cloud China (copilot.tencent.com), supports domestic mainstream models |
| **International Site** | Overseas users | Authenticate via Tencent Cloud International (codebuddy.ai), supports international mainstream models |
| **Enterprise Domain** | Dedicated/Private deployment | Connect to enterprise dedicated or self-hosted CodeBuddy service, requires enterprise-provided service address |
| **iOA** | Tencent employees | Authenticate via Tencent iOA zero-trust system, for Tencent internal employees only |

Use `↑↓` keys to select the login method, press `Enter` to confirm, and the browser will automatically open to complete authentication.

## 🚀 First Experience

### 1. Navigate to Your Project Directory
```bash
cd /path/to/your/project
```

### 2. Launch Interactive Mode
```bash
codebuddy
```

You will see the welcome screen:

> **Tip**: If you want CodeBuddy Code to always reply in a specific language (e.g., Simplified Chinese), you can run the `/config` command after startup to set the Language option.
```
🤖 CodeBuddy Code v1.0.0
💡 Type /help to view available commands
📝 Start chatting and let AI become your programming partner

>
```

### 3. Initialize Project Context (Highly Recommended)

Before starting your conversation, it is **highly recommended** to initialize the project context using the `/init` command:

```
> /init
```

**Why is /init so important?**

**📊 Performance Improvements:**
- ✅ **More Accurate Understanding**: Pre-builds a project knowledge graph, enabling AI to more accurately understand code structure and business logic
- ✅ **Faster Responses**: Avoids repeated file scans, significantly improving subsequent conversation response times
- ✅ **More Precise Suggestions**: Provides recommendations more aligned with your project architecture based on a global view
- ✅ **Reduced Misjudgments**: Understands project dependencies, avoiding incompatible modification proposals

**💰 Cost Optimization:**
- ✅ **Lower Token Consumption**: Establishes context once, avoiding re-analysis in every conversation
- ✅ **Fewer Redundant Requests**: Pre-loads key information, reducing context token overhead by 30-50%
- ✅ **More Efficient Conversations**: Each conversation round carries less redundant information, lowering overall costs

**Best Practices:**
```
# When using a project for the first time
> /init

# When project structure undergoes major changes (e.g., adding new modules, refactoring)
> /clear  # Start a fresh conversation
> /init   # Re-initialize
```

### 4. Try Your First Conversation
```
> Help me analyze the structure of this project
```

CodeBuddy will automatically scan your project files and provide a detailed structural analysis.

## 💡 Core Usage Patterns

### Interactive Conversation Mode
The most natural way to use, suitable for exploratory development:

```bash
codebuddy
```

**Typical Conversation Examples:**
```
> I want to add a loading state to this React component
> Help me refactor this function to make it more readable
> What are the potential performance issues with this code?
> Write unit tests for this API endpoint
```

### Single Command Mode
Suitable for scripting and automation scenarios:

```bash
# Direct query
codebuddy -p "Optimize the performance of this SQL query"

# Pipeline input
cat error.log | codebuddy -p "Analyze these error logs"

# File analysis (must add -y or --dangerously-skip-permissions when authorization is needed)
codebuddy -p "Review the code quality of src/utils.js" -y
```

> **Important Note**: When using the `-p/--print` parameter for single execution, if the operation requires authorized actions such as file access or command execution, you must add the `-y` (or `--dangerously-skip-permissions`) parameter.

### Project-Level Operations
Handle complex cross-file tasks:

```bash
# Project refactoring (requires file operation authorization)
codebuddy -p "Migrate all components from class components to function components" -y

# Code standards (requires file read authorization)
codebuddy -p "Check TypeScript type definitions across the entire project" -y

# Test coverage (requires file operation authorization)
codebuddy -p "Add unit tests for all files in the services directory" -y
```

### Keyboard Shortcuts

#### Basic Navigation
| Shortcut | Function |
|--------|------|
| `↑/↓` | Browse command history |
| `↓` | View background tasks (when tasks are running) |
| `Tab` | Command auto-completion |
| `Esc` | Clear input (press twice) / Return to previous menu |
| `Ctrl+C` | Exit program |
| `Ctrl+D` | Exit program (press twice when input is empty and no conversation in progress) |

#### Permissions and Modes
| Shortcut | Function |
|--------|------|
| `Shift+Tab` (macOS/Linux) or `Alt+M` (Windows) | Toggle permission mode (default → bypass → accept → plan) |

#### Editing Features
| Shortcut | Function |
|--------|------|
| `Ctrl+R` | Expand/collapse detailed output (in conversation) |
| `Ctrl+G` | Edit prompt in external editor |
| `Enter` | Send message |
| `Shift+Enter` | New line (multi-line input) |
| `\Enter` | New line (backslash escape) |
| `Ctrl+J` | Insert new line (multi-line input) |

#### Panel Operations
| Shortcut | Function |
|--------|------|
| `↑/↓` | Navigate options in panel |
| `Enter` | Select current item |
| `Space` | Toggle selection (multi-select panels) |
| `k` | Terminate selected background task |

#### Special Functions
| Shortcut | Function |
|--------|------|
| `j/k` | Vim-style up/down navigation (supported in some panels) |
| `Ctrl+O` | View thinking details panel |

When the terminal displays a "Thinking" indicator, you can use `Ctrl+O` to open the full reasoning content, and press `Ctrl+O` again to exit.

## 🎓 Advanced Learning

Congratulations on completing the quick start! We recommend reading next:

- **[Common Workflows](common-workflows.md)** - Learn advanced features like extended thinking and image analysis
- **[IDE Integration](ide-integrations.md)** - Use in VS Code and JetBrains
- **[Slash Commands](slash-commands.md)** - Master all built-in commands
- **[MCP Integration](mcp.md)** - Extend with custom tools

## 💬 Get Help

Having issues? We're here to support you:

- 🐛 [Submit a Bug](https://cnb.cool/codebuddy/codebuddy-code/-/issues)
- 📧 Technical Support: codebuddy@tencent.com
- 📚 [Complete Documentation](./README.md)
- 🌐 [Official Website](https://copilot.tencent.com/cli)

---

*Now, let AI become your programming partner! 🚀*
