Troubleshooting and 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 at: https://nodejs.org/en/download/

Windows Platform

Git Bash Dependency

Git Bash must be installed on Windows.

• Download: https://git-scm.com/downloads/win
• Check the "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"

The npm global directory is not in PATH.

npm config get prefix    # Find installation path

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

Search Tool (Ripgrep)

CodeBuddy automatically handles the ripgrep dependency; no manual installation is needed. For optimal performance:

# macOS
brew install ripgrep

# Windows
choco install ripgrep

# Ubuntu/Debian
sudo apt install ripgrep

---

Common Issues

Shared Quota

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] # Switch directly
/status             # View current model

--serve Mode Network Access Issues

LAN IP Access Returns ERR_EMPTY_RESPONSE

Symptom: After starting with codebuddy --serve, accessing via LAN IP (e.g., http://10.31.110.26:52477) results in ERR_EMPTY_RESPONSE in the browser.

Cause: The HTTP server listens on 127.0.0.1 (loopback address) by default, accepting only local connections. When accessing via LAN IP, the request reaches the machine but is rejected by the service.

Solution: Add the --host 0.0.0.0 parameter at startup to listen on all network interfaces:

codebuddy --serve --host 0.0.0.0 --port 8080

Password authentication is automatically enabled when starting on a non-loopback address. The password is visible in the console output.

Verify Service Listening Status

You can check if the service is listening correctly with:

# macOS / Linux
lsof -i :PORT_NUMBER

# Or
netstat -an | grep PORT_NUMBER

• If showing 127.0.0.1:PORT — accepts local connections only
• If showing 0.0.0.0:PORT or *:PORT — accepts all network connections

---

Updates

Auto Updates

Enabled by default; new versions are automatically applied on next startup. Manage the toggle 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 in both.

# 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 admin 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; changes don't affect each other.

# 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 and are automatically loaded after installation.

Verify Migration

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

---

Cost Optimization

Core Principles

• Use /clear to start a new session for new tasks
• Use /compact to compress history for long conversations
• Use @filename to reference files instead of pasting code

Session Management Commands

Command	Function
/cost	View token consumption
/clear	Start a new session
/compact	Compress history
/resume	Resume a previous conversation

Cost Comparison

Approach	Input Tokens	Relative Cost
10 tasks in a single session	~50,000	High
New session per task	~15,000	Low
Periodic /compact	~25,000	Medium

Recommended Practices

• Do start a new session for new tasks
• Do use /compact every 20-30 turns
• Do use @filename to reference files
• Do keep prompts concise

Avoid

• Don't handle multiple unrelated tasks in the same session
• Don't go beyond 30 turns without cleanup
• Don't repeatedly paste known code

---

More help: Quick Start Guide