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 is recommended on Windows. If missing, CodeBuddy Code will print a one-time prompt at startup and automatically fall back to PowerShell for shell command execution. Git Bash-specific features such as /enter-worktree and /leave-worktree will be unavailable.

• 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"

If the path pointed to by CODEBUDDY_CODE_GIT_BASH_PATH does not exist, the behavior depends on CODEBUDDY_SKIP_GIT_BASH_CHECK: by default (not set to 1), it is treated as an explicit user configuration error, and the program exits with an error at startup; when set to 1 (e.g., when an upstream process has already taken over the shell, in which case the variable may have been written by a third-party program such as UGit and became invalid after its upgrade), the conversation is not interrupted — instead, a warning is logged to ~/.codebuddy/logs and it automatically falls back to auto-detected Git Bash / PowerShell. To completely eliminate the warning, remove the environment variable or correct it to a valid path.

Suppress startup prompt (e.g., when an upstream process already manages the shell):

# PowerShell
$env:CODEBUDDY_SKIP_GIT_BASH_CHECK="1"

"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

---

Permission Confirmation Dialog Unresponsive / Only ESC Closes It

Symptom: The TUI shows a tool permission confirmation dialog. Pressing number keys / Enter to confirm doesn't dismiss the dialog, but ESC closes it normally — and after closing, the task has actually already started executing.

Log Location

ls -t ~/.codebuddy/logs/codebuddy-*.log | head -1   # latest log

You can relocate the entire config directory via the CODEBUDDY_CONFIG_DIR environment variable.

Key TAGs (in chronological order)

A normal confirmation flow should produce the following sequence (grep -E '\[Approve\]|\[Reject\]|\[dequeue\]|\[tool-permission\]'):

TAG	Meaning
[tool-permission] ASK ...	A tool was intercepted and requires approval
[HandleInterruptions] Approval dialog shown	TUI has displayed the dialog
[Approve] User approved tool: <name>	User clicked confirm
[Approve] Deferred resolved	Backend promise has been resolved (task starts executing here)
[dequeue] Queue empty, clearing interruptionSubject	pending$ cleared, dialog should disappear
[Approve] Success: ... interruption dequeued	Full flow finished

The ESC path replaces [Approve] with [Reject].

Symptom -> Inference

You see	Inference
Full TAG sequence present but dialog doesn't disappear	UI rendering is stuck (e.g., IDE closeTab RPC blocking await)
[Approve] User approved present but [dequeue] missing	findSessionByItem failed; nearby logs will show [Approve] Failed: Cannot find session
dequeue Start present but no Queue empty	interruptionQueues cannot fetch the queue (multi-session mismatch)
No [tool-permission] ASK at all	The tool didn't go through approval — possibly BypassPermissions or allowed by allow rules
[tool-permission] ASK present but no Approval dialog shown	TUI didn't subscribe to pending$ (teammate concurrent session mismatch)
[Approve] Failed: No pending deferred found	Deferred was consumed twice

Minimum Info to Report to Developers

30 consecutive lines of logs around the timestamp of the [Approve] / [Reject] / [dequeue] TAGs are enough to determine whether the UI didn't refresh, the backend didn't dequeue, or the IDE RPC is stuck.

---

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

Cannot Update to the Latest Version

If codebuddy update or npm install -g @tencent-ai/codebuddy-code@latest consistently fails to fetch the latest version, the issue is usually caused by npm mirror cache delays. You can specify the official registry to retry:

npm install -g @tencent-ai/codebuddy-code@latest --registry=https://registry.npmjs.org/

Check the npm registry currently configured locally:

npm config get registry

If you regularly use a third-party mirror, you can temporarily specify the official registry in the update command without modifying the global configuration.

npm Install Succeeds but Old Version Still Executes

Symptom: npm install -g @tencent-ai/codebuddy-code@latest shows installation success, but codebuddy --version still shows the old version.

Cause: Multiple codebuddy executables exist on the system, and the terminal finds the old version first. Common scenarios:

• Installed via both npm and Homebrew simultaneously, with Homebrew version having higher priority
• Switched Node versions using nvm; the new version was installed under a different Node version's bin directory
• Leftover old native binary files on the system (~/.local/bin/codebuddy)
• Multiple paths in PATH containing different versions of codebuddy

Troubleshooting steps:

# 1. Confirm which codebuddy is actually being executed
which codebuddy
# Or view all matches
which -a codebuddy

# 2. Confirm npm global installation path
npm prefix -g
# npm-installed codebuddy is under $(npm prefix -g)/bin/

# 3. Compare paths
# If the path from "which codebuddy" ≠ $(npm prefix -g)/bin/codebuddy,
# it means the terminal is not executing the npm-installed version

Solutions:

Case 1: Both Homebrew and npm installed

Homebrew's /opt/homebrew/bin (macOS Apple Silicon) or /usr/local/bin (Intel Mac) typically has higher priority in PATH than npm's global directory.

# Option A: Keep only one installation method (recommended)
brew uninstall codebuddy-code          # Uninstall Homebrew version, use npm version
# Or
npm uninstall -g @tencent-ai/codebuddy-code  # Uninstall npm version, use Homebrew version
brew upgrade codebuddy-code

# Option B: Keep both installations but specify priority
# Adjust PATH order in ~/.zshrc or ~/.bashrc, placing the npm path first:
export PATH="$(npm prefix -g)/bin:$PATH"

Case 2: nvm Node version switch

npm global packages are installed under the current Node version's directory. After switching Node versions, global packages installed under previous versions are unavailable.

# Check current Node version
node -v

# Reinstall under the current version
npm install -g @tencent-ai/codebuddy-code@latest

# Or switch back to the Node version used during installation
nvm use <version-used-during-installation>

Case 3: Leftover old native binary files

# Check if a native binary version exists
ls -la ~/.local/bin/codebuddy

# If it exists and is not needed, delete it
rm ~/.local/bin/codebuddy

Case 4: Shell cached old path

Some shells cache command paths. After installing a new version, you need to refresh the cache:

hash -r                    # bash / zsh clear command cache
# Or simply restart the terminal

Quick verification:

# One command to complete troubleshooting
echo "Execution path: $(which codebuddy)" && \
echo "Current version: $(codebuddy --version 2>/dev/null || echo 'not found')" && \
echo "npm install path: $(npm prefix -g)/bin/codebuddy" && \
echo "npm version: $(cat "$(npm prefix -g)/lib/node_modules/@tencent-ai/codebuddy-code/package.json" 2>/dev/null | grep '"version"' || echo 'not installed via npm')" && \
echo "All codebuddy: $(which -a codebuddy 2>/dev/null || where codebuddy 2>/dev/null)"

If the issue persists after troubleshooting, please submit the output of the above commands to the Issues page.

---

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