# CodeBuddy Code Installation Guide

## Installation Methods

### 📦 Install via Package Manager

#### Node.js Package Managers

**Prerequisites:** Node.js 18.20 or higher

Choose your preferred package manager and run the following command:

::: code-group

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

```bash [pnpm]
pnpm add -g @tencent-ai/codebuddy-code
```

```bash [yarn]
yarn global add @tencent-ai/codebuddy-code
```

```bash [bun]
bun install -g @tencent-ai/codebuddy-code
```

:::

#### Homebrew (macOS/Linux)

No Node.js required, install directly:

::: code-group

```bash [Two-step Installation]
# Add tap
brew tap Tencent-CodeBuddy/tap

# Install tool
brew install codebuddy-code
```

```bash [Single Command Installation]
brew install Tencent-CodeBuddy/tap/codebuddy-code
```

```ruby [Brewfile]
tap "Tencent-CodeBuddy/tap"
brew "codebuddy-code"
```

:::

#### Verify Installation

After installation, run the following command to verify successful installation:

```bash
codebuddy --version
```


### ⚙️ Install via Native Binary (Beta)

> ⚠️ **Beta Testing Phase**
>
> Native binary installation is currently in Beta testing phase, and features are still being improved.
> If you encounter any issues, please submit an issue report on the [Issues page](https://cnb.cool/codebuddy/codebuddy-code/-/issues), or contact technical support (codebuddy@tencent.com).

#### Features

Native binary installation provides the following features compared to the npm version:

- Single executable file with no additional dependencies
- No Node.js runtime required
- Improved automatic update mechanism

#### Supported Platforms

- macOS (Apple Silicon M1/M2/M3 or Intel x86_64)
- Linux (arm64 or x86_64)
- Windows (x86_64)

#### Migrating from npm Version

If you have already installed CodeBuddy Code via npm, you can migrate to the native binary version using the following command:

```bash
codebuddy install
```

#### Fresh Installation

::: code-group

```bash [macOS / Linux]
curl -fsSL https://www.codebuddy.cn/cli/install.sh | bash
```

```powershell [Windows]
irm https://www.codebuddy.cn/cli/install.ps1 | iex
```

:::

#### Verify Installation

The installation script will automatically download the latest version and configure environment variables. After installation, run the following command to verify:

```bash
codebuddy --version
```

**If the command is not available**, manually add the installation path to the `PATH` environment variable:

::: code-group

```bash [macOS / Linux]
export PATH="$HOME/.local/bin:$PATH"

# For permanent effect, it's recommended to add to your shell configuration file:
# Bash: ~/.bashrc or ~/.bash_profile
# Zsh: ~/.zshrc
```

```powershell [Windows]
# Add the following path to user environment variables:
# %USERPROFILE%\AppData\Local\codebuddy\bin
```

:::


## 📁 Configuration Directory

CodeBuddy Code stores configuration files in the following directory by default:

| Platform | Default Configuration Directory |
|------|-------------|
| macOS / Linux | `~/.codebuddy` |
| Windows | `%USERPROFILE%\.codebuddy` |

### Directory Contents

```
~/.codebuddy/
├── settings.json      # User settings
├── mcp.json           # MCP server configuration
├── .mcp.json          # MCP server configuration (alternative location)
└── skills/            # User-defined Skills
```

### Custom Configuration Directory

You can customize the configuration directory location by setting the `CODEBUDDY_CONFIG_DIR` environment variable:

```bash
export CODEBUDDY_CONFIG_DIR="$HOME/.my-codebuddy-config"
```

This is useful in the following scenarios:

- Multiple CodeBuddy instances need independent configurations
- Enterprise environments that require centralized configuration management
- Avoiding configuration conflicts when coexisting with other applications using the CodeBuddy engine (such as WorkBuddy)


## 🔄 Updates

### Automatic Updates

CodeBuddy Code automatically stays up to date by default to ensure you have the latest features and security fixes.

#### Disable Automatic Updates

To disable automatic updates, set the environment variable:

```bash
export DISABLE_AUTOUPDATER=1
```

### Manual Updates

Use the following command to manually update to the latest version:

```bash
codebuddy update
```

The `update` command will automatically detect your installation method and perform the corresponding update operation.

#### Update via Package Manager

If the `codebuddy update` command fails to update successfully, you can also reinstall using your package manager:

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

Or use the corresponding installation command with other package managers (pnpm, yarn, bun).


## 🔧 Troubleshooting

### Command Not Available

**Issue:** After installation, you get `codebuddy: command not found`

**Solution:**

1. Check if the installation path is in the `PATH` environment variable:
   ```bash
   echo $PATH
   ```

2. Add the CodeBuddy installation path to `PATH` (refer to the [Verify Installation](#verify-installation) section above)

3. Restart your terminal or reload the configuration file:
   ```bash
   source ~/.bashrc  # or ~/.zshrc
   ```

### Network Issues

**Issue:** Network connection failure during installation or update

**Solution:**

1. Check network connection
2. Configure npm registry mirror (if installing via npm):
   ```bash
   npm config set registry https://registry.npmmirror.com
   ```

## 🗑️ Uninstallation

### Uninstall Package Manager Version

::: code-group

```bash [Homebrew]
# Uninstall tool
brew uninstall codebuddy-code

# Remove tap (optional)
brew untap Tencent-CodeBuddy/tap
```

```bash [npm]
npm uninstall -g @tencent-ai/codebuddy-code
```

```bash [pnpm]
pnpm remove -g @tencent-ai/codebuddy-code
```

```bash [yarn]
yarn global remove @tencent-ai/codebuddy-code
```

```bash [bun]
bun remove -g @tencent-ai/codebuddy-code
```

:::

### Uninstall Native Binary Version

#### macOS / Linux

Remove the executable file:

```bash
rm -f ~/.local/bin/codebuddy
```

### Clean Configuration Files (Optional)

For complete cleanup, you can delete the configuration directories:

**macOS / Linux:**
```bash
rm -rf ~/.codebuddy
rm -rf ~/.local/share/codebuddy
```

> 💡 **Tip:** If you customized the configuration directory using the `CODEBUDDY_CONFIG_DIR` environment variable, delete the corresponding directory as well.
