# Troubleshooting and Best Practices

This document covers common problem solutions and usage optimization tips.


## 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:

```bash
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:

```bash
# 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

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

### Version Check

```bash
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.

```bash
# 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
```

```powershell
# 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.

```bash
# 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
```

```powershell
# 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

```bash
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](./quickstart.md)
