---
name: debug
description: Diagnose koda issues — checks provider config, API connectivity, settings, and environment.
tags: [debug, diagnostics, troubleshooting, config]
when_to_use: Use when koda is misbehaving — wrong provider, API errors, tools not working, unexpected behaviour. Describe the issue and this skill will guide a systematic diagnosis.
argument_hint: [issue description, e.g. "API calls are failing with 401"]
allowed_tools: [Read, Grep, Glob, List, Bash]
user_invocable: true
---

# Debug: Diagnose Koda Issues

Help the user diagnose an issue they're encountering with koda. Work through the checklist below, run each command, and report findings. Do not skip steps — a step that passes is still useful information.

## Issue Description

The user's issue: {{args}}

If no issue was described, read the config, logs, and environment and summarise anything that looks wrong.

## Step 1: Session Log

Koda logs to a database, `~/.config/koda/db/logs_1.db`, which `koda-logs` reads. Each line is filed under the session it was logged in:

```bash
# The newest lines, every session
koda-logs --backfill 50 2>/dev/null || echo "(no log database found)"

# Errors and warnings from the last two hours
koda-logs --level warn --since 2h
```

If `config.toml` sets `log_dir`, the same lines are also in `<log_dir>/koda.log`.

## Step 2: Environment and API Keys

Check which provider is configured and whether its key is present:

```bash
# Show relevant env vars (mask actual key values)
env | grep -E "KODA|OPENAI|ANTHROPIC|GEMINI|GROQ|MISTRAL|DEEPSEEK|FIREWORKS|TOGETHER|API_KEY|API_BASE" | sed 's/=.*/=<set>/'
```

Common issues:
- Key env var not set → `export OPENAI_API_KEY=...` (or whichever provider)
- Key set but for wrong provider → check `~/.config/koda/settings.toml` for the active provider
- Custom base URL pointing to unreachable endpoint

## Step 3: Settings File

Read the koda settings file:

```bash
cat ~/.config/koda/settings.toml 2>/dev/null || echo "(no settings.toml found — using defaults)"
```

Check for:
- `provider` — is it what the user expects?
- `model` — does it exist on that provider?
- `base_url` — is it reachable?

## Step 4: Agent and Skill Config

List any user-level agent or skill overrides:

```bash
ls ~/.config/koda/agents/ 2>/dev/null && echo "---agents above---" || echo "(no user agents)"
ls ~/.config/koda/skills/ 2>/dev/null && echo "---skills above---" || echo "(no user skills)"
```

If custom agents exist, read any that seem relevant to the issue.

## Step 5: API Connectivity Test

Test raw connectivity to the configured provider endpoint. Use the base URL from settings.toml or the provider default:

```bash
# OpenAI-compatible (OpenAI, Groq, Fireworks, local LM Studio, etc.)
curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  https://api.openai.com/v1/models 2>&1 | head -5

# Anthropic
curl -s -o /dev/null -w "%{http_code}" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  https://api.anthropic.com/v1/models 2>&1
```

Expected: HTTP 200. Common failures:
- 401 → wrong or missing API key
- 403 → key exists but no access to model
- 000 or connection refused → network issue, wrong base URL, VPN required

## Step 6: Memory Files

Check whether memory files exist and are well-formed:

```bash
wc -l ~/.config/koda/AGENTS.md 2>/dev/null || echo "(no global instructions)"
wc -l ./AGENTS.md ./CLAUDE.md 2>/dev/null || echo "(no project instructions)"
ls ~/.config/koda/memories/ 2>/dev/null || echo "(no saved notes)"
wc -l ./CLAUDE.md 2>/dev/null || echo "(no CLAUDE.md)"
```

Large memory files (>500 lines) can cause context overflow. If suspiciously large, read the first 50 lines.

## Step 7: Summarise Findings

After running all steps, provide:

1. **Root cause** (if found) — be specific
2. **Fix** — exact command or change needed
3. **If unresolved** — what additional information to collect:
   - Run koda with `RUST_LOG=koda_core=debug,koda_cli=debug koda ...` and share the resulting log file
   - Or set `RUST_LOG=debug` for maximum verbosity (very noisy)
