debug · git:20261116.c35b66a · 2026-11-16 · sha256 6cf4cf87cc46e440
debug git:20261116.c35b66aA
Immutable. This exact content never changes and is served at /api/v1/blob/6cf4cf87cc46e440.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_5htxgvubwnfhcf6w/6cf4cf87cc46e440340c57ac4cc40c7ce9b85385f533007aacbb152bccaf213e.json
Then /plugin install debug@markdownregistry-5htxgvubwnfhcf6w in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
---
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)