Troubleshooting & Best Practices

This document covers common problem solutions and usage optimization tips.

---

Installation Issues

Node.js Version Requirements

CodeBuddy Code requires Node.js v18.20 or higher.

node -v          # Check version

Upgrade URL: https://nodejs.org/en/download/

Windows Platform

Git Bash Dependency

Git Bash must be installed on Windows platforms.

• Download: https://git-scm.com/downloads/win
• Select "Git Bash" component during installation

Custom Path (non-standard installation location):

# CMD
set CODEBUDDY_CODE_GIT_BASH_PATH=C:\Program Files\Git\bin\bash.exe

# PowerShell
$env:CODEBUDDY_CODE_GIT_BASH_PATH="C:\Program Files\Git\bin\bash.exe"

"codebuddy is not recognized as an internal or external command"

npm global directory is not added to PATH.

npm config get prefix    # Find installation path

Add the path to system PATH (default: %USERPROFILE%\AppData\Roaming\npm), then restart the terminal.

Search Tool (Ripgrep)

CodeBuddy automatically handles ripgrep dependency, no manual installation required. For optimal performance:

# macOS
brew install ripgrep

# Windows
choco install ripgrep

# Ubuntu/Debian
sudo apt install ripgrep

---

Common Issues

Quota Sharing

CLI, CodeBuddy IDE, and CodeBuddy Plugin share the same account's resource quota.

ESC Key Not Working in JetBrains IDE

JetBrains terminal handles the ESC key differently. Use Ctrl+ESC or Shift+ESC instead.

Action	Standard Terminal	JetBrains Terminal
Exit/Cancel	ESC	Ctrl+ESC or Shift+ESC

Model Switching

/model              # Interactive selection
/model [model-name] # Direct switch
/status             # View current model

---

Updates

Automatic Updates

Enabled by default, new versions are automatically applied at next startup. Manage the setting via /config.

Manual Update

codebuddy update                                    # Built-in command (recommended)
npm install -g @tencent-ai/codebuddy-code@latest   # npm update

Version Check

codebuddy --version                                 # Current version
npm view @tencent-ai/codebuddy-code version        # Latest version

---

Migrating from Claude Code

Migration Content

Directory/File	Description
agents/	Custom agents configuration
commands/	Slash command definitions
skills/	Skill definitions
CLAUDE.md → CODEBUDDY.md	AI instructions and memory documents

Option 1: Symbolic Links (Recommended)

Share configuration, changes in one place take effect on both sides.

# macOS/Linux
cd ~/.codebuddy
ln -s ~/.claude/agents agents
ln -s ~/.claude/commands commands
ln -s ~/.claude/skills skills
ln -s ~/.claude/CLAUDE.md CODEBUDDY.md

# Windows (requires administrator privileges)
cd $env:USERPROFILE\.codebuddy
New-Item -ItemType SymbolicLink -Path agents -Target $env:USERPROFILE\.claude\agents
New-Item -ItemType SymbolicLink -Path commands -Target $env:USERPROFILE\.claude\commands
New-Item -ItemType SymbolicLink -Path skills -Target $env:USERPROFILE\.claude\skills
New-Item -ItemType SymbolicLink -Path CODEBUDDY.md -Target $env:USERPROFILE\.claude\CLAUDE.md

Option 2: Copy Files

Independent configuration, no mutual interference.

# macOS/Linux
cp -r ~/.claude/agents ~/.codebuddy/agents
cp -r ~/.claude/commands ~/.codebuddy/commands
cp -r ~/.claude/skills ~/.codebuddy/skills
cp ~/.claude/CLAUDE.md ~/.codebuddy/CODEBUDDY.md

# Windows
Copy-Item -Recurse $env:USERPROFILE\.claude\agents $env:USERPROFILE\.codebuddy\agents
Copy-Item -Recurse $env:USERPROFILE\.claude\commands $env:USERPROFILE\.codebuddy\commands
Copy-Item -Recurse $env:USERPROFILE\.claude\skills $env:USERPROFILE\.codebuddy\skills
Copy-Item $env:USERPROFILE\.claude\CLAUDE.md $env:USERPROFILE\.codebuddy\CODEBUDDY.md

One-Click Plugin Skills Installation

Skills from Claude Code plugins support one-click installation, automatically loaded after installation.

Verify Migration

codebuddy         # Start
/skills           # Check Skills
/config           # View configuration

---

Cost Optimization

Core Principles

• Use /clear to start new sessions for new tasks
• Use /compact to compress history for long conversations
• Use @filename to reference files, avoid pasting code

Session Management Commands

Command	Function
/cost	View Token consumption
/clear	Start new session
/compact	Compress history
/resume	Resume old conversation

Cost Comparison

Method	Input Tokens	Relative Cost
Single session, 10 consecutive tasks	~50,000	High
New session per task	~15,000	Low
Periodic /compact	~25,000	Medium

Recommended Practices

• ✓ Start new session for new tasks
• ✓ Use /compact every 20-30 rounds
• ✓ Use @filename to reference files
• ✓ Keep questions concise

Avoid

• ✗ Handle multiple unrelated tasks in the same session
• ✗ Let conversations exceed 30 rounds without cleanup
• ✗ Repeatedly paste known code

---

More Help: Quick Start Guide