# 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

---

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

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

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

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

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

Check the npm registry currently configured locally:

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

---

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